feat: expose durable material-progress inspection

[timigod]

Linked discussion

Discussion #2690: Workflow: distinguish material agent progress from transport activity.

This replaces draft PR #2689 with the material-progress capability only. Provider-history hydration, quarantine, and lifecycle reconciliation are deliberately excluded into separate review units.

Type of change

• Bug fix
• New feature
• Enhancement
• Refactor
• Docs

What does this PR do

Adds a provider-agnostic, read-only materialProgress snapshot to the existing agent protocol and paseo agent inspect path. The snapshot reports whether the current continuation has made material progress, the latest material event, and whether repeated compaction without useful output has reached warning or stalled state.

Material progress includes completed edits and writes, concrete read/search/fetch evidence, successful shell verification with output, non-empty explicit decisions, and a completed turn's terminal assistant deliverable. Stable result fingerprints prevent repeated identical activity from resetting the compaction count. Failed, empty, missing-output, and no-op activity remains non-material.

The state is persisted with the agent record, survives worker collection/archive/restart, and is protected against older queued snapshots overwriting a newer continuation. A live agent's explicit null turn outcome is authoritative while a new turn is running, so stale persisted completion cannot classify in-progress work as terminal.

The manager also persists its own accepted-start timeline boundary before publishing the running state. Inspection therefore does not depend on a provider first projecting a user_message row. Duplicate/pre-resolution turn_started events cannot move that boundary past already-emitted events, and the foreground waiter is installed before the durable write so a fast terminal event cannot strand the stream. Legacy records without the boundary retain the latest-user-message fallback.

This PR does not stop, retry, route, archive, or otherwise control an agent. Downstream patch receipts and machine-specific state are excluded from the upstream diff.

The candidate was first reconstructed directly on official stable v0.2.5 (6fc491e6220fba6543bbbe4bf1b1f58cfe59228b) and then merged normally with upstream main; follow-up review repairs and regression proof were committed normally on top. No commit was rewritten or force-pushed.

Exact submitted head: 65c98a30a74f8639c0827f7deec50c75b9546a5b.

Exact submitted tree: 243d20df8ab720b3df2d3c04a6bd9bbe01434923.

Accepted-start boundary source repair: a045df727f6a161c17998714fcd1322f90bba032.

How did you verify it

All latest repair commands used Node 24.18.1 against the exact submitted head.

• Directly affected suite: 3 files, 22 tests passed.
  • Protocol material-progress schema: 5
  • Material-progress classifier: 11
  • Daemon/client end-to-end: 6
• Regressions prove that distinct read/search/fetch evidence, successful test/build/typecheck output, and explicit decisions keep a continuation progressing across compactions.
• Regressions also prove that repeated identical reads still stall after two compactions and that empty, failed, missing-output, or no-op tools and commentary do not count.
• Earlier continuation-boundary and persistence proof remains covered by the existing CLI, protocol, agent-storage, agent-manager, classifier, and daemon/client suites.
• Server build passed.
• Repository-wide all-workspace typecheck passed, including the pre-commit rerun.
• Repository-wide lint passed with 0 warnings and 0 errors, including the pre-commit changed-file rerun.
• Repository-wide formatting and git diff --check passed.
• GitHub's PR file list contains only generic docs, CLI, protocol, and server changes; the downstream patch manifest is absent.

Tested on macOS. No UI, desktop bundle, mobile runtime, daemon installation, or live agent state is changed or activated.

Checklist

• One focused change
• npm run typecheck passes
• npm run lint passes
• Formatting passes
• QA evidence
• Tests added or updated where it made sense

This contribution was developed with AI assistance. I reviewed the final diff and ran the commands reported above against the exact submitted branch.

[greptile-apps]

Greptile Summary

This PR exposes and durably persists provider-independent material-progress inspection.

• Adds the material-progress wire schema and CLI inspection output.
• Derives progress from continuation-scoped timeline events and terminal outcomes.
• Persists continuation boundaries, outcomes, and classifications across archival and restart.
• Adds manager, storage, protocol, CLI, and daemon-level regression coverage.

Confidence Score: 4/5

The PR is not yet safe to merge because an older delayed terminal event can still overwrite the outcome of a newer running continuation.

The terminal handlers assign lastTurnOutcome and end material-progress tracking without confirming that the event belongs to the active continuation; the existing finalized-turn guard does not cover every older or background turn, so stale completion can still make current work appear terminal.

Files Needing Attention: packages/server/src/server/agent/agent-manager.ts

Important Files Changed

Filename	Overview
packages/server/src/server/agent/agent-manager.ts	Adds continuation-boundary and outcome lifecycle management, but the previously reported stale-terminal-event overwrite remains reachable.
packages/server/src/server/agent/material-progress.ts	Introduces the timeline-based material-progress classifier and terminal assistant-result semantics.
packages/server/src/server/agent/agent-storage.ts	Extends durable agent records and snapshot persistence for progress state, continuation boundaries, and outcomes.
packages/protocol/src/messages.ts	Adds the optional validated material-progress payload to agent snapshots.
packages/server/src/server/session.ts	Attaches the manager-derived material-progress snapshot to inspection responses.
packages/cli/src/commands/agent/inspect.ts	Exposes structured material progress and a concise state-and-reason table row.

Sequence Diagram

sequenceDiagram
    participant Provider
    participant Manager as AgentManager
    participant Timeline
    participant Storage
    participant Inspect
    Provider->>Manager: turn_started(turnId)
    Manager->>Timeline: capture continuation boundary
    Manager->>Storage: persist cleared outcome and boundary
    Provider->>Manager: timeline events
    Manager->>Timeline: append events
    Manager->>Storage: persist derived material progress
    Inspect->>Manager: getMaterialProgressSnapshot
    Manager->>Timeline: resolve continuation rows
    Manager->>Storage: read retained classification
    Manager-->>Inspect: materialProgress snapshot

Loading

_{Reviews (3): Last reviewed commit: "test: cover failed continuation boundary" | Re-trigger Greptile}

[timigod]

Greptile found a blocking stale-outcome fallback at the exact current head: an explicit live null outcome for a newly running turn can be replaced by the prior persisted completion, misclassifying in-progress work as terminal. I have returned the PR to draft while I add the direct regression and remove that fallback. The existing stable/current-main evidence remains preserved.

[timigod]

The exact-head stale-outcome fallback is repaired at 6c71167. Live explicit null now remains authoritative while a new turn is running instead of falling back to an older persisted completion. The deterministic regression forces that stale persistence condition; agent-manager tests pass 148/148, with Node 24 server typecheck and changed-file lint/format/diff checks green. Submitted head is 4097571.

[timigod]

Accepted-start material-progress repair is now frozen at exact head a045df727f6a161c17998714fcd1322f90bba032 (tree b6d42b8b3e7239415a55c9c848a8f9cab4ebdb7c).

The manager persists an authoritative continuation sequence before publishing running; fetch/inspect no longer requires a provider user_message row. The regression reproduces turn 2 after two turn-1 compactions with no turn-2 user row, and the result is none, not inherited stalled. A second manager regression emits turn_started and timeline output before startTurn resolves and proves the post-resolution path cannot move the boundary past those events.

Exact Node 24.18.1 proof: 6 files / 182 tests passed; server build passed; repository-wide all-workspace pre-commit typecheck passed; changed-file lint/format and git diff --check passed. The branch was updated by a normal non-force push. The PR remains draft pending an independent exact-tip rereview.

[timigod]

Exact-head review found the #2721 product implementation clean and requested one focused missing regression only. That proof is now added at exact head c1dcbffdabaf4cb520d7ccdbd56a295d49324033 (tree ba80b248be53279513e7cb20b0c100404b0d3454).

The daemon/client test starts from a two-compaction stalled continuation, accepts a new provider turn, emits turn_failed before any provider user_message, and proves fetch/inspect reports the new continuation as none with failed outcome and boundary 4—not inherited stalled. No product code changed.

Exact Node 24.18.1 proof: 6 files / 183 tests passed; repository-wide pre-commit typecheck, lint, format, and diff checks passed. Normal non-force push. PR remains draft pending final exact-tip rereview.

[timigod]

Independent exact-head review of a045df727f6a161c17998714fcd1322f90bba032 found no P0-P3 defect. One residual focused test gap remains for turn_failed before any provider user_message; that regression is being added before the draft is returned to ready.