Parked/Awaiting-Agent Signal in no-mistakes: How Pipeline Gates Pause for Human Review

The parked/awaiting-agent signal in no-mistakes is a nullable Unix-seconds timestamp stored in the AwaitingAgentSince column of the runs table that indicates when a pipeline run entered a gate awaiting human intervention, enabling external tools to observe and format the parked duration without affecting the underlying step state machine.

The no-mistakes pipeline execution system sequences steps that may pause at gates requiring human-driven agents for reviews, fixes, or responses. When a run reaches such a gate, the executor records the parked/awaiting-agent signal to mark the exact moment the run began waiting. This signal provides deterministic observability for CLI tools, web interfaces, and automation daemons while keeping the step's state machine logic decoupled from timing concerns.

What Is the Parked/Awaiting-Agent Signal?

The signal is implemented as a nullable int64 Unix timestamp in the database schema defined in internal/db/run.go. Specifically, the runs table contains an AwaitingAgentSince column that stores the seconds since epoch when the run entered an awaiting-agent state.

Key characteristics of the implementation:

• Nullability: When NULL, the run is not parked; when populated, it indicates active waiting.
• Persistence: Stored in SQLite, surviving daemon restarts and enabling historical analysis.
• Non-invasive: The timestamp exists outside the step state machine, preventing side effects on business logic.

How the Signal Works: Gate Entry and Exit

The lifecycle of the parked signal follows strict setter and getter patterns implemented in the database layer.

Entering the Parked State

When the executor encounters a gate requiring human intervention, it calls db.SetRunAwaitingAgent(run.ID) to persist the current Unix timestamp. This operation occurs in internal/pipeline/executor.go at the moment the run transitions into the awaiting-agent phase.

// internal/pipeline/executor.go – gate entry handling
if dbErr := e.db.SetRunAwaitingAgent(run.ID); dbErr != nil {
    return fmt.Errorf("mark run as awaiting agent: %w", dbErr)
}

Exiting the Parked State

Upon agent response or cancellation, the executor clears the flag via db.ClearRunAwaitingAgent(run.ID), which resets AwaitingAgentSince to NULL.

// internal/pipeline/executor.go – after agent response
if dbErr := e.db.ClearRunAwaitingAgent(run.ID); dbErr != nil {
    return fmt.Errorf("clear awaiting-agent flag: %w", dbErr)
}

Crash Recovery Safety

To prevent stale parked states after crashes, db.RecoverStaleRuns automatically clears the AwaitingAgentSince field during startup recovery. This ensures that resurrected runs never falsely appear as awaiting an agent.

Observability and Client Consumption

The signal propagates through the IPC protocol to reach end-user tools, providing both machine-readable data and human-readable formatting.

IPC Representation

The daemon exposes the parked state through the ipc.RunInfo struct defined in internal/ipc/protocol.go. This structure includes an AwaitingAgent boolean and the awaiting_agent_since timestamp for programmatic access.

// Programmatic inspection via IPC client
info, _ := ipcClient.RunInfo(ctx, runID)
if info.AwaitingAgent {
    fmt.Printf("Run %s has been parked for %d seconds\n",
        runID, *info.AwaitingAgentSince)
}

CLI Rendering

The CLI renderer in internal/cli/axi_render.go formats the parked duration for human readability. When rendering a run status, it adds an awaiting_agent field to the TOON object using the formatParkedFor helper function, displaying durations like 5m23s.

# List runs; parked runs show an "awaiting_agent" field

no-mistakes axi status --run <run-id>

Expected output includes:

awaiting_agent: 5m23s

Testing and Validation

The behavior is verified by comprehensive tests confirming the signal's presence during waiting periods and absence after resolution. The internal/e2e/axi_journey_test.go file confirms that the timestamp appears while a run is parked and disappears after the agent responds. Unit tests in internal/db/run_test.go verify that SetRunAwaitingAgent stores a non-nil timestamp and ClearRunAwaitingAgent properly removes it.

Summary

• The parked/awaiting-agent signal is a Unix-seconds timestamp in the AwaitingAgentSince column of the runs table defined in internal/db/run.go.
• db.SetRunAwaitingAgent(run.ID) sets the signal when entering a gate; db.ClearRunAwaitingAgent(run.ID) clears it upon exit.
• The signal surfaces in ipc.RunInfo as AwaitingAgent (boolean) and awaiting_agent_since (timestamp) according to internal/ipc/protocol.go.
• The CLI renders parked duration via formatParkedFor in internal/cli/axi_render.go.
• Crash recovery via db.RecoverStaleRuns ensures the signal never persists incorrectly after restarts.

Frequently Asked Questions

How do I check if a run is currently parked awaiting an agent?

Use the CLI command no-mistakes axi status --run <run-id> and look for the awaiting_agent field in the output. If present, the run is parked and the value shows the duration (e.g., 5m23s). Programmatically, query the daemon's IPC endpoint for RunInfo and check if the AwaitingAgent boolean is true.

What happens to the awaiting-agent signal if the executor crashes?

The db.RecoverStaleRuns function clears the AwaitingAgentSince field during startup recovery. This prevents runs from falsely appearing as parked after a crash, ensuring that only actively waiting runs carry the timestamp.

Can I programmatically detect how long a run has been parked?

Yes. Through the IPC protocol defined in internal/ipc/protocol.go, the RunInfo struct exposes awaiting_agent_since as a Unix timestamp. Subtract this value from the current time to calculate the exact duration in seconds that the run has been awaiting an agent.

Where is the parked timestamp stored in the database?

The timestamp is stored in the AwaitingAgentSince column of the runs table, defined in internal/db/run.go. This nullable int64 field stores Unix epoch seconds when the run is parked, and remains NULL when the run is active or completed.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}