@tranhoangnguyen0310/pi-flow-external 3.0.0-external.0 → 3.1.1-external.0

package/AGENTS.md

@@ -43,6 +43,8 @@ This fork changes the original pi-flow contract: `Agent` is not a generic Pi sub
 
 ## Receipt and evidence invariants
 
+- Agent public contract v1 uses a discriminated `ok` envelope with `isError === !ok`; renderer details remain independent. Expected errors are coded at their source, not parsed from prose. Canonical output is inline only within 16 KiB UTF-8 JSON after redaction, with `output_redacted` disclosed when changed. Refs must be resolvable, liveness must be observed after evidence I/O, and unavailable evidence must not discard a settled result. Native codemode tests must assert script output and hook-captured flags outside hooks (the SDK catches hook exceptions).
+
 - Success requires a recognized backend terminal-success event, a zero process exit, and a non-empty result.
 - A backend failure with a complete local record is different from an incomplete or damaged record; preserve that distinction in reports.
 - Normal runs write private best-effort evidence under `~/.pi/agent/pi-flow-external/runs/` or `PI_FLOW_EXTERNAL_RUNS_DIR`. Records may still contain sensitive prompts, excerpts, and tool output despite redaction.

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to pi-flow external are documented here.
 
+## [3.1.1-external.0] - 2026-10-02
+
+### Fixed
+- `external_runs list` no longer reports live work as `interrupted_or_uncertain` on later pages, or lists a live run twice. Live state now replaces a run's persisted row on whichever page that row falls. Live runs with no persisted row yet (for example, while evidence writes fail) are paged first and count against `limit`, so every page stays within `limit`. The cursor bookmarks the last such run in registry order, so persisting one between pages never skips another; it can only appear twice (once live, once persisted). If the bookmarked run has left the registry, the next page fails with "Run list changed while paging" instead of guessing. A run started after the listing reached its persisted rows appears in the next fresh listing.
+- One unreadable workflow journal (an incompatible version, a corrupt start line, or a read error) no longer fails the whole `list`. It is listed as one `interrupted_or_uncertain` row with the read error; `inspect` of that ID still reports the error.
+- A workflow launched after its session closed no longer throws with its journal left open. The journal is settled as failed, and the call returns an error result naming the closed session.
+- Workflow resume no longer reveals that another project's run exists: it reports the same "run journal not found" message as an unknown run ID.
+
+## [3.1.0-external.0] - 2026-10-02
+
+### Added
+- Versioned Agent receipts (`outputSchema`, `structuredContent`, and accurate `isError`) for native Pi codemode. Scripts must check `ok`; expected failures are data, while host dispatch failures and unexpected exceptions still throw.
+- Registry-backed lifecycle/output/evidence projections, a 16 KiB UTF-8 JSON inline cap, inspect references, and explicit output-redaction warnings. Human renderer details remain separate. Workflow and supervision contracts remain follow-up work.
+
+### Changed
+- Require Pi `~0.99.2`, with development packages pinned to 0.99.2; older hosts are no longer claimed as supported. Pi children inherit registered providers and runtime API keys through ModelRuntime. Flow retains six concrete thinking levels (not SDK `max`); virtual models are rejected because their registrations cannot be inherited.
+- Port isolated faux-provider and E2E harnesses to Pi 0.99.2. Native codemode regressions cover returned errors, host rejection/throws, redaction, declaration discovery, and background settlement during evidence reads.
+
 ## [3.0.0-external.0] - 2026-10-01
 
 ### Breaking: configuration v5 (issue #73)

package/README.md

@@ -14,7 +14,7 @@ Six built-in roles are available in memory on every one of those harnesses. A fr
 
 The ordinary driver has four tools (`workflow` can be disabled):
 
-- `Agent` resolves and runs one external role.
+- `Agent` resolves and runs one external role. Its [versioned public receipt](docs/agent-public-contract.md) is available to native Pi codemode; scripts must check `ok`.
 - `workflow` orchestrates multiple external roles with trusted JavaScript.
 - `external_help` returns the usage playbook, role details, permission behavior, or workflow guidance on demand.
 - `external_runs` lists, inspects, waits for, and cancels session-owned runs.
@@ -23,6 +23,8 @@ The ordinary driver has four tools (`workflow` can be disabled):
 
 ## Install
 
+Host baseline: **Pi 0.99.2**, with Pi peers restricted to `~0.99.2` (0.99.x patches from 0.99.2). The offline suite is pinned to exactly 0.99.2; older hosts and later minor versions are not claimed as supported.
+
 Global installation:
 
 ```bash
@@ -370,7 +372,7 @@ Disable a role everywhere with `/external config role disable reviewer`, or add
 
 ### Named Pi harness configurations
 
-A named Pi harness runs in-process through Pi's own SDK, for any model Pi can already resolve (built-in, self-hosted, or a custom-registered provider). Register it with **Add a Pi agent…** in `/external`, or with `/external config harness create pi-NAME --model provider/model`: a `pi-<label>` name, a `provider/model` id, a reasoning policy (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `parent`, stored explicitly on creation), and a resource preset (`minimal` or `skills`). `minimal` is the default and leaves skills unloaded. `skills` loads installed skills, and project skills only when the project is trusted. Registration is saved into the `harnesses` object of `settings.json` without sending a request. `/external config harness assist` is the model-assisted alternative; its smoke test uses the selected preset and runs before saving. A legacy entry that omits `preset` is `minimal`. The six CLI harnesses are built in and do not need entries there.
+A named Pi harness runs in-process through Pi's own SDK, for physical models Pi can already resolve (built-in, self-hosted, or a custom-registered provider). Children inherit in-memory provider registrations and the selected provider's runtime API key; stored authentication uses the same agent directory. Virtual model registrations cannot be transferred through the SDK registry and are rejected. Flow retains six concrete thinking levels; SDK `max` remains unsupported. Register it with **Add a Pi agent…** in `/external`, or with `/external config harness create pi-NAME --model provider/model`: a `pi-<label>` name, a `provider/model` id, a reasoning policy (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `parent`, stored explicitly on creation), and a resource preset (`minimal` or `skills`). `minimal` is the default and leaves skills unloaded. `skills` loads installed skills, and project skills only when the project is trusted. Registration is saved into the `harnesses` object of `settings.json` without sending a request. `/external config harness assist` is the model-assisted alternative; its smoke test uses the selected preset and runs before saving. A legacy entry that omits `preset` is `minimal`. The six CLI harnesses are built in and do not need entries there.
 
 ```json
 {

package/docs/agent-public-contract.md

@@ -0,0 +1,21 @@
+# Agent public contract v1
+
+`Agent` declares `outputSchema` and returns matching `structuredContent`. Human `content` and renderer `details` remain separate. Native Pi codemode receives the structured receipt, including failures: **check `ok`**, not just whether the call threw.
+
+```js
+const receipt = await tools.Agent({ role: "worker", description: "Check build", prompt: "Run the build and report." });
+if (!receipt.ok) return receipt.error;
+return receipt.data.run;
+```
+
+The envelope carries `contractVersion: 1`, `tool: "Agent"`, `action: "delegate"`, ISO `observedAt`, `ok`, `data: {run}`, and `warnings`. `error: {code,message}` exists only on failure. Unknown fields must be ignored by v1 consumers; removing fields or changing their meaning requires a new contract version. The host uses the schema for declarations, not runtime output validation; tests validate actual receipts.
+
+Pre-registration failures have `run:null`. Run receipts expose task identity, registry-confirmed liveness, lifecycle state/outcome, timing, evidence integrity (`complete`, `incomplete`, `damaged`, or `unknown`), output availability/delivery, and inspect references when resolvable. Missing evidence does not turn a settled successful run into an uncertain execution. While a run is live, `incomplete` means evidence has not yet been finalized, not that execution failed. Unreadable evidence reports `unknown` without discarding the child result. Private evidence paths and launch/configuration are not included.
+
+Only complete canonical results are inline, within **16 KiB of UTF-8 JSON after secret redaction**. Larger values use references. False, null, zero, and empty strings are valid results. Partial narration is never the canonical value. Both model-visible channels use the existing secret redactor; `warnings` includes `output_redacted` when it changes canonical output. this is best-effort pattern redaction, not a guarantee that arbitrary sensitive prose is identified.
+
+Codes include `configuration_invalid`, `harness_unavailable`, `selection_invalid`, `model_unavailable`, `context_invalid`, `session_closed`, and terminal outcomes `failed`, `cancelled`, `timed_out`. Unexpected exceptions remain host errors, as do predispatch schema/permission failures. A content-replacing host redaction hook drops structured content unless it explicitly supplies a replacement.
+
+Background `ok:true` means accepted, not completed. Await foreground calls; use `background:true` for work that must outlive a codemode script. Inspect/wait through the existing `external_runs` API; its versioned contract is separate work in #77.
+
+Pi 0.99.2 generates a useful discriminated return type (native `describeTool` result: 2941 UTF-8 bytes). Its input declaration currently loses all input properties because Pi renders the existing root `anyOf` constraints before properties; input validation itself remains intact. This is a known input-discovery limitation, not a runtime validation bypass.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tranhoangnguyen0310/pi-flow-external",
-  "version": "3.0.0-external.0",
+  "version": "3.1.1-external.0",
   "description": "External Claude Code, Codex CLI, Antigravity, Grok Build CLI, Muse Code, and OpenCode delegation for pi.",
   "type": "module",
   "main": "./index.ts",
@@ -9,6 +9,7 @@
     "index.ts",
     "src",
     "scripts/field-report.mjs",
+    "docs/agent-public-contract.md",
     "docs/ARCHITECTURE_SNAPSHOT.md",
     "docs/field-testing.md",
     "docs/releasing.md",
@@ -42,17 +43,17 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-agent-core": "~0.99.2",
+    "@earendil-works/pi-ai": "~0.99.2",
+    "@earendil-works/pi-coding-agent": "~0.99.2",
+    "@earendil-works/pi-tui": "~0.99.2",
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.79.4",
-    "@earendil-works/pi-ai": "0.79.4",
-    "@earendil-works/pi-coding-agent": "0.79.4",
-    "@earendil-works/pi-tui": "0.79.4",
+    "@earendil-works/pi-agent-core": "0.99.2",
+    "@earendil-works/pi-ai": "0.99.2",
+    "@earendil-works/pi-coding-agent": "0.99.2",
+    "@earendil-works/pi-tui": "0.99.2",
     "@types/node": "^24.12.4",
     "typebox": "1.1.38",
     "typescript": "^5.9.3",

package/src/core/errors.ts

@@ -0,0 +1,10 @@
+export const FLOW_ERROR_CODES = ["configuration_invalid", "harness_unavailable", "selection_invalid", "model_unavailable", "context_invalid", "session_closed", "failed", "cancelled", "timed_out"] as const;
+export type FlowErrorCode = (typeof FLOW_ERROR_CODES)[number];
+
+/** Expected caller/configuration failure, distinct from a programming error. */
+export class ExpectedFlowError extends Error {
+  constructor(readonly code: FlowErrorCode, message: string) {
+    super(message);
+    this.name = "ExpectedFlowError";
+  }
+}

package/src/core/parent-context.ts

@@ -1,3 +1,4 @@
+import { ExpectedFlowError } from "./errors.ts";
 import { buildSessionContext, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 
@@ -20,12 +21,12 @@ export interface ParentContextReceipt {
 
 export function parseParentContext(value: unknown): ParentContext | undefined {
   if (value === undefined) return undefined;
-  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("context must be an object");
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new ExpectedFlowError("context_invalid", "context must be an object");
   const { mode, turns } = value as Record<string, unknown>;
   if (!["none", "recent", "full"].includes(mode as string) ||
       Object.keys(value).some((key) => key !== "mode" && !(mode === "recent" && key === "turns")) ||
       (mode === "recent" && (typeof turns !== "number" || !Number.isSafeInteger(turns) || turns < 1))) {
-    throw new Error("context must be {mode:'none'}, {mode:'recent',turns:positive integer}, or {mode:'full'}");
+    throw new ExpectedFlowError("context_invalid", "context must be {mode:'none'}, {mode:'recent',turns:positive integer}, or {mode:'full'}");
   }
   return mode === "recent" ? { mode, turns: turns as number } : { mode: mode as "none" | "full" };
 }
@@ -46,8 +47,8 @@ export function prepareParentContext(
   const context = parseParentContext(selection);
   if (!context || context.mode === "none") return { prompt };
   const resumeId = typeof resume === "string" && resume.trim() !== "" ? resume.trim() : undefined;
-  if (resumeId !== undefined) throw new Error("context sharing cannot be combined with resume; continue the child or start a new one");
-  if (!messages) throw new Error("Parent context is unavailable; use context:none and a self-contained prompt");
+  if (resumeId !== undefined) throw new ExpectedFlowError("context_invalid", "context sharing cannot be combined with resume; continue the child or start a new one");
+  if (!messages) throw new ExpectedFlowError("context_invalid", "Parent context is unavailable; use context:none and a self-contained prompt");
   const compacted = messages.some((message) => message.role === "compactionSummary");
   let start = 0;
   if (context.mode === "recent") {
@@ -64,6 +65,8 @@ export function prepareParentContext(
   const transcript: unknown[] = [];
   let sharedTurns = 0;
   for (const message of selected) {
+    // SDK transcripts include system messages; sharing excludes their content.
+    if (message.role === "system") continue;
     if (message.role === "bashExecution") {
       if (!message.excludeFromContext) transcript.push({ role: message.role, command: message.command, output: message.output, exitCode: message.exitCode, truncated: message.truncated });
       continue;
@@ -73,7 +76,7 @@ export function prepareParentContext(
       continue;
     }
     if (message.role !== "user" && message.role !== "assistant" && message.role !== "toolResult" && message.role !== "custom") {
-      throw new Error("Unsupported parent context message role");
+      throw new ExpectedFlowError("context_invalid", "Unsupported parent context message role");
     }
     if (message.role === "toolResult" && message.toolCallId === toolCallId) continue;
     if (message.role === "toolResult") {
@@ -91,7 +94,7 @@ export function prepareParentContext(
       if (block.type === "text") blocks.push({ type: "text", text: block.text });
       else if (block.type === "toolCall") {
         if (completed.has(block.id)) blocks.push({ type: "toolCall", id: block.id, name: block.name, arguments: block.arguments });
-      } else throw new Error(`Unsupported parent context content: ${block.type}; share fewer turns or provide a text briefing`);
+      } else throw new ExpectedFlowError("context_invalid", `Unsupported parent context content: ${block.type}; share fewer turns or provide a text briefing`);
     }
     if (blocks.length) transcript.push({ role: message.role, content: blocks,
       ...(message.role === "toolResult" ? { toolCallId: message.toolCallId, toolName: message.toolName, isError: message.isError } : {}),
@@ -101,7 +104,7 @@ export function prepareParentContext(
   const text = JSON.stringify(transcript);
   const bytes = Buffer.byteLength(text, "utf8");
   // ponytail: fixed transport ceiling, backend-specific token budgeting if needed.
-  if (bytes > 1024 * 1024) throw new Error("Parent context is too large (over 1 MiB); share fewer turns or provide a text briefing. Nothing was truncated.");
+  if (bytes > 1024 * 1024) throw new ExpectedFlowError("context_invalid", "Parent context is too large (over 1 MiB); share fewer turns or provide a text briefing. Nothing was truncated.");
   const receipt: ParentContextReceipt = { mode: context.mode, ...(context.mode === "recent" ? { requestedTurns: context.turns } : {}), sharedTurns, messages: transcript.length, bytes, compacted };
   return {
     context: receipt,

package/src/core/run-registry.ts

@@ -1,3 +1,4 @@
+import { ExpectedFlowError } from "./errors.ts";
 export type RegisteredRunKind = "agent" | "workflow";
 export type RegisteredRunState = "running" | "terminal";
 export type RegisteredRunStatus = "done" | "error" | "aborted";
@@ -82,7 +83,7 @@ export class RunRegistry {
 
   start<T>(params: StartRegisteredRun<T>): RegisteredRunHandle<T> {
     if (this.closedSessions.has(params.sessionId) || (params.sessionVersion !== undefined && params.sessionVersion !== this.sessionVersion(params.sessionId))) {
-      throw new Error(`Session ${params.sessionId} is closed; run was not started`);
+      throw new ExpectedFlowError("session_closed", `Session ${params.sessionId} is closed; run was not started`);
     }
     if (this.entries.has(params.runId)) {
       throw new Error(`Run is already registered: ${params.runId}`);

package/src/core/spawn.ts

@@ -2,6 +2,7 @@ import {
   createAgentSession,
   DefaultResourceLoader,
   getAgentDir,
+  ModelRuntime,
   SessionManager,
   SettingsManager,
   type ExtensionContext,
@@ -925,12 +926,33 @@ async function spawnSubagentRuntime(params: SpawnSubagentRuntimeParams): Promise
     // markModified()/save(), so this still never reaches the settings file.
     settingsManager.applyOverrides({ retry: { enabled: false } });
 
+    // The extension context exposes a registry, not its owning runtime. Rebuild
+    // from the same files and carry over in-memory provider/auth registrations.
+    if (model.api === "pi-virtual") {
+      throw new Error("Named Pi harnesses require a physical model; virtual model registrations cannot be inherited through the SDK registry.");
+    }
+    const modelRuntime = await ModelRuntime.create({
+      authPath: join(agentDir, "auth.json"),
+      modelsPath: join(agentDir, "models.json"),
+    });
+    for (const id of ctx.modelRegistry.getRegisteredProviderIds()) {
+      const native = ctx.modelRegistry.getRegisteredNativeProvider(id);
+      if (native) modelRuntime.registerNativeProvider(native);
+      const config = ctx.modelRegistry.getRegisteredProviderConfig(id);
+      if (config) modelRuntime.registerProvider(id, config);
+    }
+    if (ctx.modelRegistry.getProviderAuthStatus(model.provider).source === "runtime") {
+      const key = await ctx.modelRegistry.getApiKeyForProvider(model.provider);
+      if (key) await modelRuntime.setRuntimeApiKey(model.provider, key);
+    }
+    if (signal?.aborted) throw new Error("Subagent aborted before prompt start");
+
     ({ session } = await createAgentSession({
       cwd,
       agentDir,
       model,
       thinkingLevel: thinkingLevel as NonNullable<Parameters<typeof createAgentSession>[0]>["thinkingLevel"],
-      modelRegistry: ctx.modelRegistry,
+      modelRuntime,
       settingsManager,
       sessionManager: SessionManager.inMemory(cwd),
       resourceLoader,

package/src/external-runs.ts

@@ -1,5 +1,5 @@
 import { StringEnum } from "@earendil-works/pi-ai";
-import { defineTool, type ExtensionContext, type Theme, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type ExtensionContext, type Theme, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Container, Text } from "@earendil-works/pi-tui";
 import { Type, type Static } from "typebox";
 import { createHash } from "node:crypto";
@@ -12,7 +12,7 @@ import { renderOutputText } from "./core/subagent-render.ts";
 import { SPINNER_INTERVAL_MS } from "./core/spinner.ts";
 import { EXTERNAL_RUNS_PROMPT_SNIPPET } from "./prompts.ts";
 import type { WorkflowToolDetails } from "./types.ts";
-import { getSessionWorkflowDir, listWorkflowJournals, loadWorkflowJournal, type LoadedWorkflowJournal } from "./workflow/journal.ts";
+import { getSessionWorkflowDir, listWorkflowJournals, loadWorkflowJournal, WorkflowJournalReadError, type LoadedWorkflowJournal, type UnreadableWorkflowJournal } from "./workflow/journal.ts";
 
 const RUN_ID = /^(?:run|wf)_[A-Za-z0-9_-]{1,128}$/;
 const WORKFLOW_ID = /^wf_[A-Za-z0-9_-]{1,128}$/;
@@ -219,6 +219,97 @@ function journalSummary(journal: LoadedWorkflowJournal, allChildren = false) {
   };
 }
 
+/** A listed journal that could not be loaded: one uncertain row instead of a failed listing. */
+function unreadableJournalSummary(journal: UnreadableWorkflowJournal) {
+  return {
+    ...projectWorkflowRun({
+      runId: journal.runId,
+      live: false,
+      status: "interrupted_or_uncertain",
+      error: clip(journal.unreadable),
+      resultAvailable: false,
+      finalAvailable: false,
+    }),
+    children: [],
+  };
+}
+
+/** Mirrors the listing's own inclusion rule, so a journal is counted persisted exactly when some page lists it. */
+async function hasWorkflowJournal(dir: string, runId: string, project: string): Promise<boolean> {
+  try {
+    return (await loadWorkflowJournal(dir, runId))?.project === project;
+  } catch (error) {
+    const owner = error instanceof WorkflowJournalReadError ? error.project : undefined;
+    return owner === undefined || owner === project;
+  }
+}
+
+function listScope(stream: "runs" | "workflows", sessionId: string, project: string, workflowRunId?: string): string {
+  return JSON.stringify({ stream, sessionId, project, workflowRunId });
+}
+
+type UnpersistedBookmark = { after: string } | { persisted: true };
+
+function encodeUnpersistedCursor(scope: string, bookmark: UnpersistedBookmark): string {
+  return Buffer.from(JSON.stringify({ v: 1, kind: "unpersisted-list", scope, ...bookmark })).toString("base64url");
+}
+
+/** The bookmark of an unpersisted-stage cursor, or undefined for any other cursor (passed on to the persisted listing). */
+function decodeUnpersistedCursor(value: string, scope: string): UnpersistedBookmark | undefined {
+  let parsed: Record<string, unknown> | undefined;
+  try {
+    parsed = record(JSON.parse(Buffer.from(value, "base64url").toString("utf8")));
+  } catch {
+    return undefined;
+  }
+  if (parsed?.kind !== "unpersisted-list") return undefined;
+  const keys = Object.keys(parsed).sort().join(",");
+  const valid = parsed.v === 1 && ((keys === "after,kind,scope,v" && typeof parsed.after === "string" && RUN_ID.test(parsed.after)) || (keys === "kind,persisted,scope,v" && parsed.persisted === true));
+  if (!valid) throw new Error("Invalid list cursor");
+  if (parsed.scope !== scope) throw new Error("Cursor belongs to a different list scope");
+  return typeof parsed.after === "string" ? { after: parsed.after } : { persisted: true };
+}
+
+/**
+ * One bounded list page: live runs with no persisted row first, then
+ * persisted rows, all within `pageSize`. The unpersisted stage bookmarks the
+ * last run it served, in registry order. Persisting a run never removes it
+ * from the registry, so a later page always resumes after the same run and
+ * none is skipped. If the bookmarked run has left the registry, continuation
+ * fails as stale rather than guessing. A run persisted between pages may
+ * appear in both stages; a run registered after the listing reached its
+ * persisted stage appears in the next fresh listing.
+ */
+async function pageUnpersistedFirst<L extends { runId: string }, D>(
+  scope: string,
+  cursor: string | undefined,
+  pageSize: number,
+  candidates: L[],
+  isUnpersisted: (candidate: L) => Promise<boolean>,
+  persisted: (limit: number, cursor: string | undefined) => Promise<{ items: D[]; nextCursor?: string }>,
+): Promise<{ live: L[]; items: D[]; nextCursor?: string }> {
+  const bookmark = cursor === undefined ? undefined : decodeUnpersistedCursor(cursor, scope);
+  if (cursor !== undefined && bookmark === undefined) return { live: [], ...await persisted(pageSize, cursor) };
+  if (bookmark && "persisted" in bookmark) return { live: [], ...await persisted(pageSize, undefined) };
+  let start = 0;
+  if (bookmark) {
+    const index = candidates.findIndex((candidate) => candidate.runId === bookmark.after);
+    if (index < 0) throw new Error("Run list changed while paging; restart the listing without a cursor");
+    start = index + 1;
+  }
+  // Find one more than fits, to know whether the unpersisted stage continues.
+  const live: L[] = [];
+  for (let index = start; index < candidates.length && live.length <= pageSize; index++) {
+    if (await isUnpersisted(candidates[index]!)) live.push(candidates[index]!);
+  }
+  if (live.length > pageSize) {
+    const served = live.slice(0, pageSize);
+    return { live: served, items: [], nextCursor: encodeUnpersistedCursor(scope, { after: served.at(-1)!.runId }) };
+  }
+  if (live.length === pageSize) return { live, items: [], nextCursor: encodeUnpersistedCursor(scope, { persisted: true }) };
+  return { live, ...await persisted(pageSize - live.length, undefined) };
+}
+
 function projectionRevision(text: string): string {
   return createHash("sha256").update(text).digest("hex");
 }
@@ -655,16 +746,25 @@ function normalizeInspectSelectors(params: ExternalRunsParams): ExternalRunsPara
   return { ...params, runId, runIds };
 }
 
+// Commands and tools share this executor; it needs no tool-only host capabilities.
+type ExternalRunsTool = Omit<ToolDefinition<typeof externalRunsParameters, ExternalRunsDetails>, "execute"> & {
+  execute: (
+    toolCallId: string, params: ExternalRunsParams, signal: AbortSignal | undefined,
+    onUpdate: Parameters<ToolDefinition<typeof externalRunsParameters, ExternalRunsDetails>["execute"]>[3],
+    ctx: ExtensionContext,
+  ) => ReturnType<ToolDefinition<typeof externalRunsParameters, ExternalRunsDetails>["execute"]>;
+};
+
 export function createExternalRunsTool(
   options: CreateExternalRunsToolOptions,
-): ToolDefinition<typeof externalRunsParameters, ExternalRunsDetails> {
-  return defineTool({
+): ExternalRunsTool {
+  return {
     name: "external_runs",
     label: "External Runs",
     description: "List, inspect (single or batched summaries), wait for, or cancel session-owned external runs.",
     promptSnippet: EXTERNAL_RUNS_PROMPT_SNIPPET,
     parameters: externalRunsParameters,
-    async execute(_toolCallId, params: ExternalRunsParams, signal, onUpdate, ctx) {
+    async execute(_toolCallId, params: ExternalRunsParams, signal, onUpdate, ctx: ExtensionContext) {
       if (params.action === "inspect") {
         params = normalizeInspectSelectors(params);
         if (params.runId === undefined && params.runIds !== undefined && params.runIds.length === 1 && params.view !== undefined && params.view !== "summary") {
@@ -676,30 +776,44 @@ export function createExternalRunsTool(
 
       if (params.action === "list") {
         if (params.workflowRunId !== undefined && !WORKFLOW_ID.test(params.workflowRunId)) throw new Error("Invalid workflow run ID");
-        const page = params.workflowCursor && !params.cursor
-          ? { items: [] }
-          : await listRunRecords({
-              runsDirectory,
-              sessionId,
-              project,
-              workflowRunId: params.workflowRunId,
-              limit: params.limit,
-              cursor: params.cursor,
-            });
         const workflowDir = getSessionWorkflowDir(ctx);
-        const historical = !params.workflowRunId && workflowDir
-          ? await listWorkflowJournals(workflowDir, project, params.limit, params.workflowCursor)
-          : { items: [] };
-        const current = params.cursor || params.workflowCursor || params.workflowRunId
-          ? []
-          : options.registry.list(sessionId, project).filter((entry) => entry.kind === "workflow").map((entry) => liveSummary(entry));
-        const currentIds = new Set(current.map((entry) => entry.runId));
-        const workflows = [...current, ...historical.items.filter((journal) => !currentIds.has(journal.runId)).map((journal) => journalSummary(journal))];
-        const liveAgents = params.cursor || params.workflowCursor ? [] : options.registry.list(sessionId, project)
-          .filter((entry) => entry.kind === "agent" && (params.workflowRunId === undefined || entry.workflowRunId === params.workflowRunId))
-          .map(listedAgent);
-        const liveIds = new Set(liveAgents.map((entry) => entry.runId));
-        const runs = [...liveAgents, ...page.items.filter((entry) => !liveIds.has(entry.runId)).map(historicalAgent)];
+        // Live state overlays its persisted row on whichever page that row
+        // falls, so a live run is never shown as interrupted or listed twice.
+        // Live runs with no persisted row yet are paged first, inside the same
+        // limit, before the persisted rows begin.
+        const registered = new Map(options.registry.list(sessionId, project).map((entry) => [entry.runId, entry]));
+        const runScope = listScope("runs", sessionId, project, params.workflowRunId);
+        const page = params.workflowCursor && !params.cursor
+          ? { live: [], items: [] }
+          : await pageUnpersistedFirst(runScope, params.cursor, Math.max(1, Math.min(100, Math.floor(params.limit ?? 50))),
+            [...registered.values()].filter((entry) => entry.kind === "agent" && (params.workflowRunId === undefined || entry.workflowRunId === params.workflowRunId)),
+            async (entry) => {
+              const persisted = await getRunRecord(runsDirectory, entry.runId);
+              return !persisted || persisted.parentSessionId !== sessionId || persisted.project !== project
+                || (params.workflowRunId !== undefined && persisted.workflowRunId !== params.workflowRunId);
+            },
+            (limit, cursor) => listRunRecords({ runsDirectory, sessionId, project, workflowRunId: params.workflowRunId, limit, cursor }));
+        const historical = params.workflowRunId
+          ? { live: [], items: [] }
+          : await pageUnpersistedFirst(listScope("workflows", sessionId, project), params.workflowCursor, Math.max(1, Math.min(100, Math.floor(params.limit ?? 100))),
+            [...registered.values()].filter((entry) => entry.kind === "workflow"),
+            async (entry) => !workflowDir || !await hasWorkflowJournal(workflowDir, entry.runId, project),
+            async (limit, cursor) => workflowDir ? listWorkflowJournals(workflowDir, project, limit, cursor) : { items: [] });
+        const workflows = [
+          ...historical.live.map((entry) => liveSummary(entry)),
+          ...historical.items.map((journal) => {
+            const live = registered.get(journal.runId);
+            if (live?.kind === "workflow") return liveSummary(live);
+            return "unreadable" in journal ? unreadableJournalSummary(journal) : journalSummary(journal);
+          }),
+        ];
+        const runs = [
+          ...page.live.map(listedAgent),
+          ...page.items.map((item) => {
+            const live = registered.get(item.runId);
+            return live?.kind === "agent" ? listedAgent(live) : historicalAgent(item);
+          }),
+        ];
         const list = { workflows, runs, nextCursor: page.nextCursor, nextWorkflowCursor: historical.nextCursor };
         return result(JSON.stringify(list), list);
       }
@@ -981,5 +1095,5 @@ export function createExternalRunsTool(
     renderResult(toolResult, { expanded }, theme) {
       return renderExternalRunsResult(toolResult, theme, expanded);
     },
-  });
+  };
 }

package/src/harnesses.ts

@@ -3,24 +3,10 @@ import { loadExternalSettings, saveExternalSettings, externalSettingsPath, DEFAU
 import type { ThinkingLevel as SdkThinkingLevel } from "@earendil-works/pi-agent-core";
 import { PI_RESOURCE_PRESETS, type PiResourcePreset } from "./types.ts";
 
-/**
- * The pinned SDK exposes its thinking-level union only as a TypeScript type,
- * not a runtime-exported constant array, so this list is hand-maintained here.
- * The `as const satisfies` + AssertNever guards below make drift a compile
- * error rather than a procedural "re-check at upgrade time" reminder: if the
- * SDK's ThinkingLevel union gains or loses a member, `npm run check` fails
- * until this list is updated.
- */
+/** Flow deliberately supports six levels; SDK additions do not expand settings. */
 export const VALID_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const satisfies readonly SdkThinkingLevel[];
 
-type AssertNever<T extends never> = T;
-// Both directions must collapse to never: every SDK level is listed (no missing
-// members) and every listed value is a real SDK level (no extras — also
-// enforced by `satisfies`, but asserted symmetrically for clarity).
-type _MissingThinkingLevels = AssertNever<Exclude<SdkThinkingLevel, (typeof VALID_THINKING_LEVELS)[number]>>;
-type _ExtraThinkingLevels = AssertNever<Exclude<(typeof VALID_THINKING_LEVELS)[number], SdkThinkingLevel>>;
-
-export function isValidThinkingLevel(value: unknown): value is SdkThinkingLevel {
+export function isValidThinkingLevel(value: unknown): value is (typeof VALID_THINKING_LEVELS)[number] {
   return typeof value === "string" && (VALID_THINKING_LEVELS as readonly string[]).includes(value);
 }
 

package/src/pi-subagent.ts

@@ -1,3 +1,7 @@
+import { ExpectedFlowError } from "./core/errors.ts";
+import { agentOutputSchema, agentReceipt, type PublicError } from "./public-contract.ts";
+import { getRunRecord } from "./core/run-inspection.ts";
+import { redactSecrets } from "./core/run-record.ts";
 import {
   defineTool,
   getAgentDir,
@@ -37,7 +41,7 @@ import { captureParentContext, parentContextSchema, prepareParentContext } from
 import { resolvePermission, permissionLabel, resolveEffectivePermissionTier } from "./core/permissions.ts";
 import { pruneRunRecords, runRecordsDirectory } from "./core/retention.ts";
 import { createProgressNode, textResult, type AgentToolResult } from "./core/progress.ts";
-import { RunRegistry } from "./core/run-registry.ts";
+import { RunRegistry, type RegisteredRunEntry } from "./core/run-registry.ts";
 import { formatUsage, renderSubagentNode } from "./core/subagent-render.ts";
 import { SPINNER_INTERVAL_MS } from "./core/spinner.ts";
 import { createWorkflowTool } from "./workflow/tool.ts";
@@ -359,19 +363,34 @@ function createAgentTool(
     description: "Delegate one task to an external Claude Code, Codex CLI, Antigravity, Grok CLI, Muse Code, OpenCode, or registered Pi harness role.",
     promptSnippet: AGENT_PROMPT_SNIPPET,
     parameters: agentToolParameters,
+    outputSchema: agentOutputSchema,
     executionMode: "parallel",
     async execute(toolCallId, params, signal, onUpdate, ctx) {
-      const resume = typeof params.resume === "string" && params.resume.trim() !== "" ? params.resume.trim() : undefined;
-      const briefing = prepareParentContext(params.prompt, params.context,
-        params.context && params.context.mode !== "none" ? captureParentContext(ctx.sessionManager) : undefined,
-        toolCallId, resume);
       const state = getState();
+      const receipt = async (result: AgentToolResult, error?: PublicError, settled?: RegisteredRunEntry) => {
+        const details = result.details as SubagentToolDetails;
+        const durable = details.runId ? await getRunRecord(runRecordsDirectory(), details.runId).catch(() => undefined) : undefined;
+        // Evidence I/O may outlast the child: observe live state only after it.
+        const entry = settled ?? (details.runId ? state.registry.get(details.runId) : undefined);
+        const structuredContent = agentReceipt({ entry, integrity: durable?.integrity, error, inspectable: !!durable || !!(entry && state.registry.get(entry.runId)) });
+        return { ...result, content: redactSecrets(result.content) as typeof result.content, structuredContent, isError: !structuredContent.ok };
+      };
+      const resume = typeof params.resume === "string" && params.resume.trim() !== "" ? params.resume.trim() : undefined;
+      let briefing: ReturnType<typeof prepareParentContext>;
+      try {
+        briefing = prepareParentContext(params.prompt, params.context,
+          params.context && params.context.mode !== "none" ? captureParentContext(ctx.sessionManager) : undefined,
+          toolCallId, resume);
+      } catch (error) {
+        if (!(error instanceof ExpectedFlowError)) throw error;
+        return receipt(textResult(error.message, { description: params.description, subagentType: "unknown", status: "error", error: error.message }), error);
+      }
       const effectiveState: DelegationState = {
         ...state,
         progressEnabled: state.progressEnabled || shouldEnableProgress(ctx),
       };
       const catalog = loadExternalCatalog(getAgentDir());
-      if (catalog.blocked) return textResult(catalog.diagnostics.join(" "), { description: params.description, subagentType: "unknown", status: "error", error: catalog.diagnostics.join(" ") });
+      if (catalog.blocked) return receipt(textResult(catalog.diagnostics.join(" "), { description: params.description, subagentType: "unknown", status: "error", error: catalog.diagnostics.join(" ") }), { code: "configuration_invalid", message: catalog.diagnostics.join(" ") });
       const allProfiles = catalog.profiles;
       const harnessConfigs = catalog.harnessConfigs;
       const configuredHarnessNames: ReadonlySet<string> = new Set([...EXTERNAL_HARNESSES, ...harnessConfigs.keys()]);
@@ -388,12 +407,12 @@ function createAgentTool(
       const defaultHarness = requestedDefault.harness;
       if (params.role && !params.harness && !configuredHarnessNames.has(defaultHarness)) {
         const error = `Default harness "${defaultHarness}" is not registered (missing from settings.json); pass harness explicitly or recreate it via /external config harness create.`;
-        return textResult(error, {
+        return receipt(textResult(error, {
           description: params.description,
           subagentType: "unknown",
           status: "error",
           error,
-        });
+        }), { code: "harness_unavailable", message: error });
       }
       let profile: SubagentProfile;
       try {
@@ -403,8 +422,9 @@ function createAgentTool(
           subagentType: params.subagent_type,
         }, defaultHarness, { configuredHarnessNames, harnessConfigs, disabledHarnesses: catalog.disabledHarnesses });
       } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return textResult(
+        if (!(error instanceof ExpectedFlowError)) throw error;
+        const message = error.message;
+        return receipt(textResult(
           message,
           {
             description: params.description,
@@ -412,7 +432,7 @@ function createAgentTool(
             status: "error",
             error: message,
           },
-        );
+        ), { code: error.code, message });
       }
       const subagentType = profile.name;
       profile = resolveExecutionProfile(profile, options.getThinkingLevel(), state.defaultMaxBudgetUsd);
@@ -420,14 +440,14 @@ function createAgentTool(
       const model = resolveProfileModel(profile, ctx);
       if (usesPiBackend(profile) && !model) {
         const error = describeMissingModel(profile, ctx.modelRegistry);
-        return textResult(`Cannot launch subagent: ${error}.`, {
+        return receipt(textResult(`Cannot launch subagent: ${error}.`, {
           description: params.description,
           subagentType,
           backend: profile.backend,
           harness: selectorHarness(profile),
           status: "error",
           error,
-        });
+        }), { code: "model_unavailable", message: error });
       }
 
       const queuedAt = Date.now();
@@ -565,7 +585,9 @@ function createAgentTool(
         }
       };
 
-      const registered = state.registry.start({
+      let registered;
+      try {
+        registered = state.registry.start({
         runId: runRecord.runId,
         kind: "agent",
         sessionId,
@@ -585,8 +607,20 @@ function createAgentTool(
           };
         },
       });
-      if (!background) return await registered.result;
-      return textResult(
+      } catch (error) {
+        if (!(error instanceof ExpectedFlowError)) throw error;
+        await runRecord.finish({ status: "error", error: error.message, backendStarted: false });
+        return receipt(textResult(error.message, { description: params.description, subagentType, status: "error", error: error.message }), error);
+      }
+      if (!background) {
+        const result = await registered.result;
+        const outcome = await registered.terminal;
+        return receipt(result, undefined, {
+          runId: runRecord.runId, kind: "agent", sessionId, project, state: "terminal",
+          observation: (result.details as SubagentToolDetails).progress ?? progress, outcome,
+        });
+      }
+      return receipt(textResult(
         `Subagent "${params.description}" (${subagentType}) queued as ${runRecord.runId}. Use external_runs to inspect, wait, or cancel it.`,
         {
           description: params.description,
@@ -599,7 +633,7 @@ function createAgentTool(
           progress,
           backgroundReceipt: true,
         },
-      );
+      ));
     },
     renderCall(args, theme, context) {
       const defaultHarness = options.getDefaultHarness(context.cwd);

package/src/profiles.ts

@@ -1,3 +1,4 @@
+import { ExpectedFlowError } from "./core/errors.ts";
 import { existsSync, readdirSync, readFileSync, lstatSync } from "node:fs";
 import { basename, join } from "node:path";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
@@ -431,7 +432,7 @@ export function reconcilePiProfileWithHarness(
   harnessConfigs: ReadonlyMap<string, HarnessConfig>,
 ): SubagentProfile {
   const { profile: reconciled, conflict } = computeReconciledPiProfile(profile, harnessConfigs);
-  if (conflict) throw new Error(conflict);
+  if (conflict) throw new ExpectedFlowError("selection_invalid", conflict);
   return reconciled;
 }
 
@@ -522,36 +523,36 @@ export function resolveExternalProfile(
 
   if (subagentType) {
     if (role || harness) {
-      throw new Error("Choose either role (with optional harness) or legacy subagent_type; do not combine them.");
+      throw new ExpectedFlowError("selection_invalid", "Choose either role (with optional harness) or legacy subagent_type; do not combine them.");
     }
     const matches = [...profiles.values()].filter(p => p.configVersion === 5 && p.role && `${selectorHarness(p)}-${p.role}` === subagentType);
-    if (!profiles.has(subagentType) && matches.length > 1) throw new Error(`Ambiguous legacy selector "${subagentType}"; use role and harness explicitly.`);
+    if (!profiles.has(subagentType) && matches.length > 1) throw new ExpectedFlowError("selection_invalid", `Ambiguous legacy selector "${subagentType}"; use role and harness explicitly.`);
     const profile = profiles.get(subagentType) ?? matches[0];
     if (!profile) {
-      throw new Error(unknownExternalProfileMessage(subagentType, profiles.keys()));
+      throw new ExpectedFlowError("selection_invalid", unknownExternalProfileMessage(subagentType, profiles.keys()));
     }
-    if (profile.configurationError) throw new Error(profile.configurationError);
+    if (profile.configurationError) throw new ExpectedFlowError("selection_invalid", profile.configurationError);
     return reconcilePiProfileWithHarness(profile, harnessConfigs);
   }
 
   if (!role) {
-    throw new Error(harness
+    throw new ExpectedFlowError("selection_invalid", harness
       ? "role is required when harness is provided; otherwise provide role or legacy subagent_type."
       : "Either role or legacy subagent_type is required.");
   }
   const selectedHarness = harness || defaultHarness;
   if (!configuredHarnessNames.has(selectedHarness)) {
-    throw new Error(`Unknown external harness "${selectedHarness}". Choose one of: ${[...configuredHarnessNames].join(", ") || "none"}.`);
+    throw new ExpectedFlowError("selection_invalid", `Unknown external harness "${selectedHarness}". Choose one of: ${[...configuredHarnessNames].join(", ") || "none"}.`);
   }
   if ((options.disabledHarnesses ?? DEFAULT_RESOLVE_OPTIONS.disabledHarnesses).has(selectedHarness)) {
-    throw new Error(disabledHarnessMessage(selectedHarness, !harness));
+    throw new ExpectedFlowError("selection_invalid", disabledHarnessMessage(selectedHarness, !harness));
   }
 
   const legacy = profiles.get(`${selectedHarness}-${role}`);
   const exact = profiles.get(bindingKey(selectedHarness, role)) ?? (legacy?.configVersion === 5 ? undefined : legacy);
   if (exact) {
-    if (exact.configurationError) throw new Error(exact.configurationError);
-    if (selectorHarness(exact) !== selectedHarness || externalProfileRole(exact) !== role) throw new Error(`Override "${exact.name}" does not match selected harness "${selectedHarness}".`);
+    if (exact.configurationError) throw new ExpectedFlowError("selection_invalid", exact.configurationError);
+    if (selectorHarness(exact) !== selectedHarness || externalProfileRole(exact) !== role) throw new ExpectedFlowError("selection_invalid", `Override "${exact.name}" does not match selected harness "${selectedHarness}".`);
     return reconcilePiProfileWithHarness(exact, harnessConfigs);
   }
 
@@ -566,12 +567,12 @@ export function resolveExternalProfile(
   const availability = externalRoleAvailability(profiles);
   const supported = availability.get(role);
   if (supported?.length) {
-    throw new Error(
+    throw new ExpectedFlowError("selection_invalid",
       `Role "${role}" is unavailable for harness "${selectedHarness}". Supported harnesses for this role: ${supported.join(", ")}. Choose one of those harnesses or add profile "${selectedHarness}-${role}".`,
     );
   }
   const knownRoles = new Set([...availability.keys(), ...(EXTERNAL_HARNESSES.includes(selectedHarness as ExternalHarness) ? [] : defaultRoleNames())]);
-  throw new Error(
+  throw new ExpectedFlowError("selection_invalid",
     `Unknown external role "${role}". Available roles: ${[...knownRoles].join(", ") || "none"}. Nonstandard profile names must be selected with legacy subagent_type.`,
   );
 }

package/src/public-contract.ts

@@ -0,0 +1,73 @@
+import { StringEnum, type JsonObject } from "@earendil-works/pi-ai";
+import { Type, type Static } from "typebox";
+import { projectLiveAgent } from "./core/run-projection.ts";
+import type { RegisteredRunEntry } from "./core/run-registry.ts";
+import { FLOW_ERROR_CODES } from "./core/errors.ts";
+import { redactSecrets } from "./core/run-record.ts";
+
+export const INLINE_RESULT_BYTES = 16 * 1024;
+const strings = <T extends string[]>(...values: T) => StringEnum(values);
+const errorSchema = Type.Object({ code: StringEnum(FLOW_ERROR_CODES), message: Type.String() });
+const inspectRef = Type.Object({ tool: Type.Literal("external_runs"), action: Type.Literal("inspect"), runIds: Type.Array(Type.String()), view: strings("summary", "final", "diagnostics") });
+const runSchema = Type.Object({
+  runId: Type.String(), kind: Type.Literal("agent"), live: Type.Boolean(),
+  task: Type.Object({ description: Type.Optional(Type.String()), profile: Type.Optional(Type.String()), backend: Type.Optional(Type.String()), harness: Type.Optional(Type.String()) }),
+  state: Type.Object({ status: strings("queued", "running", "done", "error", "aborted"), outcome: Type.Optional(strings("succeeded", "failed", "cancelled", "timed_out")) }),
+  timing: Type.Object({
+    queuedAt: Type.Optional(Type.String()), executionStartedAt: Type.Optional(Type.String()),
+    processStartedAt: Type.Optional(Type.String()), firstActivityAt: Type.Optional(Type.String()),
+    lastActivityAt: Type.Optional(Type.String()), finishedAt: Type.Optional(Type.String()),
+    queueDelayMs: Type.Optional(Type.Number()), elapsedMs: Type.Optional(Type.Number()),
+    activityAgeMs: Type.Optional(Type.Number()), processDurationMs: Type.Optional(Type.Number()),
+  }),
+  output: Type.Object({ available: Type.Boolean(), finalAvailable: Type.Boolean(), delivery: strings("inline", "reference", "none"), value: Type.Optional(Type.Unknown()) }),
+  evidence: Type.Object({ integrity: strings("complete", "incomplete", "damaged", "unknown") }),
+  refs: Type.Optional(Type.Object({ summary: inspectRef, final: inspectRef, diagnostics: inspectRef })),
+});
+const common = {
+  contractVersion: Type.Literal(1), tool: Type.Literal("Agent"), action: Type.Literal("delegate"),
+  observedAt: Type.String(), data: Type.Object({ run: Type.Union([Type.Null(), runSchema]) }),
+  warnings: Type.Array(Type.String()),
+};
+export const agentOutputSchema = Type.Union([
+  Type.Object({ ...common, ok: Type.Literal(true), error: Type.Optional(Type.Never()) }),
+  Type.Object({ ...common, ok: Type.Literal(false), error: errorSchema }),
+]);
+export type AgentReceipt = Static<typeof agentOutputSchema>;
+export type PublicError = Static<typeof errorSchema>;
+
+/** Only registry-confirmed entries may supply a public handle. Never infer liveness from disk. */
+export function agentReceipt({ entry, integrity = "unknown", error, inspectable = true }: {
+  entry?: RegisteredRunEntry;
+  integrity?: "complete" | "incomplete" | "damaged" | "unknown";
+  error?: PublicError;
+  inspectable?: boolean;
+}): AgentReceipt & JsonObject {
+  const warnings: string[] = [];
+  let run: AgentReceipt["data"]["run"] = null;
+  if (entry) {
+    const projected = projectLiveAgent(entry);
+    const value = entry.outcome?.result;
+    const finalAvailable = projected.output.finalAvailable;
+    let encoded: string | undefined;
+    try { encoded = finalAvailable ? JSON.stringify(value) : undefined; } catch { /* Non-JSON values are never presented as complete. */ }
+    const redacted = encoded === undefined ? undefined : redactSecrets(JSON.parse(encoded));
+    const original = encoded;
+    encoded = encoded === undefined ? undefined : JSON.stringify(redacted);
+    if (encoded !== original) warnings.push("output_redacted");
+    const inline = encoded !== undefined && Buffer.byteLength(encoded, "utf8") <= INLINE_RESULT_BYTES;
+    const ref = (view: "summary" | "final" | "diagnostics") => ({ tool: "external_runs" as const, action: "inspect" as const, runIds: [entry.runId], view });
+    run = {
+      runId: entry.runId, kind: "agent", live: projected.live, task: projected.task,
+      state: { status: projected.state.status as NonNullable<AgentReceipt["data"]["run"]>["state"]["status"], ...(entry.outcome ? { outcome: entry.outcome.outcome } : {}) },
+      timing: projected.timing,
+      output: { available: projected.output.available, finalAvailable, delivery: inline ? "inline" : finalAvailable && inspectable ? "reference" : "none", ...(inline ? { value: redacted } : {}) },
+      evidence: { integrity }, ...(inspectable ? { refs: { summary: ref("summary"), final: ref("final"), diagnostics: ref("diagnostics") } } : {}),
+    };
+    if (!error && entry.outcome && entry.outcome.status !== "done") {
+      error = { code: entry.outcome.outcome === "succeeded" ? "failed" : entry.outcome.outcome, message: entry.outcome.error ?? "Child execution failed" };
+    }
+  }
+  const base = { contractVersion: 1 as const, tool: "Agent" as const, action: "delegate" as const, observedAt: new Date().toISOString(), data: { run }, warnings };
+  return JSON.parse(JSON.stringify(redactSecrets(error ? { ...base, ok: false, error: { code: error.code, message: error.message } } : { ...base, ok: true }))) as AgentReceipt & JsonObject;
+}

package/src/workflow/journal.ts

@@ -41,6 +41,14 @@ export interface LoadedWorkflowJournal {
   children: Array<{ index: number; runId?: string; label?: string; status: "queued" | "done" | "error" | "aborted"; outcome?: ChildRunOutcome; error?: unknown }>;
 }
 
+/** A journal that exists but cannot be loaded; `project` is set when its own run_start line names one. */
+export class WorkflowJournalReadError extends Error {
+  constructor(message: string, readonly project?: string) {
+    super(message);
+    this.name = "WorkflowJournalReadError";
+  }
+}
+
 export interface WorkflowJournalWriter {
   runId: string;
   path: string;
@@ -128,8 +136,9 @@ export async function loadWorkflowJournal(dir: string, runId: string): Promise<L
     }
     if (entry.type === "run_start") {
       if (entry.version !== JOURNAL_VERSION || entry.apiVersion !== WORKFLOW_API_VERSION) {
-        throw new Error(
+        throw new WorkflowJournalReadError(
           `Workflow journal ${path} uses an incompatible API contract; recompose with meta.apiVersion: ${WORKFLOW_API_VERSION}. No children were launched`,
+          typeof entry.project === "string" ? entry.project : undefined,
         );
       }
       seenRunStart = entry.runId === runId;
@@ -190,13 +199,19 @@ export async function loadWorkflowJournal(dir: string, runId: string): Promise<L
   }
 
   if (!seenRunStart) {
-    throw new Error(`Workflow journal ${path} does not match run id ${runId}`);
+    throw new WorkflowJournalReadError(`Workflow journal ${path} does not match run id ${runId}`, project);
   }
   return { launch, runId, path, agentResults, name, source, project, status, outcome, result, error: terminalError, children: children.filter(Boolean) };
 }
 
+/** A listed journal that failed to load: shown as its own row instead of failing the whole listing. */
+export interface UnreadableWorkflowJournal {
+  runId: string;
+  unreadable: string;
+}
+
 export interface WorkflowJournalPage {
-  items: LoadedWorkflowJournal[];
+  items: Array<LoadedWorkflowJournal | UnreadableWorkflowJournal>;
   nextCursor?: string;
 }
 
@@ -228,12 +243,19 @@ export async function listWorkflowJournals(dir: string, project: string, limit =
   }
   const start = workflowListStart(names, cursor);
   const pageLimit = Math.max(1, Math.min(100, limit));
-  const journals: LoadedWorkflowJournal[] = [];
+  const journals: WorkflowJournalPage["items"] = [];
   let index = start;
   for (; index < names.length && index < start + 200; index++) {
     const name = names[index]!;
-    const journal = await loadWorkflowJournal(dir, name.slice(4, -6));
-    if (journal?.project === project) journals.push(journal);
+    const runId = name.slice(4, -6);
+    try {
+      const journal = await loadWorkflowJournal(dir, runId);
+      if (journal?.project === project) journals.push(journal);
+    } catch (error) {
+      // The directory is this session's own; a journal whose project cannot be read is still listed so it is never silently dropped.
+      const owner = error instanceof WorkflowJournalReadError ? error.project : undefined;
+      if (owner === undefined || owner === project) journals.push({ runId, unreadable: error instanceof Error ? error.message : String(error) });
+    }
     if (journals.length >= pageLimit) {
       index++;
       break;

package/src/workflow/source.ts

@@ -6,6 +6,7 @@ import {
   createWorkflowJournalWriter,
   createWorkflowRunIdentity,
   getSessionWorkflowDir,
+  WorkflowJournalReadError,
   loadWorkflowJournal,
   persistWorkflowScript,
   type WorkflowJournalWriter,
@@ -270,19 +271,23 @@ export async function prepareWorkflowToolSource(
     try {
       journal = await loadWorkflowJournal(sessionWorkflowDir, resumeFromRunId);
     } catch (error) {
-      const message = `Cannot resume workflow: ${error instanceof Error ? error.message : String(error)}`;
-      return sourceError(message, {
-        name: metaName,
-        error: message,
-        logs: source.warnings,
-        source: source.source,
-        sourcePath: source.sourcePath,
-        scriptPath,
-        runId: identity.runId,
-        resumeFromRunId,
-      });
+      // Another project's unreadable journal is reported exactly like a missing one.
+      if (!(error instanceof WorkflowJournalReadError) || error.project === undefined || error.project === project) {
+        const message = `Cannot resume workflow: ${error instanceof Error ? error.message : String(error)}`;
+        return sourceError(message, {
+          name: metaName,
+          error: message,
+          logs: source.warnings,
+          source: source.source,
+          sourcePath: source.sourcePath,
+          scriptPath,
+          runId: identity.runId,
+          resumeFromRunId,
+        });
+      }
     }
-    if (!journal) {
+    // Another project's run is indistinguishable from an unknown one.
+    if (!journal || journal.project !== project) {
       const message = `Cannot resume workflow: run journal not found for ${resumeFromRunId}.`;
       return sourceError(message, {
         name: metaName,
@@ -295,19 +300,6 @@ export async function prepareWorkflowToolSource(
         resumeFromRunId,
       });
     }
-    if (journal.project !== project) {
-      const message = `Cannot resume workflow: ${resumeFromRunId} belongs to a different project. No children were launched.`;
-      return sourceError(message, {
-        name: metaName,
-        error: message,
-        logs: source.warnings,
-        source: source.source,
-        sourcePath: source.sourcePath,
-        scriptPath,
-        runId: identity.runId,
-        resumeFromRunId,
-      });
-    }
     resumeAgentResults = journal.agentResults;
   }
 

package/src/workflow/tool.ts

@@ -18,7 +18,8 @@ import { CHILD_EXCLUDED_TOOLS, spawnSubagent } from "../core/spawn.ts";
 import { createRunRecord } from "../core/run-record.ts";
 import { runRecordsDirectory } from "../core/retention.ts";
 import { captureParentContext } from "../core/parent-context.ts";
-import { RunRegistry } from "../core/run-registry.ts";
+import { RunRegistry, type RegisteredRunHandle } from "../core/run-registry.ts";
+import { ExpectedFlowError } from "../core/errors.ts";
 import { OUTPUT_PREVIEW_CHARS } from "../core/progress.ts";
 import { loadExternalCatalog, resolveExternalProfile, selectorHarness, unknownExternalProfileMessage } from "../profiles.ts";
 import { resolveExecutionProfile } from '../execution-config.ts';
@@ -585,23 +586,33 @@ export function createWorkflowTool(
       }
       };
 
-      const registered = options.registry.start({
-        runId: identity.runId,
-        kind: "workflow",
-        sessionId,
-        sessionVersion,
-        project,
-        ...(background ? {} : { signal }),
-        run: executeWorkflow,
-        outcome: (result, workflowSignal) => ({
-          status: result.details.status === "completed" ? "done" : result.details.status === "aborted" ? "aborted" : "error",
-          outcome: result.details.outcome ?? (result.details.status === "completed" ? "succeeded" : result.details.status === "aborted" ? "cancelled" : "failed"),
-          ...(result.details.result !== undefined ? { result: result.details.result } : {}),
-          ...(workflowSignal.aborted && workflowSignal.reason !== undefined
-            ? { error: workflowSignal.reason instanceof Error ? workflowSignal.reason.message : String(workflowSignal.reason) }
-            : result.details.error ? { error: result.details.error } : {}),
-        }),
-      });
+      let registered: RegisteredRunHandle<ReturnType<typeof workflowResult>>;
+      try {
+        registered = options.registry.start({
+          runId: identity.runId,
+          kind: "workflow",
+          sessionId,
+          sessionVersion,
+          project,
+          ...(background ? {} : { signal }),
+          run: executeWorkflow,
+          outcome: (result, workflowSignal) => ({
+            status: result.details.status === "completed" ? "done" : result.details.status === "aborted" ? "aborted" : "error",
+            outcome: result.details.outcome ?? (result.details.status === "completed" ? "succeeded" : result.details.status === "aborted" ? "cancelled" : "failed"),
+            ...(result.details.result !== undefined ? { result: result.details.result } : {}),
+            ...(workflowSignal.aborted && workflowSignal.reason !== undefined
+              ? { error: workflowSignal.reason instanceof Error ? workflowSignal.reason.message : String(workflowSignal.reason) }
+              : result.details.error ? { error: result.details.error } : {}),
+          }),
+        });
+      } catch (error) {
+        // The run_start journal line is already written; settle it so the
+        // never-started run does not read as interrupted forever.
+        const message = error instanceof Error ? error.message : String(error);
+        await journalWriter?.fail(message).catch(() => undefined);
+        if (!(error instanceof ExpectedFlowError)) throw error;
+        return workflowError(`Workflow "${metaName}" was not started: ${message}`, { name: metaName, error: message, status: "error", outcome: "failed", runId: identity.runId, journalPath: journalWriter?.path });
+      }
       emit();
       if (!background) return await registered.result;
       return workflowResult(