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

> Understand the parked/awaiting-agent signal in no-mistakes. Learn how this timestamp pauses pipeline runs for human review, allowing external tools to track durations effectively.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: how-to-guide
- Published: 2026-07-02

---

**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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/executor.go) at the moment the run transitions into the awaiting-agent phase.

```go
// 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`.

```go
// 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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/ipc/protocol.go). This structure includes an `AwaitingAgent` boolean and the `awaiting_agent_since` timestamp for programmatic access.

```go
// 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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`.

```bash

# 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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/ipc/protocol.go).
- The CLI renders parked duration via `formatParkedFor` in [`internal/cli/axi_render.go`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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.