@tranhoangnguyen0310/pi-flow-external 2.1.0-external.3 → 2.2.0-external.0

package/AGENTS.md

@@ -36,7 +36,7 @@ This fork changes the original pi-flow contract: `Agent` is not a generic Pi sub
 - Settings retention automatically prunes eligible completed records beyond `maxRunRecords`; active, interrupted, incomplete, and damaged records are not eligible.
 - Structured nested-agent activity may extend the wall-clock deadline once, by one fresh base timeout, capped at twice the original deadline.
 - Do not automatically retry failed or aborted external runs. Preserve the receipt and retry only when the user asks. Exception: the agy backend retries once on infrastructure-classified failures (auth, eligibility, network); the retry is disclosed in the receipt details (`retries`, `retryOf`) and never applies to agent-level failures, aborts, or timeouts.
-- `external_runs` is session/project scoped. `list` pages runs and workflow roots; `inspect` pages summaries/output/diagnostics; `wait` returns outcomes only for the selected one/any/all target set and never cancels pending work; `cancel` targets one stable ID and preserves its reason. No routine run event sends a parent message or notification.
+- `external_runs` is session/project scoped. `list` pages runs and workflow roots, each carrying a shared timing projection (`queuedAt`/`executionStartedAt`/`processStartedAt`/activity timestamps plus derived `queueDelayMs`/`elapsedMs`/`activityAgeMs`/`processDurationMs`); `activityAgeMs` and a running `elapsedMs` are computed only for a target independently confirmed live by the registry, never inferred from a durable record's status field alone (an unowned "running"-looking record may be an orphaned/crashed run, not a live one). `inspect` pages `summary`/`output`/`diagnostics`/`final` for one `runId`; `final` returns only the same canonical terminal result every other view already reads (no separate backend parser, no narration promoted to final) and is empty with `finalAvailable: false` until a verified successful terminal boundary exists — including for workflows, where an intentional JSON `null` result still counts as available. `inspect` also accepts a bounded batch `runIds` (up to 20, deduplicated, order preserved, summary-only, mutually exclusive with `runId`): every requested ID's ownership is validated before any page returns, entries share one consistent nested shape regardless of live/durable/agent/workflow origin (a workflow entry omits its unbounded children array in favor of `outputRef`/`diagnosticsRef`), reuses the existing per-inspect `limitBytes` cap with no second budget, and fails with an actionable error naming the run rather than ever silently dropping a target or serving a page over the caller's own byte budget. `wait` returns outcomes only for the selected one/any/all target set and never cancels pending work; `cancel` targets one stable ID and preserves its reason. An unresolvable `wf_...` ID fails as unknown/unavailable across `inspect`/`cancel`/`wait`/batch `inspect`, never falling through to the agent-only durable reader. No routine run event sends a parent message or notification.
 
 ## Workflow contract
 

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to pi-flow external are documented here.
 
 ## Unreleased
 
+## [2.2.0-external.0] - 2026-09-20
+
+### Added
+
+- `external_runs` `inspect` now accepts a bounded `runIds` batch (up to 20, deduplicated, order preserved) returning one consistent normalized summary entry per target — live, durable, agent, or workflow — without waiting for completion.
+- Added a verified `view: "final"` projection that returns only a backend's own canonical terminal answer, separate from combined narration/output; unavailable is a bounded, narration-free empty page (`finalAvailable: false`), never a synthesized sentence.
+- Derived explicit queue/elapsed/activity timing (`queueDelayMs`, `elapsedMs`, `activityAgeMs`, `processDurationMs`) from existing evidence, computed only where the underlying timestamps genuinely exist; a registry-confirmed-live run is required before now-relative durations are computed, so an orphaned/crashed durable record is never misreported as actively running.
+- `/external runs` list rows now show status, queue/elapsed duration, live activity age, and output/final availability, plus a manual `Refresh` choice that re-reads the current page and resets stale cursors.
+
+### Fixed
+
+- Recorded an explicit `execution_started` evidence boundary (direct `Agent` calls and workflow `agent()` calls) so durable status classification and timing no longer depend solely on `processStartedAt`, which never exists for in-process Pi children.
+- A workflow child's own registry entry now transitions `queued` → `running` explicitly at limiter-acquisition time, instead of only incidentally once its backend's first progress event fires.
+- Settled `outcome.status` now wins over a possibly-stale ambient `observation.status` once a run has terminated.
+- An unresolvable `wf_...` ID now rejects consistently as unknown/unavailable across `inspect`, `cancel`, `wait`, and batch `inspect`, instead of falling through to the agent-only durable reader.
+
 ## [2.1.0-external.3] - 2026-09-18
 
 ### Fixed

package/README.md

@@ -266,13 +266,39 @@ Agent({
 
 Use `external_runs` with these actions:
 
-- `list`: current session/project runs; use `cursor` for run pages and `workflowCursor` for workflow pages. `workflowRunId` filters children of one workflow.
-- `inspect`: `runId`, `view: "summary" | "output" | "diagnostics"`, and optional opaque `cursor`/`limitBytes`. Follow `nextCursor` to avoid truncation.
+- `list`: current session/project runs; use `cursor` for run pages and `workflowCursor` for workflow pages. `workflowRunId` filters children of one workflow. Rows carry a `timing` projection (`queueDelayMs`, `elapsedMs`, `activityAgeMs` when live, `processDurationMs`) plus `outputAvailable`/`finalAvailable`.
+- `inspect`: single `runId` with `view: "summary" | "output" | "diagnostics" | "final"`, and optional opaque `cursor`/`limitBytes` (max 64 KiB, same cap for every view). Follow `nextCursor` to avoid truncation. `summary` includes the same `timing` projection as `list`, plus `output.finalAvailable`. `final` returns only the verified canonical terminal answer — empty with `finalAvailable: false` until a successful terminal boundary exists; it never promotes partial/narration text. `output` stays the combined stream (assistant messages plus canonical result) and is unchanged.
+- `inspect` with `runIds` instead of `runId` (up to 20, deduplicated, order preserved): a single bounded batch of `summary`-only projections — one cheap request to see whether several selected background children are queued, running, or terminal, each with `outputRef`/`diagnosticsRef` for follow-up detail. Ownership of every requested ID is validated before any page is returned. Reuses the same `limitBytes` cap as single-run inspection; pages contain whole target entries and continue through `nextCursor`, without invalidation from ordinary live progress. If one compact entry cannot fit, an actionable error asks you to increase `limitBytes` or inspect that run individually; no target is silently dropped. `runId` and `runIds` are mutually exclusive, and batch `view` must stay `summary`.
 - `wait`: one `runId` or selected `runIds`, with `mode: "any" | "all"`. It returns terminal outcomes plus still-pending IDs; an unsuccessful workflow returns early even in `all` mode. It never chooses a winner or cancels pending work.
 - `cancel`: one `runId` and optional reason. Whole-workflow cancellation stops active children; targeted child cancellation remains a catchable workflow outcome. Cancellation does not roll back edits or other side effects.
 
 Interrupting a blocking `Agent`/`workflow` call cancels its work. Interrupting `external_runs wait` stops only that wait. Background work survives its launching tool return and ordinary parent turns, but not the owning session: orderly session shutdown requests cancellation and waits for bounded cleanup. This is not a daemon. After a host crash or unconfirmed shutdown, unfinished evidence is `interrupted_or_uncertain`; restart restores evidence access, never live ownership or guaranteed retrospective process termination. No routine activity wakes the parent, and live steering is not supported.
 
+A parent's own `sleep`/wait duration (or its process lifetime) is not a measurement of, and does not bound, how long a delegated command actually takes to run — a background child keeps running under the session's ownership regardless of what the parent does next. A realistic collection shape:
+
+```ts
+// Launch two independent background runs.
+const one = Agent({ description: "Audit auth module", prompt: "Audit /absolute/repo/auth read-only.", role: "reviewer", background: true }); // -> run_...
+const two = Agent({ description: "Audit billing module", prompt: "Audit /absolute/repo/billing read-only.", role: "reviewer", background: true }); // -> run_...
+
+// Optional: give both a head start before doing anything else. This sleep
+// bounds nothing about the children's own runtime — it is just the parent
+// choosing when to next check in, not a deadline or a proxy for command time.
+// sleep(30_000)
+
+// Do unrelated parent work here (read files, answer the user, plan next steps)
+// while both children continue running under the session, not the parent turn.
+
+// Check on both at once, without waiting for either to finish:
+// external_runs({ action: "inspect", runIds: [one.runId, two.runId] })
+
+// Leave them running and come back later in the conversation (or after
+// further parent work) to collect final output once each is actually done:
+// external_runs({ action: "inspect", runId: one.runId, view: "final" })
+```
+
+A task that sounds like a 30-second command can legitimately take substantially longer end-to-end once queueing and backend overhead are included — inspect and wait, do not assume.
+
 ## Workflow usage
 
 The `workflow` tool runs trusted JavaScript that calls one or more external roles and returns a JSON-serializable result. Workflows are for explicit fan-out — and for the case this extension was built to make explicit: running several children on the **same** harness at once. Example:

package/docs/field-testing.md

@@ -105,6 +105,17 @@ Local fixture tests own selection, boundary, and failure behavior; this check on
 
 Do not run damaged-record and expected-failure provider scenarios manually. Their behavior is deterministic and belongs in the local fixture tests.
 
+## Change-triggered background-run observability check
+
+Run only when batch inspection, the `final` view, timing projection, or `/external runs` browsing changes. In one fresh Pi session against a read-only fixture:
+
+1. Launch two independent `Agent({ ..., background: true })` calls back to back (do not wait on either), then do one unrelated piece of parent work (e.g. read a file) before checking on them — this exercises the actually-recommended usage shape (separate launches, other work in between), not a tight launch-then-immediately-inspect loop.
+2. Call `external_runs({ action: "inspect", runIds: [<first>, <second>] })` once and confirm both come back as one bounded batch of `summary` projections (queued/running/terminal, `outputRef`/`diagnosticsRef` per entry) without waiting for either to finish.
+3. After both children are confirmed terminal (`external_runs wait` or a later `inspect`), call `external_runs({ action: "inspect", runId: <runId>, view: "final" })` for a completed run and confirm it returns only the verified canonical answer; for a run cancelled mid-flight (or inspected before it settles), confirm the tool response reports `finalAvailable: false` with a deliberately empty, bounded projection (`items: []`, `integrity: "incomplete"`) rather than a fabricated success — this empty shape is correct at the tool layer, not a bug. The human-readable explanation ("No verified final answer is available yet for `<runId>`.") is a separate, UI-only notice that `/external runs` shows when Final is selected on an unsettled run; the tool response itself stays narration-free by design.
+4. Run `/external runs`, open the list, and manually select `Refresh`: confirm it re-reads the first page and resets any list cursor without navigating into a run or waiting/polling. Select a still-running row and confirm its queue/elapsed timing and final-availability marker are present and update only when you refresh again (never on a timer).
+
+Local fixture tests already cover batch pagination/cursor/byte-limit edge cases, the `final` view's success/unavailable/legitimate-null shapes, and `Refresh`'s cursor-reset behavior deterministically; this check only proves the real backend/registry timing (queued→running, activity age, terminal settlement) matches what those fixtures assume.
+
 ## Change-triggered project default-harness check
 
 Run only when project default-harness resolution changes. In a fresh Pi session against a trusted read-only fixture containing `.pi/pi-flow-external/settings.json` with `"defaultHarness": "claude"`, verify `/external settings` reports `defaultHarness: claude (project: ...)`, delegate one read-only task with `role` only (no `harness`) and verify the receipt names a `claude-*` profile, then confirm an explicit `harness: "codex"` call still routes to codex. Repeat once in the same fixture with trust removed and confirm the override is ignored with a warning.
@@ -119,4 +130,5 @@ Before a runtime release:
 4. Run interruption checks for adapters whose cancellation/output path changed.
 5. Run the natural-language routing smoke only if role discovery, tool descriptions, or coordinator guidance changed.
 6. Run the nested timeout check only if nested detection or timeout behavior changed.
-7. Remove temporary evidence and profiles.
+7. Run the background-run observability check only if batch inspection, the `final` view, timing projection, or `/external runs` browsing changed.
+8. Remove temporary evidence and profiles.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tranhoangnguyen0310/pi-flow-external",
-  "version": "2.1.0-external.3",
+  "version": "2.2.0-external.0",
   "description": "External Claude Code, Codex CLI, and Antigravity delegation for pi.",
   "type": "module",
   "main": "./index.ts",

package/src/core/agy.ts

@@ -266,6 +266,7 @@ export async function spawnAgySubagent(params: {
   permission?: PermissionTier;
   resumeConversationId?: string;
   timeoutMs?: number;
+  executionStartedAt?: number;
 }): Promise<AgentToolResult> {
   const subagentType = params.profile.name;
   const promptParts = [params.profile.systemPrompt, params.prompt, params.appendInstructions].filter(Boolean);
@@ -278,6 +279,7 @@ export async function spawnAgySubagent(params: {
     backend: params.profile.backend,
     enabled: params.progressEnabled,
     onProgress: params.onProgress,
+    executionStartedAt: params.executionStartedAt,
   });
   const progress = emitter.progress;
   const stderrBuffer = createBoundedBuffer(MAX_STDERR_CHARS);

package/src/core/claude.ts

@@ -340,6 +340,7 @@ export async function spawnClaudeSubagent(params: {
   permission?: PermissionTier;
   maxBudgetUsd?: number;
   resumeSessionId?: string;
+  executionStartedAt?: number;
 }): Promise<AgentToolResult> {
   const subagentType = params.profile.name;
   const taskPrompt = params.appendInstructions ? `${params.prompt}\n\n${params.appendInstructions}` : params.prompt;
@@ -350,6 +351,7 @@ export async function spawnClaudeSubagent(params: {
     backend: params.profile.backend,
     enabled: params.progressEnabled,
     onProgress: params.onProgress,
+    executionStartedAt: params.executionStartedAt,
   });
   const progress = emitter.progress;
   let latestRawUsage = emptyTokenUsage();

package/src/core/codex.ts

@@ -311,6 +311,7 @@ export async function spawnCodexSubagent(params: {
   outputSchema?: unknown;
   permission?: PermissionTier;
   resumeSessionId?: string;
+  executionStartedAt?: number;
 }): Promise<AgentToolResult> {
   const subagentType = params.profile.name;
   const taskPrompt = params.appendInstructions ? `${params.prompt}\n\n${params.appendInstructions}` : params.prompt;
@@ -321,6 +322,7 @@ export async function spawnCodexSubagent(params: {
     backend: params.profile.backend,
     enabled: params.progressEnabled,
     onProgress: params.onProgress,
+    executionStartedAt: params.executionStartedAt,
   });
   const progress = emitter.progress;
   let latestUsage = emptyUsage(params.profile.model);

package/src/core/progress.ts

@@ -186,6 +186,8 @@ export interface ProgressEmitterOptions {
   backend?: SubagentBackend;
   enabled: boolean;
   onProgress: ((result: AgentToolResult) => void) | undefined;
+  /** Execution-start boundary captured by the caller right after the shared concurrency limiter granted a slot. */
+  executionStartedAt?: number;
 }
 
 export interface ProgressEmitter {
@@ -214,6 +216,9 @@ export interface ProgressEmitter {
 export function createProgressEmitter(options: ProgressEmitterOptions): ProgressEmitter {
   const { toolCallId, description, subagentType, backend, enabled, onProgress } = options;
   const progress = createProgressNode(toolCallId, description, subagentType, "running", backend);
+  if (options.executionStartedAt !== undefined) {
+    progress.executionStartedAt = options.executionStartedAt;
+  }
   const live = Boolean(enabled && onProgress);
 
   let lastProgressEmit = 0;

package/src/core/run-inspection.ts

@@ -14,7 +14,7 @@ const MAX_CURSOR_CHARS = 4096;
 const MAX_LIST_SCAN = 200;
 const RUN_ID_PATTERN = /^run_[A-Za-z0-9_-]{1,128}$/;
 
-export type RunInspectionView = "output" | "diagnostics" | "summary";
+export type RunInspectionView = "output" | "diagnostics" | "summary" | "final";
 export type RunRecordIntegrity = "complete" | "incomplete" | "damaged";
 export type RunOutputStatus = "preliminary" | "final" | "interrupted";
 
@@ -25,11 +25,41 @@ export interface RunInspectionPage {
   view: RunInspectionView;
   items: RunInspectionItem[];
   outputStatus: RunOutputStatus;
+  /** Whether a separate verified final answer (view: "final") is available for this run. */
+  finalAvailable: boolean;
   integrity: RunRecordIntegrity;
   truncatedTail: boolean;
   nextCursor?: string;
 }
 
+/**
+ * Raw timestamp inputs for {@link deriveRunTiming}. Accepts either an ISO
+ * string (durable evidence) or an epoch-ms number (live `SubagentProgressNode`
+ * fields) so both `run-inspection.ts` and `external-runs.ts` can share one
+ * derivation without a normalization step at every call site.
+ */
+export interface RunTimingInputs {
+  queuedAt?: string | number;
+  executionStartedAt?: string | number;
+  processStartedAt?: string | number;
+  firstActivityAt?: string | number;
+  lastActivityAt?: string | number;
+  finishedAt?: string | number;
+}
+
+export interface RunTiming {
+  queuedAt?: string;
+  executionStartedAt?: string;
+  processStartedAt?: string;
+  firstActivityAt?: string;
+  lastActivityAt?: string;
+  finishedAt?: string;
+  queueDelayMs?: number;
+  elapsedMs?: number;
+  activityAgeMs?: number;
+  processDurationMs?: number;
+}
+
 export interface RunRecordListItem {
   runId: string;
   queuedAt?: string;
@@ -43,6 +73,8 @@ export interface RunRecordListItem {
   parentSessionId?: string;
   workflowRunId?: string;
   outputAvailable: boolean;
+  finalAvailable: boolean;
+  timing: RunTiming;
   integrity: RunRecordIntegrity;
 }
 
@@ -61,6 +93,7 @@ interface ScanResult { missing: boolean; stopped: boolean; truncatedTail: boolea
 interface RunObservation {
   metadata?: Record<string, unknown>;
   queuedAt?: string;
+  executionStartedAt?: string;
   processStartedAt?: string;
   firstActivityAt?: string;
   lastActivityAt?: string;
@@ -94,6 +127,7 @@ export async function inspectRun({
   const summary = await readSummary(join(directory, "summary.json"), runId);
   const terminal = asRecord(summary.document?.summary);
   const terminalStatus = asString(terminal?.status);
+  const finalAvailable = isFinalAvailable(terminal);
 
   if (view === "summary") {
     if (decoded?.kind === "inspect" && decoded.source !== "summary") throw new Error("Cursor source does not match summary view");
@@ -109,6 +143,7 @@ export async function inspectRun({
       view,
       items: portion.text ? [{ text: portion.text }] : [],
       outputStatus: outputStatus(terminalStatus),
+      finalAvailable,
       integrity: mergedIntegrity(summary, observation),
       truncatedTail: observation.truncatedTail,
       ...(portion.nextOffset < text.length
@@ -118,6 +153,34 @@ export async function inspectRun({
   }
 
   if (decoded?.kind === "inspect" && decoded.source === "summary") throw new Error("Cursor source does not match inspection view");
+
+  if (view === "final") {
+    // Reuses the same canonical terminal result every other view already reads
+    // (canonicalResult/isFinalAvailable) — no separate backend parser or
+    // narration heuristic. Always a single small terminal-document item, so it
+    // reuses the same "terminal" cursor source as view: "output".
+    const observation = await readObservation(eventsPath, runId);
+    const finalText = finalAvailable ? canonicalResult(terminal) : undefined;
+    const items: RunInspectionItem[] = finalText ? [{ text: finalText }] : [];
+    const revision = contentRevision(finalText ?? "");
+    const finalCursor = decoded?.kind === "inspect"
+      ? decoded
+      : { v: CURSOR_VERSION, kind: "inspect", runId, view, source: "terminal", itemIndex: 0, textOffset: 0, revision } as const;
+    if (finalCursor.source !== "terminal") throw new Error("Cursor source does not match final view");
+    if (finalCursor.revision !== revision) throw staleCursorError();
+    return terminalPage(
+      runId,
+      view,
+      items,
+      finalCursor,
+      limit,
+      mergedIntegrity(summary, observation),
+      observation.truncatedTail,
+      terminalStatus,
+      finalAvailable,
+    );
+  }
+
   if (view === "output" && summary.document && (terminalStatus === "done" || assistantItems(terminal).length > 0)) {
     if (decoded?.kind === "inspect" && decoded.source === "events") throw staleCursorError();
     const observation = await readObservation(eventsPath, runId);
@@ -137,6 +200,7 @@ export async function inspectRun({
       mergedIntegrity(summary, observation),
       observation.truncatedTail,
       terminalStatus,
+      finalAvailable,
     );
   }
   if (decoded?.kind === "inspect" && decoded.source === "terminal") throw new Error("Cursor source does not match diagnostics view");
@@ -187,6 +251,7 @@ export async function inspectRun({
     view,
     items,
     outputStatus: outputStatus(terminalStatus),
+    finalAvailable,
     integrity,
     truncatedTail: scan.truncatedTail,
     ...(nextCursor ? { nextCursor: encodeCursor(nextCursor) } : {}),
@@ -258,8 +323,9 @@ async function readListItem(runsDirectory: string, runId: string): Promise<RunRe
   const metadata = asRecord(summary.document?.metadata) ?? observation?.metadata;
   if (!metadata && summary.integrity === "damaged") return undefined;
   const terminal = asRecord(summary.document?.summary);
-  const processStarted = Boolean(timeValue(terminal?.processStartedAt) ?? observation?.processStartedAt ?? observation?.outputAvailable);
-  const status = asString(terminal?.status) ?? (processStarted ? "running" : "queued");
+  const executionStartedAt = timeValue(terminal?.executionStartedAt) ?? observation?.executionStartedAt;
+  const processStartedAtValue = timeValue(terminal?.processStartedAt) ?? observation?.processStartedAt;
+  const status = asString(terminal?.status) ?? classifyQueuedOrRunning(executionStartedAt, processStartedAtValue, observation?.outputAvailable);
   const outcome = terminal
     ? status === "done" ? "succeeded" : terminal.timedOut === true ? "timed_out" : status === "aborted" ? "cancelled" : "failed"
     : undefined;
@@ -278,10 +344,36 @@ async function readListItem(runsDirectory: string, runId: string): Promise<RunRe
     ...(asString(metadata?.parentSessionId) ? { parentSessionId: asString(metadata?.parentSessionId) } : {}),
     ...(asString(metadata?.workflowRunId) ? { workflowRunId: asString(metadata?.workflowRunId) } : {}),
     outputAvailable: Boolean(canonicalResult(terminal) || assistantItems(terminal).length || observation?.outputAvailable),
+    finalAvailable: isFinalAvailable(terminal),
+    // Never live: a historical list row has no RunRegistry access either, so
+    // this timing is always the durable-evidence-only projection (live=false).
+    timing: deriveRunTiming({
+      queuedAt,
+      executionStartedAt,
+      processStartedAt: processStartedAtValue,
+      firstActivityAt: timeValue(terminal?.firstActivityAt) ?? observation?.firstActivityAt,
+      lastActivityAt: timeValue(terminal?.lastActivityAt) ?? observation?.lastActivityAt,
+      finishedAt: summary.document?.finishedAt,
+    }, false),
     integrity: observation ? observation.integrity : summary.integrity,
   };
 }
 
+/**
+ * Shared queued/running classification for a raw (pre-integrity-override)
+ * status, used by both `readListItem` and `summaryProjection`.
+ * `executionStartedAt` is backend-agnostic (present for pi too, unlike
+ * `processStartedAt`, which only CLI backends with a child OS process ever
+ * emit) and is the earliest reliable "execution actually began" signal, so it
+ * must gate this classification alongside `processStartedAt`/output — or a pi
+ * run that has started but produced no output yet would misreport as still
+ * "queued". Does not affect the separate integrity/interrupted_or_uncertain
+ * distinction, applied independently downstream (e.g. by `historicalAgent`).
+ */
+function classifyQueuedOrRunning(executionStartedAt: unknown, processStartedAt: unknown, outputAvailable: unknown): "queued" | "running" {
+  return Boolean(executionStartedAt) || Boolean(processStartedAt) || Boolean(outputAvailable) ? "running" : "queued";
+}
+
 function documentTime(value: unknown): number | undefined {
   if (typeof value !== "string") return undefined;
   const time = Date.parse(value);
@@ -296,6 +388,8 @@ async function readObservation(eventsPath: string, runId: string): Promise<RunOb
     if (event.type === "run_started") {
       observation.metadata = asRecord(event.data);
       observation.queuedAt = asString(observation.metadata?.queuedAt) ?? event.timestamp;
+    } else if (event.type === "execution_started") {
+      observation.executionStartedAt ??= event.timestamp;
     } else if (event.type === "process_started") {
       observation.processStartedAt ??= event.timestamp;
     } else if (event.type === "backend_event") {
@@ -317,10 +411,12 @@ function summaryProjection(runId: string, summary: SummaryState, observation: Ru
   const document = summary.document;
   const metadata = asRecord(document?.metadata) ?? observation.metadata;
   const terminal = asRecord(document?.summary);
+  const executionStartedAt = timeValue(terminal?.executionStartedAt) ?? observation.executionStartedAt;
   const processStartedAt = timeValue(terminal?.processStartedAt) ?? observation.processStartedAt;
   const firstActivityAt = timeValue(terminal?.firstActivityAt) ?? observation.firstActivityAt;
   const lastActivityAt = timeValue(terminal?.lastActivityAt) ?? observation.lastActivityAt;
-  const status = asString(terminal?.status) ?? (processStartedAt || observation.outputAvailable ? "running" : "queued");
+  const status = asString(terminal?.status) ?? classifyQueuedOrRunning(executionStartedAt, processStartedAt, observation.outputAvailable);
+  const queuedAt = asString(document?.queuedAt) ?? observation.queuedAt;
   return {
     runId,
     task: compactObject({
@@ -333,7 +429,7 @@ function summaryProjection(runId: string, summary: SummaryState, observation: Ru
     }),
     state: compactObject({
       status,
-      queuedAt: asString(document?.queuedAt) ?? observation.queuedAt,
+      queuedAt,
       processStartedAt,
       firstActivityAt,
       lastActivityAt,
@@ -341,9 +437,22 @@ function summaryProjection(runId: string, summary: SummaryState, observation: Ru
       error: boundedString(terminal?.error),
       integrity: mergedIntegrity(summary, observation),
     }),
+    // Never live here: this projection is durable-evidence-only (inspectRun has
+    // no RunRegistry access), so now-relative fields (elapsedMs while running,
+    // activityAgeMs) are never computed — only src/external-runs.ts may do that,
+    // and only for a target it resolves through registry.get(runId).
+    timing: deriveRunTiming({
+      queuedAt,
+      executionStartedAt,
+      processStartedAt,
+      firstActivityAt,
+      lastActivityAt,
+      finishedAt: document?.finishedAt,
+    }, false),
     output: {
       available: Boolean(canonicalResult(terminal) || assistantItems(terminal).length || observation.outputAvailable),
       status: outputStatus(asString(terminal?.status)),
+      finalAvailable: isFinalAvailable(terminal),
     },
   };
 }
@@ -457,7 +566,7 @@ async function validateEventCursor(path: string, runId: string, view: RunInspect
   }
 }
 
-function terminalPage(runId: string, view: "output", items: RunInspectionItem[], cursor: Extract<InspectionCursor, { source: "terminal" }>, limit: number, integrity: RunRecordIntegrity, truncatedTail: boolean, terminalStatus: string | undefined): RunInspectionPage {
+function terminalPage(runId: string, view: "output" | "final", items: RunInspectionItem[], cursor: Extract<InspectionCursor, { source: "terminal" }>, limit: number, integrity: RunRecordIntegrity, truncatedTail: boolean, terminalStatus: string | undefined, finalAvailable: boolean): RunInspectionPage {
   if (items.length || cursor.itemIndex !== 0 || cursor.textOffset !== 0) validateItemCursor(items, cursor.itemIndex, cursor.textOffset);
   const served = serveItems(items, cursor.itemIndex, cursor.textOffset, limit);
   return {
@@ -465,6 +574,7 @@ function terminalPage(runId: string, view: "output", items: RunInspectionItem[],
     view,
     items: served.items,
     outputStatus: outputStatus(terminalStatus),
+    finalAvailable,
     integrity,
     truncatedTail,
     ...(served.next ? { nextCursor: encodeCursor({ v: CURSOR_VERSION, kind: "inspect", runId, view, source: "terminal", ...served.next, revision: cursor.revision }) } : {}),
@@ -538,6 +648,75 @@ function canonicalResult(summary: Record<string, unknown> | undefined): string |
   return summary?.status === "done" ? textValue(summary.structuredOutput ?? summary.result) : undefined;
 }
 
+/**
+ * Whether a separate verified final answer (view: "final") is available.
+ * Deliberately identical to `Boolean(canonicalResult(summary))`: the terminal
+ * `status: "done"` gate lives inside `canonicalResult` itself, so there is
+ * exactly one place that decides "this run has a verified successful
+ * terminal boundary" — no second heuristic, no narration promotion.
+ */
+function isFinalAvailable(summary: Record<string, unknown> | undefined): boolean {
+  return Boolean(canonicalResult(summary));
+}
+
+function msValue(value: string | number | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  const parsed = typeof value === "number" ? value : Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function nonNegativeDelta(end: number | undefined, start: number | undefined): number | undefined {
+  if (end === undefined || start === undefined) return undefined;
+  const delta = end - start;
+  return delta >= 0 ? delta : undefined;
+}
+
+function isoValue(value: string | number | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  return typeof value === "string" ? value : timeValue(value);
+}
+
+/**
+ * One shared, pure timing projection used by durable summaries, list entries,
+ * batch inspection, and (via `live: true`) live registry-backed summaries.
+ *
+ * `live` must be true ONLY for a target independently confirmed still running
+ * by `RunRegistry` (i.e. resolved via `registry.get(runId)` in
+ * `src/external-runs.ts`). Durable-evidence-only callers in this module
+ * (`inspectRun`, `listRunRecords`, `getRunRecord`) always pass `false`: a
+ * record with no `finishedAt` and no owning registry entry could be a
+ * genuinely still-running child, or an orphaned/crashed one whose parent
+ * session never got to write `finishedAt` — durable evidence alone cannot
+ * tell the two apart, so a `now`-relative field is never fabricated for it.
+ */
+export function deriveRunTiming(inputs: RunTimingInputs, live: boolean, now: number = Date.now()): RunTiming {
+  const queuedAtMs = msValue(inputs.queuedAt);
+  const executionStartedAtMs = msValue(inputs.executionStartedAt);
+  const processStartedAtMs = msValue(inputs.processStartedAt);
+  const lastActivityAtMs = msValue(inputs.lastActivityAt);
+  const finishedAtMs = msValue(inputs.finishedAt);
+
+  const queueDelayMs = nonNegativeDelta(executionStartedAtMs, queuedAtMs);
+  const elapsedMs = finishedAtMs !== undefined
+    ? nonNegativeDelta(finishedAtMs, executionStartedAtMs)
+    : live ? nonNegativeDelta(now, executionStartedAtMs) : undefined;
+  const activityAgeMs = live && finishedAtMs === undefined ? nonNegativeDelta(now, lastActivityAtMs) : undefined;
+  const processDurationMs = nonNegativeDelta(finishedAtMs, processStartedAtMs);
+
+  return {
+    ...(isoValue(inputs.queuedAt) ? { queuedAt: isoValue(inputs.queuedAt) } : {}),
+    ...(isoValue(inputs.executionStartedAt) ? { executionStartedAt: isoValue(inputs.executionStartedAt) } : {}),
+    ...(isoValue(inputs.processStartedAt) ? { processStartedAt: isoValue(inputs.processStartedAt) } : {}),
+    ...(isoValue(inputs.firstActivityAt) ? { firstActivityAt: isoValue(inputs.firstActivityAt) } : {}),
+    ...(isoValue(inputs.lastActivityAt) ? { lastActivityAt: isoValue(inputs.lastActivityAt) } : {}),
+    ...(isoValue(inputs.finishedAt) ? { finishedAt: isoValue(inputs.finishedAt) } : {}),
+    ...(queueDelayMs !== undefined ? { queueDelayMs } : {}),
+    ...(elapsedMs !== undefined ? { elapsedMs } : {}),
+    ...(activityAgeMs !== undefined ? { activityAgeMs } : {}),
+    ...(processDurationMs !== undefined ? { processDurationMs } : {}),
+  };
+}
+
 function textValue(value: unknown): string | undefined {
   if (typeof value === "string") return value || undefined;
   if (value === undefined || value === null) return undefined;
@@ -623,7 +802,7 @@ function hasKeys(value: Record<string, unknown>, keys: string[]): boolean {
 }
 
 function isView(value: unknown): value is RunInspectionView {
-  return value === "output" || value === "diagnostics" || value === "summary";
+  return value === "output" || value === "diagnostics" || value === "summary" || value === "final";
 }
 
 function isNonNegativeInteger(value: unknown): value is number {

package/src/core/spawn.ts

@@ -90,6 +90,14 @@ export interface SpawnSubagentParams {
   resumeRunId?: string;
   /** Evidence identity allocated by the caller before waiting for a concurrency slot. */
   runRecord?: RunRecord;
+  /**
+   * Execution-start boundary (epoch ms), captured by the caller immediately after
+   * the shared concurrency limiter granted this run a slot. Callers always acquire
+   * the limiter themselves before calling spawnSubagent (see the class doc comment
+   * above); this field only carries that already-captured timestamp through so it
+   * reaches the terminal summary and the live progress snapshot.
+   */
+  executionStartedAt?: number;
 }
 
 interface SpawnSubagentRuntimeParams extends SpawnSubagentParams {
@@ -372,6 +380,7 @@ export async function spawnSubagent(params: SpawnSubagentParams): Promise<AgentT
         timedOut: details.timedOut === true,
         result: details.result,
         assistantOutput: details.assistantOutput,
+        executionStartedAt: details.progress?.executionStartedAt,
         processStartedAt: details.progress?.processStartedAt,
         firstActivityAt: details.progress?.firstActivityAt,
         lastActivityAt: details.progress?.lastActivityAt,
@@ -425,6 +434,7 @@ export async function spawnSubagent(params: SpawnSubagentParams): Promise<AgentT
       description: params.description,
       status: "error",
       error: error instanceof Error ? error.message : String(error),
+      executionStartedAt: params.executionStartedAt,
       durationMs: Date.now() - startedAt,
       backendEventCount,
       nestedActivitySeen,
@@ -456,6 +466,7 @@ async function spawnSubagentRuntime(params: SpawnSubagentRuntimeParams): Promise
       outputSchema: params.outputSchema,
       permission: params.permission,
       resumeSessionId: params.resumeSessionId,
+      executionStartedAt: params.executionStartedAt,
     });
   }
   if (params.profile.backend === "agy") {
@@ -477,6 +488,7 @@ async function spawnSubagentRuntime(params: SpawnSubagentRuntimeParams): Promise
       outputSchema: params.outputSchema,
       permission: params.permission,
       resumeConversationId: params.resumeSessionId,
+      executionStartedAt: params.executionStartedAt,
       // ponytail: 2x base because extendOnce() may legitimately double the
       // outer deadline; the outer AbortSignal remains the real authority.
       timeoutMs: params.timeoutMs * 2,
@@ -519,6 +531,7 @@ async function spawnSubagentRuntime(params: SpawnSubagentRuntimeParams): Promise
       permission: params.permission,
       maxBudgetUsd: params.maxBudgetUsd,
       resumeSessionId: params.resumeSessionId,
+      executionStartedAt: params.executionStartedAt,
     });
   }
   if (!params.model) {
@@ -616,6 +629,7 @@ async function spawnSubagentRuntime(params: SpawnSubagentRuntimeParams): Promise
     backend: profile.backend,
     enabled: progressEnabled,
     onProgress,
+    executionStartedAt: params.executionStartedAt,
   });
   const progress = emitter.progress;