Coding-Agent Monitoring Needs Semantic Time, Not Just Process Liveness

You're watching a coding agent work. The terminal shows it's running. The CPU meter ticks. But is it actually doing anything right now, or is it waiting for you to approve a change? Is it finished, or did it just start a new task? These questions sound simple until you're managing five agent sessions at once and need to know which one deserves your attention.

This is the central problem in agent observability: a process can be alive without being productive, and it can appear finished while already processing a new instruction. Traditional monitoring systems were built to answer a simpler question—does this process exist?—by checking whether it consumes CPU, writes files, or emits logs. Those signals matter, but they don't answer what a developer actually needs to know: should I return to this session now?

The gap widens when you run multiple coding agents in parallel. Instead of repeatedly checking each terminal, developers rely on a status display to direct them to the session that needs attention. At that scale, a wrong signal isn't a minor inconvenience. It sends you to the wrong place, wastes your time, and breaks your workflow. A process marked "finished" when it's actually waiting for input creates alerts that are technically accurate but operationally useless.

The solution requires rethinking what "state" means for a coding agent. Rather than treating the entire process lifetime as a single unit, the monitor should model each session as a state machine keyed to individual turns of work. A session can be actively working, waiting for human input, finished with a turn, stalled without progress, or intentionally rate-limited. Critically, it can move from finished back to working the moment a new instruction arrives. The process itself might never stop; only the current turn ends.

To track this accurately, a monitor needs to combine multiple weak signals instead of trusting any single timestamp. Process state shows whether a session can still be active. Filesystem activity reveals whether transcripts or session records are changing. Structured events expose user turns, assistant responses, tool calls, completion markers, and rate-limit notices. Each source has different failure modes—process IDs can be reused, filesystem timestamps can change due to metadata updates, event streams can replay after a restart—so the monitor should treat every observation as evidence, not as a complete answer.

The harder problem is semantic time: the difference between when an event was observed and where it belongs in the session's causal order. Imagine a completion event written at 10:01:00, followed by a new user instruction at 10:01:01, but the filesystem watcher doesn't report the completion until 10:01:02. A monitor sorting only by wall-clock time might incorrectly restore the "finished" state after new work has already begun. Instead, the monitor should attach events to a turn identity or a monotonically advancing session sequence. A later user turn invalidates completion from an earlier turn, even if the completion event arrives late. This is explicit retraction: old evidence remains historically true, but it no longer describes the present.

Completion itself should behave like a lease, valid only while no newer instruction, activity, or wait state has superseded it. New evidence revokes the lease immediately. This design also prevents duplicate alerts when logs or event streams replay the same completion marker—the monitor can deduplicate using turn identity and event fingerprint. Without that check, a process restart can make old work appear newly finished and inflate usage totals.

The waiting state deserves special attention because it's the state most likely to require action. A process can remain alive and consume almost no CPU while an agent waits for approval, clarification, authentication, or a tool decision. The monitor should distinguish between detecting a wait state—a correctness problem—and deciding whether to notify—a user-experience problem. Keeping them separate makes both easier to test and tune.

Sensitive information like session transcripts, prompts, and file paths should not leave the machine merely to answer whether a session is working or waiting. Local observation reduces dependence on network availability and hosted integrations. The tradeoff is handling platform-specific process and filesystem behavior, but that cost is manageable when the state model is shared and only the signal adapters differ. Testing should replay adversarial sequences: completion followed immediately by a new turn, delayed filesystem events, process restarts that replay old records, and wait states while the editor is frontmost. For each sequence, assert both the final state and whether an alert should fire. These tests target the failures users actually notice. The foundation of reliable agent observability is not a faster timestamp. It is a state model that answers what the developer needs to do next.