@springbrand/agent-runtime 0.3.0-alpha.17 → 0.3.0-alpha.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.3.0-alpha.17",
+  "version": "0.3.0-alpha.18",
   "type": "module",
   "files": [
     "src",

package/src/adapter/cloudflare/agent.ts

@@ -71,7 +71,7 @@ import type {
 } from "@earendil-works/pi-ai";
 import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
 import { openCloudflareSession } from "../../session";
-import { openSessionHarness, prepareSubmissionOperation } from "../../harness";
+import { ModelRecovery, openSessionHarness, prepareSubmissionOperation } from "../../harness";
 import type { SessionHarness } from "../../harness";
 import {
   compileHarnessTools,
@@ -789,10 +789,13 @@ export abstract class AgentRuntimeKernel<
       (key) => this.ensureRuntimeVersion(key),
     );
     const activeRuntime = this.requireRuntime();
+    // A fresh provider Session per Submission keeps one failing upstream route from pinning later turns.
+    const recovery = new ModelRecovery(submissionId);
     const harnessInput = this.pi.harnessInputs(
       activeRuntime.pi,
       submission.assemblyDescriptor,
       {
+          modelSessionId: () => recovery.sessionId(),
           assertRequestAllowed: () => {
             const current = this.db.submissions.find(submissionId);
             if (current?.abortReason || current?.unattendedFailure) throw new Error(current.abortReason ?? current.unattendedFailure!);
@@ -875,6 +878,7 @@ export abstract class AgentRuntimeKernel<
       streamOptions: { maxRetries: 0 },
       compaction: harnessInput.compaction,
       toolExecution: "parallel",
+      recovery,
       beforeTool: (call, _api, context) => gate.beforeTool({ toolName: call.name, toolCallId: call.id, args: call.arguments }, context),
       afterResponse: (message) => {
         for (const part of message.content) if (part.type === "toolCall") part.arguments = prepareToolInput(part.name, part.arguments) as JsonObject;
@@ -883,6 +887,7 @@ export abstract class AgentRuntimeKernel<
     this.activeHarness = runtime;
     let stream: Awaited<ReturnType<typeof bindHarnessStream>> | undefined;
     let deactivate = () => {};
+    let released = false;
     try {
 
       if ((submission.abortReason || submission.unattendedFailure) && runtime.openOperation) {
@@ -985,6 +990,7 @@ export abstract class AgentRuntimeKernel<
             idempotent: true,
           });
         }
+        released = true;
         return this.db.submissions.find(submissionId)!;
       }
       const record = outcome.outcome;
@@ -1025,6 +1031,14 @@ export abstract class AgentRuntimeKernel<
       deactivate();
       if (this.activeHarness === runtime) this.activeHarness = undefined;
       await runtime.close(BACKGROUND_CONTEXT).catch(() => undefined);
+      if (released) {
+        // Pi closes the Harness on release and drops undelivered stream frames; the
+        // canonical transcript gives a paused question or approval its complete input.
+        this.broadcast(json({
+          type: MessageType.CF_AGENT_CHAT_MESSAGES,
+          messages: await this.getMessages(),
+        }));
+      }
     }
   }
 

package/src/adapter/cloudflare/subagent/definition.ts

@@ -424,6 +424,16 @@ export abstract class CloudflareSubAgent<
           const progress = progressFor(event);
           if (progress) this.persistProgress(runId, progress);
         },
+        // Live frames can stop short of the last response; the canonical entries are the billed total.
+        onEntries: (entries) => {
+          const canonical = emptySubagentUsage();
+          for (const entry of entries) {
+            const message = entry.model?.[0];
+            if (message?.role === "assistant") addSubagentUsage(canonical, message.usage);
+          }
+          Object.assign(usage, canonical);
+          this.persistUsage(runId, usage);
+        },
       });
       publish(projection.finish({ status: "completed", endedAt: Date.now() }));
       this.completeRun(runId, output, usage);

package/src/adapter/cloudflare/subagent/runner.ts

@@ -1,5 +1,5 @@
 import type { StreamFn } from "@earendil-works/pi-agent-core";
-import type { AgentEvent as HarnessEvent, Storage as Session, ToolRegistration } from "@earendil-works/pi-durable";
+import type { AgentEvent as HarnessEvent, AgentEventStream, EntryRecord, Storage as Session, ToolRegistration } from "@earendil-works/pi-durable";
 import {
   awaitWithContext,
   BACKGROUND_CONTEXT,
@@ -38,8 +38,21 @@ export interface CloudflareSubAgentRun {
   tools?: ToolRegistration<any, any>[];
   signal?: AbortSignal;
   timeoutMs?: number;
-  /** Native operation events for projections that must survive model retries. */
+  /** Native operation events for live projections; they may stop short of the final frame. */
   onEvent?: (event: HarnessEvent, signal: AbortSignal) => void | Promise<void>;
+  /** This operation's canonical entries after each settle or release, the source of its final usage. */
+  onEntries?: (entries: readonly EntryRecord[]) => void | Promise<void>;
+}
+
+/** The first failed Tool result among an operation's canonical entries. */
+function toolFailureOf(entries: readonly EntryRecord[]): { name: string; error: string } | undefined {
+  for (const entry of entries) {
+    const result = entry.model?.[0];
+    if (result?.role !== "toolResult" || !result.isError) continue;
+    const diagnostics = (entry.data as { diagnostics?: Array<{ severity: string; message: string }> } | undefined)?.diagnostics;
+    return { name: result.toolName, error: diagnostics?.find((item) => item.severity === "error")?.message ?? toolErrorText(result) };
+  }
+  return undefined;
 }
 
 function textOf(message: AssistantMessage): string {
@@ -129,7 +142,13 @@ export async function runCloudflareSubAgent(run: CloudflareSubAgentRun): Promise
     compaction: { enabled: false, reserveTokens: 1, keepRecentTokens: 1 },
   } satisfies Omit<SessionHarnessOptions, "storage">;
   let runtime: SessionHarness | undefined;
+  let events: AgentEventStream | undefined;
   let toolFailure: { name: string; error: string } | undefined;
+  const operationEntries = async (active: SessionHarness): Promise<EntryRecord[]> => {
+    const submission = await active.submissionFor(operationId, BACKGROUND_CONTEXT);
+    const entries = await active.entries(BACKGROUND_CONTEXT);
+    return submission?.entry === undefined ? [] : entries.filter((entry) => entry.id >= submission.entry!);
+  };
 
   let timedOut = false;
   const timeout = setTimeout(() => {
@@ -148,15 +167,9 @@ export async function runCloudflareSubAgent(run: CloudflareSubAgentRun): Promise
         if (runtime.openOperation && runtime.openOperation.operationId !== operationId) {
           throw new Error("SubAgent Session has an unrelated open operation");
         }
-        const watch = await runtime.watch(context);
-        watch.start(async (events) => {
-          for (const event of events) {
-            await run.onEvent?.(event, signal);
-            if (event.type === "tool_execution_end") {
-              const result = event.entry?.model?.[0];
-              if (result?.role === "toolResult" && result.isError) toolFailure ??= { name: event.toolName, error: ((event.entry?.data as { diagnostics?: Array<{ severity: string; message: string }> } | undefined)?.diagnostics?.find((item) => item.severity === "error")?.message ?? toolErrorText(result)) };
-            }
-          }
+        events = await runtime.watch(context);
+        events.start(async (batch) => {
+          for (const event of batch) await run.onEvent?.(event, signal);
         });
       }
       const result = await runtime.run(
@@ -168,12 +181,18 @@ export async function runCloudflareSubAgent(run: CloudflareSubAgentRun): Promise
           : undefined,
         context,
       );
+      await events?.stop();
+      events = undefined;
       if (result.kind === "released") {
         await runtime.close(BACKGROUND_CONTEXT);
         runtime = undefined;
         continue;
       }
       settled = result;
+      // Pi's stop may drop the last frames; failures and usage come from the canonical record.
+      const owned = await operationEntries(runtime);
+      toolFailure = toolFailureOf(owned);
+      await run.onEntries?.(owned);
       break;
     }
     if (timedOut) throw new Error("SubAgent run timed out");
@@ -215,6 +234,7 @@ export async function runCloudflareSubAgent(run: CloudflareSubAgentRun): Promise
       await runtime.abort(BACKGROUND_CONTEXT).catch(() => undefined);
       await runtime.run(undefined, BACKGROUND_CONTEXT).catch(() => undefined);
     }
+    await events?.stop();
     await runtime?.close(BACKGROUND_CONTEXT).catch(() => undefined);
   }
 }

package/src/config/harness-runtime.ts

@@ -91,7 +91,7 @@ export class HarnessRuntimeConfig {
     prepared: PreparedPiRuntime,
     pinnedDescriptor: string,
     request: {
-      readonly modelSessionId?: string;
+      readonly modelSessionId?: string | (() => string);
       readonly onGeneration?: PiGenerationLifecycleObserver;
       readonly assertRequestAllowed?: () => void;
       readonly onCompactionGeneration?: PiGenerationLifecycleObserver;

package/src/conversation/harness-stream.ts

@@ -22,6 +22,7 @@ export class HarnessStreamProjection {
   private readonly encoder: PiChunkEncoder;
   private terminal?: AssistantMessage;
   private readonly shown = new Map<number, string>();
+  private readonly toolInputStarted = new Set<string>();
   private readonly toolOutput = new Map<string, string>();
   constructor(options: HarnessStreamOptions) { this.encoder = new PiChunkEncoder(options); }
   restore(message: UIMessage, streaming: boolean, snapshot?: SnapshotEvent): UIMessageChunk[] {
@@ -33,9 +34,15 @@ export class HarnessStreamProjection {
     for (const tool of snapshot?.tools ?? []) if (tool.output !== undefined) this.toolOutput.set(tool.callId, tool.output);
     return this.encoder.restore(message, streaming);
   }
-  private block(block: AssistantMessage["content"][number], contentIndex: number): UIMessageChunk[] {
+  private block(block: AssistantMessage["content"][number], contentIndex: number, settled = false): UIMessageChunk[] {
     if (block.type === "toolCall" && (!block.id || !block.name)) return [];
-    if (block.type === "toolCall") return this.encoder.encode({ type: "tool_execution_start", toolCallId: block.id, toolName: block.name, args: block.arguments } as LoopEvent);
+    if (block.type === "toolCall") {
+      // The encoder keeps the first input it sees, so only a settled message may publish arguments.
+      if (settled) return this.encoder.encode({ type: "tool_execution_start", toolCallId: block.id, toolName: block.name, args: block.arguments } as LoopEvent);
+      if (this.toolInputStarted.has(block.id)) return [];
+      this.toolInputStarted.add(block.id);
+      return [{ type: "tool-input-start", toolCallId: block.id, toolName: block.name, dynamic: true }];
+    }
     if (block.type !== "text" && block.type !== "thinking") return [];
     const start = block.type === "thinking"
       ? this.encoder.encode({ type: "message_update", assistantMessageEvent: { type: "thinking_start", contentIndex } } as LoopEvent)
@@ -47,7 +54,15 @@ export class HarnessStreamProjection {
     if (!delta) return start;
     return [...start, ...this.encoder.encode({ type: "message_update", assistantMessageEvent: { type: block.type === "text" ? "text_delta" : "thinking_delta", contentIndex, delta } } as LoopEvent)];
   }
-  event(event: AgentEvent): UIMessageChunk[] {
+  /**
+   * Pi emits `run_start` only when the live run changes, so a stream bound to a continued run (after an approval or a
+   * slice release) sees tool or message frames first. The encoder's start is idempotent; lead the first frames with it.
+   */
+  private started(chunks: UIMessageChunk[]): UIMessageChunk[] {
+    return chunks.length === 0 ? chunks : [...this.encoder.start(), ...chunks];
+  }
+  event(event: AgentEvent): UIMessageChunk[] { return this.started(this.frames(event)); }
+  private frames(event: AgentEvent): UIMessageChunk[] {
     switch (event.type) {
       case "run_start": return this.encoder.start();
       case "turn_start": this.terminal = undefined; this.shown.clear(); return this.encoder.encode({ type: "turn_start" } as LoopEvent);
@@ -74,14 +89,14 @@ export class HarnessStreamProjection {
         const message = event.entry.model?.[0];
         if (message?.role !== "assistant") return [];
         this.terminal = message;
-        return [...message.content.flatMap((block, index) => this.block(block, index)), ...this.encoder.encode({ type: "message_end", message }, { terminal: false })];
+        return [...message.content.flatMap((block, index) => this.block(block, index, true)), ...this.encoder.encode({ type: "message_end", message }, { terminal: false })];
       }
       default: return [];
     }
   }
-  approvalRequested(toolCallId: string, approvalId: string): UIMessageChunk[] { return this.encoder.approvalRequested(toolCallId, approvalId); }
+  approvalRequested(toolCallId: string, approvalId: string): UIMessageChunk[] { return this.started(this.encoder.approvalRequested(toolCallId, approvalId)); }
   finish(result: SessionRunOutcome): UIMessageChunk[] {
-    return this.encoder.finish({ stopReason: result.status === "aborted" ? "aborted" : result.status === "failed" ? "error" : this.terminal?.stopReason === "length" ? "length" : "stop", timestamp: result.endedAt, ...(result.error ? { errorMessage: result.error.message } : {}) });
+    return this.started(this.encoder.finish({ stopReason: result.status === "aborted" ? "aborted" : result.status === "failed" ? "error" : this.terminal?.stopReason === "length" ? "length" : "stop", timestamp: result.endedAt, ...(result.error ? { errorMessage: result.error.message } : {}) }));
   }
 }
 
@@ -92,6 +107,7 @@ export async function bindHarnessStream(runtime: SessionHarness, options: Harnes
   watch.start((events) => delivery = (async () => { for (const event of events) await options.publish(projection.event(event)); })());
   return {
     publishApprovalRequest: (toolCallId: string, approvalId: string) => options.publish(projection.approvalRequested(toolCallId, approvalId)),
+    // The Host follows the terminal frame with the canonical transcript, which completes any frame Pi's stop dropped.
     flushTerminal: async (result: SessionRunOutcome) => { await watch.stop(); await delivery; await options.publish(projection.finish(result)); },
     unsubscribe: async () => { await watch.stop(); await delivery; },
   };

package/src/conversation/history.ts

@@ -18,6 +18,30 @@ import {
   type UIUserSidecar,
 } from "./message";
 import { openCloudflareSession, RuntimeConversation } from "../session";
+import { dropLegacyPiTables } from "../session/cloudflare/migration";
+
+/**
+ * Pi Durable 1.1 has no public API that deletes a conversation; `Tx` can only create, fork and retire documents.
+ * Clear therefore deletes every record outside the newly selected conversation from the official SQLite schema
+ * version 1. A different schema version keeps the records rather than guessing at its layout.
+ */
+function deleteConversationsExcept(sql: SqlStorage, keep: number): void {
+  const schema = sql.exec<{ version: number }>("SELECT version FROM durable_schema WHERE singleton=1").toArray()[0]?.version;
+  if (schema !== 1) {
+    console.warn("[conversation-clear:degraded]", `Unsupported Pi Durable SQLite schema ${String(schema)}; previous records kept`);
+    return;
+  }
+  const documents = `SELECT id FROM documents WHERE (scope_kind='conversation' AND owner_id<>?1)
+    OR (scope_kind='task' AND owner_id IN (SELECT id FROM tasks WHERE conversation_id<>?1))`;
+  sql.exec(`DELETE FROM document_revisions WHERE document_id IN (${documents})`, keep);
+  sql.exec(`DELETE FROM record_ids WHERE id IN (${documents}
+    UNION SELECT id FROM submissions WHERE conversation_id<>?1 UNION SELECT id FROM tasks WHERE conversation_id<>?1
+    UNION SELECT id FROM entries WHERE conversation_id<>?1 UNION SELECT id FROM conversations WHERE id<>?1)`, keep);
+  sql.exec(`DELETE FROM documents WHERE id IN (${documents})`, keep);
+  for (const [table, column] of [["submissions", "conversation_id"], ["tasks", "conversation_id"], ["entries", "conversation_id"], ["conversations", "id"]]) {
+    sql.exec(`DELETE FROM ${table} WHERE ${column}<>?`, keep);
+  }
+}
 
 /**
  * 本文件负责保存 Pi 的规范消息，并按浏览器或 Extension Host 的需要投影历史。
@@ -264,7 +288,8 @@ export class ConversationHistory {
         const custom = message.role === "custom";
         const entry = await tx.appendEntry(conversationId!, {
           kind: custom ? "springbrand.custom" : message.role === "toolResult" ? "pi.tool-result" : `pi.${message.role}`,
-          ...(custom ? {} : { model: [message] }),
+          // Custom messages reach the model as user context, as Pi's convertToLlm did before the native harness.
+          model: [custom ? { role: "user", content: [...message.content], timestamp: message.timestamp } : message],
           data: JSON.parse(JSON.stringify({ displayId: id, createdAt: message.timestamp, ...(custom ? { message } : {}), ...(options.submissionId ? { submissionId: options.submissionId } : {}), ...(message.role === "toolResult" ? { diagnostics: [] } : {}) })),
         });
         if (options.userMessage) this.durability.upsertUserSidecar(String(entry.id), JSON.stringify({ id: options.userMessage.id, ...captureUIUserSidecar(options.userMessage) }));
@@ -419,10 +444,18 @@ export class ConversationHistory {
    * 两类 Transcript 数据必须一起删除，否则复用消息 ID 时可能重新读到旧附件或 UI 元数据。
    */
   async clear(): Promise<void> {
-    await this.withSession((session) => session.commit(async (tx) => {
-      const conversation = await tx.createConversation({ ownership: { kind: "ownerless" } });
-      (await tx.doc(RuntimeConversation)).id = conversation.id;
-    }, BACKGROUND_CONTEXT));
+    await this.storage.transaction(() => this.withSession(async (session) => {
+      const next = await session.commit(async (tx) => {
+        const conversation = await tx.createConversation({ ownership: { kind: "ownerless" } });
+        (await tx.doc(RuntimeConversation)).id = conversation.id;
+        return conversation.id;
+      }, BACKGROUND_CONTEXT);
+      deleteConversationsExcept(this.storage.sql, next);
+      await dropLegacyPiTables(this.storage, session);
+      // Entry associations name records that no longer exist.
+      this.storage.sql.exec("CREATE TABLE IF NOT EXISTS pi_session_entry_submission (entry_id TEXT PRIMARY KEY, submission_id TEXT NOT NULL)");
+      this.storage.sql.exec("DELETE FROM pi_session_entry_submission");
+    }));
     this.durability.clearUserSidecars();
   }
 
@@ -563,6 +596,8 @@ export class ConversationHistory {
         entry.message.role === "custom" &&
         entry.message.customType === "turn-aborted"
       ) {
+        // The marker is this stop's terminal; the no-answer fallback would add a second one.
+        if (pendingFailedSubmissionId === entry.submissionId) pendingFailedSubmissionId = undefined;
         const submission = this.durability.findSubmissionProjection(
           entry.submissionId,
         );

package/src/harness/governance.ts

@@ -0,0 +1,206 @@
+import type { AssistantMessage, Message, ToolCall, ToolResultMessage } from "@earendil-works/pi-ai";
+import { isRetryableAssistantError } from "@earendil-works/pi-ai/utils/retry";
+import type { EntryRecord } from "@earendil-works/pi-durable";
+import type { ArtifactRef } from "../lib/artifacts";
+import {
+  isModelStreamStallMessage,
+  isOpenRouterServerToolTimeout,
+  isRecoverableAssistantError,
+} from "../models";
+
+export const MAX_TOOL_RETRIES = 3;
+export const TURN_FAILURE_CEILING = 8;
+export const DEFAULT_MAX_WRAP_UP_MODEL_TURNS = 2;
+export const TOOL_FAILURE_WRAP_UP_INSTRUCTION =
+  "This turn reached its tool failure limit. Stop calling tools now. Reply with a final message that explains what failed and the exact next step the user should take. Do not start new work.";
+const RECOVERY_MAX_FAILURES = 5;
+const STALL_MAX_FAILURES = 3;
+const SERVER_TOOL_TIMEOUT_MAX_FAILURES = 2;
+const ARTIFACT_MANIFEST_MAX_CHARS = 12 * 1024;
+/** Harness diagnostics for calls that never crossed the Tool effect boundary. */
+const UNEXECUTED_CODES = new Set(["blocked", "tool_unavailable", "invalid_arguments", "interrupted", "aborted"]);
+
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+
+export function toolCallKey(toolName: string, args: unknown): string {
+  return `${toolName}\0${canonicalJson(args)}`;
+}
+
+function resultCodes(entry: EntryRecord): string[] {
+  const diagnostics = (entry.data as { diagnostics?: { code?: unknown }[] } | undefined)?.diagnostics;
+  return Array.isArray(diagnostics)
+    ? diagnostics.flatMap((item) => typeof item?.code === "string" ? [item.code] : [])
+    : [];
+}
+
+/**
+ * Per-Submission Tool failure budget: an exact call that keeps failing is blocked, and too many failures in one
+ * Submission switch it to a text-only wrap-up. Counts are rebuilt from canonical entries after a restart.
+ */
+export class ToolGovernance {
+  private readonly failures = new Map<string, number>();
+  private total = 0;
+  wrapUp = false;
+  /** Completed model turns when the wrap-up began; the wrap-up then has a bounded number of text turns. */
+  wrapUpAt: number | undefined;
+
+  restore(entries: readonly EntryRecord[]): void {
+    this.failures.clear();
+    this.total = 0;
+    this.wrapUp = false;
+    this.wrapUpAt = undefined;
+    const calls = new Map<string, ToolCall>();
+    let turns = 0;
+    for (const entry of entries) {
+      const message = entry.model?.[0];
+      if (message?.role === "assistant") {
+        turns += 1;
+        for (const part of message.content) if (part.type === "toolCall") calls.set(part.id, part);
+        continue;
+      }
+      if (message?.role !== "toolResult") continue;
+      const call = calls.get(message.toolCallId);
+      if (!call) continue;
+      const codes = resultCodes(entry);
+      if (codes.some((code) => UNEXECUTED_CODES.has(code))) {
+        if (codes.includes("blocked") && this.exhausted(call)) this.startWrapUp(turns);
+        continue;
+      }
+      this.record(call, message.isError, turns);
+    }
+  }
+
+  exhausted(call: Pick<ToolCall, "name" | "arguments">): boolean {
+    return (this.failures.get(toolCallKey(call.name, call.arguments)) ?? 0) >= MAX_TOOL_RETRIES;
+  }
+
+  /** Returns a block reason, or undefined when the call may run. */
+  admit(call: Pick<ToolCall, "name" | "arguments">, turns: number): string | undefined {
+    if (this.wrapUp) return "This turn reached its tool failure limit. Stop calling tools now.";
+    if (!this.exhausted(call)) return undefined;
+    this.startWrapUp(turns);
+    return `This exact ${call.name} call has already failed ${MAX_TOOL_RETRIES} times — change the input or approach instead of retrying it verbatim.`;
+  }
+
+  record(call: Pick<ToolCall, "name" | "arguments">, isError: boolean, turns: number): void {
+    const key = toolCallKey(call.name, call.arguments);
+    if (!isError) {
+      this.failures.delete(key);
+      return;
+    }
+    this.failures.set(key, (this.failures.get(key) ?? 0) + 1);
+    this.total += 1;
+    if (this.total >= TURN_FAILURE_CEILING) this.startWrapUp(turns);
+  }
+
+  private startWrapUp(turns: number): void {
+    this.wrapUp = true;
+    this.wrapUpAt ??= turns;
+  }
+}
+
+/**
+ * Provider-error recovery the durable Harness cannot express by itself: per-class budgets, refusing deterministic
+ * failures, and a fresh provider Session after an OpenRouter server Tool timeout so retries leave a failing route.
+ * Pi only retries messages its own classifier accepts, so recoverable failures it does not recognize are labelled.
+ */
+export class ModelRecovery {
+  private failures = 0;
+  private stalls = 0;
+  private serverToolTimeouts = 0;
+  private allowed = true;
+
+  constructor(private readonly baseSessionId: string) {}
+
+  /** Provider Session identity for the next request. */
+  sessionId(): string {
+    return this.serverToolTimeouts === 0
+      ? this.baseSessionId
+      : `${this.baseSessionId}:server-tool-recovery:${this.serverToolTimeouts}`;
+  }
+
+  /** Whether the Harness may retry the response last passed to {@link classify}. */
+  get retryAllowed(): boolean {
+    return this.allowed;
+  }
+
+  /** Classify one terminal provider response before the Harness decides whether to retry it. */
+  classify(message: AssistantMessage): void {
+    if (message.stopReason !== "error") {
+      this.allowed = true;
+      return;
+    }
+    this.failures += 1;
+    const stalled = isModelStreamStallMessage(message.errorMessage);
+    const serverToolTimeout = isOpenRouterServerToolTimeout(message);
+    if (stalled) this.stalls += 1;
+    if (serverToolTimeout) this.serverToolTimeouts += 1;
+    const recoverable = stalled || serverToolTimeout || isRecoverableAssistantError(message);
+    this.allowed = recoverable && this.failures < RECOVERY_MAX_FAILURES &&
+      (!stalled || this.stalls < STALL_MAX_FAILURES) &&
+      (!serverToolTimeout || this.serverToolTimeouts < SERVER_TOOL_TIMEOUT_MAX_FAILURES);
+    if (this.allowed && !isRetryableAssistantError(message)) {
+      // Pi's classifier does not know our stall watchdog or OpenRouter's HTTP/2 upstream failure. Only a retried
+      // attempt carries the label; a final failure keeps the provider text.
+      message.errorMessage = `network error: ${message.errorMessage ?? "recoverable provider failure"}`;
+    }
+  }
+}
+
+export function artifactRefFromMessage(message: Message | Pick<ToolResultMessage, "role" | "details">): ArtifactRef | undefined {
+  if (message.role !== "toolResult" || message.details === null ||
+    typeof message.details !== "object" ||
+    (message.details as { kind?: unknown }).kind !== "artifact_ref") {
+    return undefined;
+  }
+  const ref = message.details as Partial<ArtifactRef>;
+  if (typeof ref.path !== "string" || typeof ref.hash !== "string" ||
+    typeof ref.bytes !== "number" || typeof ref.preview !== "string" ||
+    typeof ref.note !== "string") return undefined;
+  return {
+    kind: "artifact_ref",
+    artifactId: typeof ref.artifactId === "string" ? ref.artifactId : `artifact_${ref.hash.slice(0, 24)}`,
+    path: ref.path,
+    bytes: ref.bytes,
+    hash: ref.hash,
+    workspaceRevision: typeof ref.workspaceRevision === "string" ? ref.workspaceRevision : "unknown",
+    availability: ref.availability === "unavailable" ? "unavailable" : "available",
+    preview: ref.preview,
+    note: ref.note,
+  };
+}
+
+/** Lightweight pointers to spilled Tool output, so the model can reread evidence after compaction. */
+export function artifactManifestMessage(refs: ReadonlyMap<string, ArtifactRef>): Message | undefined {
+  if (refs.size === 0) return undefined;
+  const lines = [
+    "<workspace_artifact_manifest>",
+    "These are lightweight references to prior Tool output. Do not treat previews as complete. Read an available artifact with the Workspace readFile/readFilePage tool only when the current request needs its evidence.",
+  ];
+  let omitted = 0;
+  for (const ref of refs.values()) {
+    const preview = ref.preview.replace(/[\r\n]+/g, " ").slice(0, 160);
+    const line = [
+      `path=${ref.path}`,
+      ...(ref.availability === "unavailable" ? ["unavailable"] : []),
+      `preview=${preview}`,
+    ].join(" ");
+    if ([...lines, line, "</workspace_artifact_manifest>"].join("\n").length > ARTIFACT_MANIFEST_MAX_CHARS) {
+      omitted += 1;
+      continue;
+    }
+    lines.push(line);
+  }
+  if (omitted > 0) lines.push(`omitted=${omitted} additional artifact references due to manifest budget`);
+  lines.push("</workspace_artifact_manifest>");
+  return { role: "user", content: lines.join("\n"), timestamp: 1 };
+}

package/src/harness/index.ts

@@ -7,3 +7,4 @@ export type {
   SessionRunRequest,
 } from "./session-harness";
 export { prepareSubmissionOperation } from "./submission-operation";
+export { ModelRecovery } from "./governance";

package/src/harness/session-harness.ts

@@ -13,10 +13,19 @@ import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
 import type { Api, Message, Model, Models, ModelThinkingLevel, UserMessage } from "@earendil-works/pi-ai";
 import { RuntimeConversation } from "../session";
 import { projectToolOutputForModel } from "../context/memory/budget/gate";
+import type { ArtifactRef } from "../lib/artifacts";
+import {
+  DEFAULT_MAX_WRAP_UP_MODEL_TURNS, TOOL_FAILURE_WRAP_UP_INSTRUCTION, ModelRecovery, ToolGovernance,
+  artifactManifestMessage, artifactRefFromMessage,
+} from "./governance";
+
+const DEFAULT_WRAP_UP_INSTRUCTION = "Finish this request now without using tools. Summarize the completed work and any remaining limitation.";
 
 export interface SessionHarnessLimits {
   modelTurnsPerSlice?: number;
   maxModelTurns?: number;
+  /** Text turns allowed after the working or Tool failure budget before the Submission is stopped. */
+  maxWrapUpModelTurns?: number;
   wrapUpInstruction?: string;
 }
 export interface SessionHarnessOptions {
@@ -35,6 +44,8 @@ export interface SessionHarnessOptions {
   retry?: Partial<ConversationRetryPolicy>;
   toolExecution?: "parallel" | "sequential";
   limits?: SessionHarnessLimits;
+  /** Per-Submission provider error classification and provider Session identity. */
+  recovery?: ModelRecovery;
   beforeTool?: ToolHooks["beforeTool"];
   afterResponse?: GenerationHooks["afterResponse"];
 }
@@ -63,6 +74,11 @@ export class SessionHarness {
   private requestId?: string;
   private release!: (reason: "approval" | "interaction" | "slice") => void;
   private turnsAtOpen = 0;
+  private governance = new ToolGovernance();
+  private readonly artifactRefs = new Map<string, ArtifactRef>();
+  private wrapUpStarted = false;
+  /** Completed model turns of the current Submission. */
+  private ownedTurns = 0;
   private readonly released = new Promise<"approval" | "interaction" | "slice">((resolve) => { this.release = resolve; });
   private constructor(
     readonly harness: NativeHarness,
@@ -85,26 +101,59 @@ export class SessionHarness {
       sections: [section("system", () => options.systemPrompt, { tag: false })],
       hooks: [
         hook(GenerationTask, {
-          beforeRequest: ({ messages }) => ({ messages: messages.map((message): Message => {
-            if (message.role !== "toolResult" || exemptions.has(message.toolName)) return message;
-            const next = projectToolOutputForModel({ content: message.content, details: message.details }) as Pick<typeof message, "content" | "details">;
-            return { ...message, ...next };
-          }) }),
-          afterResponse: options.afterResponse,
+          beforeRequest: ({ messages }) => {
+            const projected = messages.map((message): Message => {
+              if (message.role !== "toolResult" || exemptions.has(message.toolName)) return message;
+              const next = projectToolOutputForModel({ content: message.content, details: message.details }) as Pick<typeof message, "content" | "details">;
+              return { ...message, ...next };
+            });
+            const manifest = artifactManifestMessage(runtime.artifactRefs);
+            const instruction = runtime.governance.wrapUp
+              ? TOOL_FAILURE_WRAP_UP_INSTRUCTION
+              : runtime.wrapUpStarted ? options.limits?.wrapUpInstruction ?? DEFAULT_WRAP_UP_INSTRUCTION : undefined;
+            return { messages: [
+              ...projected,
+              ...(manifest ? [manifest] : []),
+              ...(instruction ? [{ role: "user" as const, content: instruction, timestamp: 1 }] : []),
+            ] };
+          },
+          afterResponse: async (message, api, hookContext) => {
+            options.recovery?.classify(message);
+            await options.afterResponse?.(message, api, hookContext);
+          },
           afterTools: async (_assistant, _results, _api, hookContext) => {
             const entries = await runtime.entries(hookContext);
-            const receipt = await runtime.submission?.status(hookContext);
-            const owned = receipt?.entry ? entries.filter((entry) => entry.id >= receipt.entry!) : entries;
-            const turns = owned.filter((entry) => entry.kind === "pi.assistant").length;
+            const turns = runtime.ownedTurns = (await runtime.ownedEntries(entries, hookContext)).filter((entry) => entry.kind === "pi.assistant").length;
             const total = entries.filter((entry) => entry.kind === "pi.assistant").length;
+            const maxTurns = options.limits?.maxModelTurns ?? 300;
+            const wrapUpAt = Math.min(maxTurns, runtime.governance.wrapUpAt ?? Infinity);
+            if (turns >= wrapUpAt + (options.limits?.maxWrapUpModelTurns ?? DEFAULT_MAX_WRAP_UP_MODEL_TURNS)) {
+              // The wrap-up is still calling Tools it no longer has; end the Submission instead of looping.
+              void runtime.conversation.abort(BACKGROUND_CONTEXT).catch(() => {});
+              return;
+            }
+            if (turns >= wrapUpAt && !runtime.wrapUpStarted) {
+              runtime.wrapUpStarted = true;
+              // Tools return on the next Submission's configure; the instruction is per request, never stored.
+              await runtime.conversation.configure({ tools: [] }, hookContext);
+            }
             if (total - runtime.turnsAtOpen >= (options.limits?.modelTurnsPerSlice ?? 30)) runtime.release("slice");
-            if (turns >= (options.limits?.maxModelTurns ?? 300)) await runtime.conversation.configure({ tools: [], instructions: options.limits?.wrapUpInstruction ?? "Finish this request now without using tools. Summarize the completed work and any remaining limitation." }, hookContext);
           },
         }),
         hook(ToolTask, {
-          beforeTool: options.beforeTool,
+          beforeTool: async (call, api, hookContext) => {
+            // Calls belong to the assistant turn after the last completed Tool round.
+            const block = runtime.governance.admit(call, runtime.ownedTurns + 1);
+            if (block !== undefined) return { block };
+            return options.beforeTool?.(call, api, hookContext);
+          },
           afterTool: async (call, result) => {
-            const names = options.toolsToActivate?.(call.name, { content: [...result.content ?? []], details: result.details }, result.isError === true) ?? [];
+            runtime.governance.record(call, result.isError === true, runtime.ownedTurns + 1);
+            const ref = artifactRefFromMessage({ role: "toolResult", details: result.details });
+            if (ref) runtime.artifactRefs.set(ref.artifactId, ref);
+            const compiled = new Set(options.tools?.map((tool) => tool.name) ?? []);
+            const names = (options.toolsToActivate?.(call.name, { content: [...result.content ?? []], details: result.details }, result.isError === true) ?? [])
+              .filter((name) => compiled.has(name));
             return names.length ? { ...result, control: { ...result.control, addTools: names } } : undefined;
           },
         }),
@@ -113,7 +162,14 @@ export class SessionHarness {
     registry.install(extension);
     const harness = await Harness.open(storage, {
       models: options.models, registry,
-      settings: { stream: options.streamOptions, compaction: options.compaction, toolExecution: options.toolExecution, retry: options.retry ?? { maxRetries: 4 } },
+      settings: {
+        stream: options.streamOptions, compaction: options.compaction, toolExecution: options.toolExecution,
+        // Read for every retry decision, after afterResponse has classified that response.
+        get retry() {
+          const retry = { maxRetries: 4, ...options.retry };
+          return options.recovery ? { ...retry, enabled: (retry.enabled ?? true) && options.recovery.retryAllowed } : retry;
+        },
+      },
     }, context);
     const pointer = await harness.snapshot(RuntimeConversation, context);
     const conversation = pointer?.id ? await harness.conversation(pointer.id, context) : await harness.root(context);
@@ -127,6 +183,7 @@ export class SessionHarness {
       runtime.submission = await harness.submission(unfinished[0].id, context);
       runtime.requestId = unfinished[0].requestId;
     }
+    await runtime.restoreGovernance(context);
     return runtime;
   }
 
@@ -142,6 +199,29 @@ export class SessionHarness {
     } while (cursor);
     return entries;
   }
+  /** Entries of the active Submission, from its input onward. */
+  async ownedEntries(entries: readonly EntryRecord[], context: Context): Promise<EntryRecord[]> {
+    const receipt = await this.submission?.status(context);
+    return receipt?.entry ? entries.filter((entry) => entry.id >= receipt.entry!) : [...entries];
+  }
+  private async restoreGovernance(context: Context): Promise<void> {
+    const entries = await this.entries(context);
+    this.artifactRefs.clear();
+    for (const entry of entries) {
+      const message = entry.model?.[0];
+      const ref = message ? artifactRefFromMessage(message) : undefined;
+      if (ref) this.artifactRefs.set(ref.artifactId, ref);
+    }
+    this.governance = new ToolGovernance();
+    this.wrapUpStarted = false;
+    this.ownedTurns = 0;
+    if (!this.submission) return;
+    const owned = await this.ownedEntries(entries, context);
+    this.governance.restore(owned);
+    this.ownedTurns = owned.filter((entry) => entry.kind === "pi.assistant").length;
+    const wrapUpAt = Math.min(this.options.limits?.maxModelTurns ?? 300, this.governance.wrapUpAt ?? Infinity);
+    this.wrapUpStarted = this.ownedTurns >= wrapUpAt;
+  }
   watch(context: Context): Promise<AgentEventStream> { return watchEvents(this.harness, this.conversation.id, context); }
   requestHumanRelease(reason: "approval" | "interaction"): void { this.release(reason); }
   async fork(at: EntryId | null, context: Context): Promise<void> {
@@ -167,10 +247,13 @@ export class SessionHarness {
       const names = new Set(this.options.activeToolNames ?? this.options.tools?.map((tool) => tool.name) ?? []);
       const previous = await this.harness.snapshot(AgentDoc, this.conversation.id, context);
       if (Array.isArray(previous?.tools)) for (const name of previous.tools) if (this.options.onDemandToolNames?.includes(name)) names.add(name);
-      await this.conversation.configure({ model: { provider: this.options.model.provider, modelId: this.options.model.id }, thinkingLevel: this.options.thinkingLevel ?? "off", tools: this.options.tools?.filter((tool) => names.has(tool.name)) ?? [] }, context);
+      await this.conversation.configure({ model: { provider: this.options.model.provider, modelId: this.options.model.id }, thinkingLevel: this.options.thinkingLevel ?? "off", tools: this.options.tools?.filter((tool) => names.has(tool.name)) ?? [],
+        // Earlier runtimes stored the wrap-up instruction in the agent; it applies to one Submission only.
+        instructions: null }, context);
       this.requestId = request.operationId;
       this.submission = await this.conversation.submit({ type: "input", requestId: request.operationId, content: typeof request.prompt === "string" ? request.prompt : request.prompt.content, whenBusy: "reject" }, context);
     }
+    await this.restoreGovernance(context);
   }
   async run(request: SessionRunRequest | undefined, context: Context): Promise<SessionHarnessRunResult> {
     if (request) await this.admit(request, context);

package/src/models/index.ts

@@ -537,14 +537,15 @@ export function modelRequestUrl(model: Model<Api>): string {
  */
 export function withProviderBoundary(
   streamFn: ProviderBoundStream,
-  defaultSessionId?: string,
+  /** Host-owned provider Session; it overrides the durable Harness's per-conversation identity. */
+  hostSessionId?: string | (() => string),
   onGeneration?: PiGenerationLifecycleObserver,
 ): ProviderBoundStream {
   return (model, context, options) =>
     lazyStream(model, async () => {
       const requestId = crypto.randomUUID();
       const startedAt = Date.now();
-      const sessionId = options?.sessionId ?? defaultSessionId;
+      const sessionId = (typeof hostSessionId === "function" ? hostSessionId() : hostSessionId) ?? options?.sessionId;
       const url = modelRequestUrl(model);
       const systemPrompt = "systemPrompt" in context && typeof context.systemPrompt === "string"
         ? context.systemPrompt
@@ -910,6 +911,11 @@ function configuredModel(
             ...(endpoint.protocol === "openrouter-messages"
               ? {
                   ...anthropicMessagesCompat,
+                  // The direct Anthropic catalog enables positional system and Tool updates, but
+                  // OpenRouter Messages rejects `tool_addition` definitions. Fold them into the
+                  // leading system and top-level tools so deferred Tool decoration still applies.
+                  supportsMidConvoSystemMessages: false,
+                  supportsMidConvoToolChanges: false,
                   supportsMidConvoEffort: false,
                   supportsEagerToolInputStreaming: false,
                   supportsStrictTools:
@@ -922,6 +928,9 @@ function configuredModel(
               : endpoint.protocol === "openrouter-chat"
                 ? {
                     ...catalogCompat,
+                    // OpenRouter Chat has no verified positional system or Tool update support.
+                    supportsMidConvoSystemMessages: false,
+                    supportsMidConvoToolChanges: false,
                     thinkingFormat: "openrouter" as const,
                     maxTokensField: "max_tokens" as const,
                     supportsStore: false,

package/src/session/cloudflare/migration.ts

@@ -92,6 +92,89 @@ function normalizeLegacyAskUserEntry(value: unknown): unknown {
   return value;
 }
 
+const TERMINAL_HOST_STATUSES = new Set(["completed", "failed", "aborted", "skipped", "error"]);
+/** Legacy run phases whose state maps onto a native generation checkpoint without guessing. */
+const RESUMABLE_PHASES = new Set(["starting", "checkpoint", "assistant.ready", "assistant.effect_pending", "assistant.retry_wait"]);
+const MESSAGE_ROLES = new Set(["user", "assistant", "toolResult", "custom", "bashExecution", "branchSummary", "compactionSummary"]);
+const UNKNOWN_EFFECT = "Tool execution was interrupted and its external outcome is unknown. Do not repeat the effect without reconciling it.";
+const INTERRUPTED = "This request was interrupted by a runtime upgrade and did not finish. Send it again to continue.";
+
+type LegacyResult = { status?: string; error?: { code?: string; message?: string } };
+type ToolBatch = { assistantEntryId: string; turnId: string; calls: Array<{ status: string; sourceIndex: number; resultEntryId: string; replay?: string }> };
+
+function warn(message: string): void {
+  console.warn("[pi-session-migration]", message);
+}
+
+/** Custom messages reach the model as user context, matching `ConversationHistory.append` (e.g. turn-aborted markers). */
+function customModel(message: Message, createdAt: number): { model?: Message[] } {
+  const content = (message as unknown as { content?: unknown }).content;
+  if (typeof content === "string") return { model: [{ role: "user", content, timestamp: createdAt }] };
+  if (!Array.isArray(content) || !content.length) return {};
+  return { model: [{ role: "user", content: [...content] as Extract<Message, { role: "user" }>["content"], timestamp: createdAt }] };
+}
+
+function unknownOutcome(call: { id: string; name: string }, text = UNKNOWN_EFFECT): Message {
+  return { role: "toolResult", toolCallId: call.id, toolName: call.name, content: [{ type: "text", text }], isError: true, timestamp: Date.now() };
+}
+
+/**
+ * Normalizes historical records onto the native shapes and drops records that can never be valid model context.
+ * Dropped and branch-pointer records resolve to their nearest kept ancestor, so descendants stay on their branch.
+ */
+function repairLegacyEntries(raw: LegacyEntry[]): { entries: LegacyEntry[]; resolve: (id: string | null) => string | null } {
+  const kept = new Map<string, LegacyEntry>();
+  const alias = new Map<string, string | null>();
+  const resolve = (id: string | null): string | null => {
+    for (let seen = 0; id !== null && !kept.has(id) && alias.has(id); seen++) {
+      if (seen > alias.size) throw new Error(`Cyclic historical Pi reference: ${id}`);
+      id = alias.get(id)!;
+    }
+    return id;
+  };
+  const entries: LegacyEntry[] = [];
+  for (const source of raw) {
+    const parentId = resolve(source.parentId);
+    const skip = (reason: string) => {
+      warn(`Skipped historical entry ${source.id}: ${reason}`);
+      alias.set(source.id, parentId);
+    };
+    if (source.type === "leaf") {
+      alias.set(source.id, resolve(typeof source.targetId === "string" ? source.targetId : source.targetId === null ? null : parentId));
+      continue;
+    }
+    let entry: LegacyEntry = { ...source, parentId };
+    if (source.type === "custom_message") {
+      if (typeof source.customType !== "string") { skip("custom message has no type"); continue; }
+      entry = {
+        id: source.id, parentId, type: "message", timestamp: source.timestamp,
+        message: { role: "custom", customType: source.customType, content: source.content, details: source.details, display: source.display, timestamp: timestamp(source) } as unknown as Message,
+      };
+    }
+    if (entry.type === "message") {
+      const message = entry.message as unknown as Record<string, unknown> | undefined;
+      if (!message || typeof message !== "object" || !MESSAGE_ROLES.has(message.role as string)) { skip("unknown message"); continue; }
+      if (message.role === "assistant" && message.stopReason === "pending") { skip("unsettled assistant"); continue; }
+      if (message.role === "toolResult") {
+        let call: { name: string } | undefined;
+        let duplicate = false;
+        for (let cursor = parentId; cursor && !call && !duplicate; cursor = kept.get(cursor)?.parentId ?? null) {
+          const ancestor = kept.get(cursor)?.message;
+          if (ancestor?.role === "toolResult" && ancestor.toolCallId === message.toolCallId) duplicate = true;
+          if (ancestor?.role === "assistant") {
+            call = ancestor.content.find((part) => part.type === "toolCall" && part.id === message.toolCallId) as { name: string } | undefined;
+          }
+        }
+        if (duplicate) { skip(`duplicate Tool result ${String(message.toolCallId)}`); continue; }
+        if (!call || call.name !== message.toolName) { skip(`orphan Tool result ${String(message.toolCallId)}`); continue; }
+      }
+    }
+    kept.set(entry.id, entry);
+    entries.push(entry);
+  }
+  return { entries, resolve };
+}
+
 /** Converts records once; historical tables are retained until the upgrade is accepted. */
 export async function migratePiSession(storage: DurableObjectStorage, session: Session): Promise<void> {
   if ((await session.snapshot(Migration, BACKGROUND_CONTEXT))?.completed) return;
@@ -105,9 +188,11 @@ export async function migratePiSession(storage: DurableObjectStorage, session: S
   const rows = current || older
     ? sql.exec<{ body: string }>(`SELECT body FROM ${current ? "pi_entries" : "pi_session_entries"} ORDER BY seq`).toArray()
     : [];
-  const entries = rows.map(({ body }) => normalizeLegacyAskUserEntry(JSON.parse(body)) as LegacyEntry);
+  const raw = rows.map(({ body }) => normalizeLegacyAskUserEntry(JSON.parse(body)) as LegacyEntry);
+  if (new Set(raw.map((entry) => entry.id)).size !== raw.length) throw new Error("Historical Pi entry IDs are not unique");
+  const repaired = repairLegacyEntries(raw);
+  const entries = repaired.entries;
   const byId = new Map(entries.map((entry) => [entry.id, entry]));
-  if (byId.size !== entries.length) throw new Error("Historical Pi entry IDs are not unique");
   const values = current && hasTable(sql, "pi_values")
     ? sql.exec<{ namespace: string; key: string; body: string }>("SELECT namespace,key,body FROM pi_values").toArray()
     : [];
@@ -116,18 +201,25 @@ export async function migratePiSession(storage: DurableObjectStorage, session: S
     return row ? JSON.parse(row.body) as T : undefined;
   };
   const tipValue = values.find((row) => row.namespace === "pi.branch.tip" && row.key === "main");
-  const last = entries.at(-1);
-  let oldTip: string | null = tipValue ? JSON.parse(tipValue.body) : last?.type === "leaf" ? last.targetId as string | null : last?.id ?? null;
+  let oldTip: string | null = repaired.resolve(tipValue ? JSON.parse(tipValue.body) as string | null : raw.at(-1)?.id ?? null);
+  const hostRows = hasTable(sql, "pi_submissions")
+    ? sql.exec<{ submission_id: string; status: string }>("SELECT submission_id,status FROM pi_submissions").toArray()
+    : [];
+  const hostStatus = new Map(hostRows.map((row) => [row.submission_id, row.status]));
   const lane = read<{ currentOperationId?: string | null }>("pi.lane.state", "main");
   const operationId = lane?.currentOperationId;
-  const result = operationId ? read<{ status?: string }>("pi.result", operationId) : undefined;
-  const legacyRunning = older && hasTable(sql, "pi_submissions") ? sql.exec<{ submission_id: string }>("SELECT submission_id FROM pi_submissions WHERE status='running'").toArray() : [];
+  const legacyRunning = older ? hostRows.filter((row) => row.status === "running") : [];
   if (legacyRunning.length > 1) throw new Error("Multiple legacy operations are active in one conversation");
-  const hostStatus = operationId && hasTable(sql, "pi_submissions")
-    ? sql.exec<{ status: string }>("SELECT status FROM pi_submissions WHERE submission_id=?", operationId).toArray()[0]?.status
-    : undefined;
-  const terminal = hostStatus && ["completed", "failed", "aborted", "skipped"].includes(hostStatus);
-  const active = operationId && result === undefined && !terminal ? operationId : legacyRunning[0]?.submission_id;
+  let active: string | undefined = operationId && read<LegacyResult>("pi.result", operationId) === undefined && !TERMINAL_HOST_STATUSES.has(hostStatus.get(operationId) ?? "")
+    ? operationId
+    : legacyRunning[0]?.submission_id;
+  // Navigation and standalone compaction never committed their target. The Host re-admits the owning
+  // Submission from its queued input, so the native runtime performs the whole step itself.
+  const intent = active ? read<{ intent?: { kind?: string } }>("pi.op.meta", active)?.intent?.kind ?? (active.endsWith(":regenerate") ? "navigation" : "run") : undefined;
+  if (active && intent !== "run") {
+    warn(`Dropped unfinished legacy ${intent} operation ${active}`);
+    active = undefined;
+  }
   const links = hasTable(sql, "pi_session_entry_submission")
     ? sql.exec<{ entry_id: string; submission_id: string }>("SELECT entry_id,submission_id FROM pi_session_entry_submission").toArray()
     : hasTable(sql, "pi_session_message_submission") ? sql.exec<{ entry_id: string; submission_id: string }>("SELECT message_id AS entry_id,submission_id FROM pi_session_message_submission").toArray() : [];
@@ -156,6 +248,10 @@ export async function migratePiSession(storage: DurableObjectStorage, session: S
       }
     }
   }
+  const commitResult = (id: string, outcome: Message) => {
+    const entry: LegacyEntry = { id, parentId: oldTip, type: "message", message: outcome, timestamp: outcome.timestamp };
+    entries.push(entry); byId.set(entry.id, entry); owners.set(entry.id, active!); oldTip = entry.id;
+  };
   if (older && active && hasTable(sql, "pi_recovery_milestones")) {
     const milestones = sql.exec<{ body: string }>("SELECT body FROM pi_recovery_milestones WHERE submission_id=? ORDER BY seq", active).toArray();
     const recovered = replayPiToolRecovery(milestones.map((row) => row.body));
@@ -163,36 +259,68 @@ export async function migratePiSession(storage: DurableObjectStorage, session: S
     for (const call of Object.values(recovered.toolCalls)) {
       if (existing.has(call.toolCallId)) continue;
       const pending = Object.values(recovered.approvals).some((row) => row.toolCallId === call.toolCallId && row.status === "pending") || Object.values(recovered.interactions).some((row) => row.toolCallId === call.toolCallId && row.status === "pending");
-      const outcome = call.result ?? (!pending && call.retry === "non-idempotent" ? { role: "toolResult" as const, toolCallId: call.toolCallId, toolName: call.toolName, content: [{ type: "text" as const, text: "Interrupted legacy effect; its outcome is unknown. Reconcile it before repeating it." }], isError: true, timestamp: Date.now() } : undefined);
-      if (!outcome) continue;
-      const entry: LegacyEntry = { id: `legacy-result:${active}:${call.toolCallId}`, parentId: oldTip, type: "message", message: outcome, timestamp: outcome.timestamp };
-      entries.push(entry); byId.set(entry.id, entry); owners.set(entry.id, active); oldTip = entry.id;
+      const outcome = call.result ?? (!pending && call.retry === "non-idempotent" ? unknownOutcome({ id: call.toolCallId, name: call.toolName }, "Interrupted legacy effect; its outcome is unknown. Reconcile it before repeating it.") : undefined);
+      if (outcome) commitResult(`legacy-result:${active}:${call.toolCallId}`, outcome);
     }
   }
-  const operation = active ? read<{ at: string; batch?: { assistantEntryId: string; turnId: string; calls: Array<{ status: string; sourceIndex: number; resultEntryId: string; replay?: string }> } }>("pi.op.state", active) : undefined;
+  // An operation that cannot be resumed is settled as interrupted. It never replays an uncertain effect.
+  let interrupted: string | undefined;
+  const operation = active ? read<{ at: string; batch?: ToolBatch }>("pi.op.state", active) : undefined;
   if (active && operation?.at === "tools") {
-    const assistant = byId.get(operation.batch!.assistantEntryId)?.message;
-    if (assistant?.role !== "assistant") throw new Error("Historical Tool batch has no canonical assistant");
-    for (const call of operation.batch!.calls) {
-      const tool = assistant.content[call.sourceIndex];
-      if (tool?.type !== "toolCall") throw new Error("Historical Tool batch index is invalid");
+    const message = operation.batch ? byId.get(operation.batch.assistantEntryId)?.message : undefined;
+    const assistant = message?.role === "assistant" ? message : undefined;
+    if (!assistant) interrupted = "Historical Tool batch has no canonical assistant";
+    for (const call of assistant ? operation.batch!.calls : []) {
+      const part = assistant!.content[call.sourceIndex];
+      if (typeof part !== "object" || part?.type !== "toolCall") { interrupted = "Historical Tool batch index is invalid"; continue; }
+      const tool = part;
       if (call.status === "completed") continue;
-      const staged = read<{ type?: string; payload?: Message }>("pi.pending.entry", call.resultEntryId);
-      let outcome = staged?.payload;
-      if (call.status === "outcome_ready" && outcome?.role !== "toolResult") throw new Error("Historical Tool outcome is missing");
-      if (call.status === "effect_pending" && call.replay !== "safe") {
-        outcome = { role: "toolResult", toolCallId: tool.id, toolName: tool.name, content: [{ type: "text", text: "Tool execution was interrupted and its external outcome is unknown. Do not repeat the effect without reconciling it." }], isError: true, timestamp: Date.now() };
+      let outcome = read<{ type?: string; payload?: Message }>("pi.pending.entry", call.resultEntryId)?.payload;
+      if (outcome && (outcome.role !== "toolResult" || outcome.toolCallId !== tool.id || outcome.toolName !== tool.name)) {
+        warn(`Historical Tool outcome ${call.resultEntryId} conflicts with its call`);
+        outcome = unknownOutcome(tool);
       }
-      if (outcome) {
-        if (outcome.role !== "toolResult" || outcome.toolCallId !== tool.id || outcome.toolName !== tool.name) throw new Error("Historical Tool outcome conflicts with its call");
-        const entry: LegacyEntry = { id: call.resultEntryId, parentId: oldTip, type: "message", message: outcome, timestamp: outcome.timestamp };
-        entries.push(entry); byId.set(entry.id, entry); owners.set(entry.id, active); oldTip = entry.id;
+      if (call.status === "outcome_ready" && outcome?.role !== "toolResult") {
+        warn(`Historical Tool outcome ${call.resultEntryId} is missing`);
+        outcome = unknownOutcome(tool);
       }
+      if (call.status === "effect_pending" && call.replay !== "safe") outcome = unknownOutcome(tool);
+      if (outcome) commitResult(call.resultEntryId, outcome);
+    }
+  } else if (active && operation && !RESUMABLE_PHASES.has(operation.at)) {
+    interrupted = `Historical operation ${operation.at} cannot resume natively`;
+  }
+  const branch = (tip: string | null): LegacyEntry[] => {
+    const chain: LegacyEntry[] = [];
+    for (let id = tip; id; id = byId.get(id)?.parentId ?? null) {
+      const entry = byId.get(id);
+      if (!entry) throw new Error("Historical branch is invalid");
+      chain.unshift(entry);
     }
-  } else if (active && operation && !["starting", "checkpoint", "assistant.ready", "assistant.effect_pending", "assistant.retry_wait"].includes(operation.at)) {
-    throw new Error(`Historical operation ${operation.at} needs an explicit migration before it can run`);
+    return chain;
+  };
+  let owned = active ? branch(oldTip).filter((entry) => owners.get(entry.id) === active) : [];
+  let prompt = owned.find((entry) => entry.message?.role === "user");
+  if (active && !prompt) interrupted ??= "Active historical operation has no canonical user input";
+  if (active && interrupted) {
+    warn(`Settled legacy operation ${active} as interrupted: ${interrupted}`);
+    const assistant = [...owned].reverse().find((entry) => entry.message?.role === "assistant")?.message;
+    const settled = new Set(owned.flatMap((entry) => entry.message?.role === "toolResult" ? [entry.message.toolCallId] : []));
+    for (const part of assistant?.role === "assistant" ? assistant.content : []) {
+      if (part.type === "toolCall" && !settled.has(part.id)) commitResult(`legacy-interrupted:${active}:${part.id}`, unknownOutcome(part));
+    }
+    owned = branch(oldTip).filter((entry) => owners.get(entry.id) === active);
+    prompt = owned.find((entry) => entry.message?.role === "user");
   }
+  // Pi finished these operations before the Host recorded their terminal; settle them instead of rerunning input.
+  const finished = hostRows.flatMap((row) => {
+    if (row.submission_id === active || !["pending", "running"].includes(row.status)) return [];
+    const result = read<LegacyResult>("pi.result", row.submission_id);
+    return result ? [{ id: row.submission_id, result }] : [];
+  });
   const converted = new Map<string, EntryRecord>();
+  // Where a child continues; a compaction's retained context belongs to every branch through it.
+  const anchors = new Map<string, EntryRecord>();
   const conversationByEntry = new Map<string, ConversationId>();
   const tips = new Map<ConversationId, string>();
   const copiedUi: Array<{ id: string; body: string }> = [];
@@ -206,7 +334,7 @@ export async function migratePiSession(storage: DurableObjectStorage, session: S
         if (!entry.id || (entry.parentId !== null && !byId.has(entry.parentId))) {
           throw new Error(`Historical Pi entry has a missing parent: ${entry.id}`);
         }
-        const parent = entry.parentId ? converted.get(entry.parentId) : undefined;
+        const parent = entry.parentId ? anchors.get(entry.parentId) : undefined;
         if (entry.parentId && !parent) throw new Error(`Historical Pi entry is out of order: ${entry.id}`);
         let conversationId = parent ? conversationByEntry.get(entry.parentId!)! : initial.id;
         if (parent && tips.get(conversationId) !== entry.parentId) {
@@ -214,15 +342,16 @@ export async function migratePiSession(storage: DurableObjectStorage, session: S
         }
         const message = entry.message;
         let record: EntryRecord;
+        let anchor: EntryRecord;
         if (entry.type === "message" && message) {
           const role = (message as { role: string }).role;
-          record = await tx.appendEntry(conversationId, {
+          record = anchor = await tx.appendEntry(conversationId, {
             kind: role === "toolResult" ? "pi.tool-result" : role === "custom" ? "springbrand.custom" : `pi.${role}`,
-            ...(role === "custom" ? {} : { model: [message] }),
-            data: { displayId: entry.id, createdAt: timestamp(entry), ...(role === "custom" ? { message: message as unknown as Record<string, never> } : {}), ...(role === "toolResult" ? { diagnostics: [] } : {}) },
+            ...(role === "custom" ? customModel(message, timestamp(entry)) : { model: [message] }),
+            data: JSON.parse(JSON.stringify({ displayId: entry.id, createdAt: timestamp(entry), ...(role === "custom" ? { message } : {}), ...(role === "toolResult" ? { diagnostics: [] } : {}) })),
           });
         } else if (entry.type === "compaction" || entry.type === "branch_summary") {
-          record = await tx.appendEntry(conversationId, {
+          record = anchor = await tx.appendEntry(conversationId, {
             kind: "pi.compaction", model: [{ role: "user", content: `<summary>\n${entry.summary ?? ""}\n</summary>`, timestamp: timestamp(entry) }],
             head: "self", data: { reason: "manual", displayId: entry.id, createdAt: timestamp(entry) },
           });
@@ -241,12 +370,13 @@ export async function migratePiSession(storage: DurableObjectStorage, session: S
             retainedTail = tail;
           }
           for (const retained of retainedTail ?? []) {
-            await tx.appendEntry(conversationId, { kind: "springbrand.retained-context", model: [retained] });
+            anchor = await tx.appendEntry(conversationId, { kind: "springbrand.retained-context", model: [retained] });
           }
         } else {
-          record = await tx.appendEntry(conversationId, { kind: "springbrand.history", data: { displayId: entry.id, createdAt: timestamp(entry), record: entry as unknown as Record<string, never> } });
+          record = anchor = await tx.appendEntry(conversationId, { kind: "springbrand.history", data: { displayId: entry.id, createdAt: timestamp(entry), record: entry as unknown as Record<string, never> } });
         }
         converted.set(entry.id, record);
+        anchors.set(entry.id, anchor);
         conversationByEntry.set(entry.id, conversationId);
         tips.set(conversationId, entry.id);
         if (entry.id === oldTip) selected = conversationId;
@@ -257,7 +387,7 @@ export async function migratePiSession(storage: DurableObjectStorage, session: S
     if (oldTip === null && entries.length) {
       selected = (await session.commit((tx) => tx.createConversation({ ownership: { kind: "ownerless" } }), BACKGROUND_CONTEXT)).id;
     } else if (oldTip && tips.get(selected) !== oldTip) {
-      const tip = converted.get(oldTip);
+      const tip = anchors.get(oldTip);
       if (!tip) throw new Error("Historical branch tip is missing");
       selected = (await session.commit((tx) => tx.forkConversation(tip.conversationId, tip.id, { ownership: { kind: "ownerless" } }), BACKGROUND_CONTEXT)).id;
     }
@@ -271,16 +401,29 @@ export async function migratePiSession(storage: DurableObjectStorage, session: S
         if (typeof config.thinkingLevel === "string") agent.thinkingLevel = config.thinkingLevel as typeof agent.thinkingLevel;
         if (Array.isArray(config.activeToolNames)) agent.tools = config.activeToolNames as string[];
       }
-      if (active) {
-        const chain: LegacyEntry[] = [];
-        for (let id = oldTip; id; id = byId.get(id)?.parentId ?? null) {
-          const entry = byId.get(id);
-          if (!entry) throw new Error("Active historical operation has an invalid branch");
-          chain.unshift(entry);
+      const selectedBranch = branch(oldTip);
+      for (const { id, result } of finished) {
+        const ownedBySubmission = selectedBranch.filter((entry) => owners.get(entry.id) === id);
+        const input = ownedBySubmission.find((entry) => entry.message?.role === "user");
+        const reply = [...ownedBySubmission].reverse().find((entry) => entry.message?.role === "assistant");
+        const entry = input ? converted.get(input.id)!.id : undefined;
+        if ((result.status === "completed" || result.status === "declined") && entry !== undefined && reply) {
+          await tx.createSubmission({ conversationId: selected, requestId: id, type: "input", status: "done", entry, answer: converted.get(reply.id)!.id });
+        } else {
+          await tx.createSubmission({
+            conversationId: selected, requestId: id, type: "input", status: "unanswered",
+            reason: result.status === "aborted" ? "aborted" : result.status ?? "failed",
+            detail: result.error?.message ?? (result.status === "aborted" ? "Cancelled" : "The legacy request ended without an answer."),
+            ...(entry !== undefined ? { entry } : {}),
+          });
         }
-        const owned = chain.filter((entry) => owners.get(entry.id) === active);
-        const prompt = owned.find((entry) => entry.message?.role === "user");
-        if (!prompt) throw new Error("Active historical operation has no canonical user input");
+      }
+      if (active && interrupted) {
+        await tx.createSubmission({
+          conversationId: selected, requestId: active, type: "input", status: "unanswered", reason: "interrupted", detail: INTERRUPTED,
+          ...(prompt ? { entry: converted.get(prompt.id)!.id } : {}),
+        });
+      } else if (active && prompt) {
         const promptEntry = converted.get(prompt.id)!;
         const submission = await tx.createSubmission({ conversationId: selected, requestId: active, type: "input", status: "placed", entry: promptEntry.id });
         const assistant = [...owned].reverse().find((entry) => entry.message?.role === "assistant");
@@ -302,13 +445,46 @@ export async function migratePiSession(storage: DurableObjectStorage, session: S
     sql.exec("CREATE TABLE IF NOT EXISTS pi_session_entry_submission (entry_id TEXT PRIMARY KEY, submission_id TEXT NOT NULL)");
     for (const link of copiedLinks) sql.exec("INSERT OR IGNORE INTO pi_session_entry_submission VALUES (?,?)", link.id, link.submissionId);
     for (const sidecar of copiedUi) sql.exec("INSERT OR IGNORE INTO pi_message_ui VALUES (?,?)", sidecar.id, sidecar.body);
+    if (hasTable(sql, "pi_pending_steers")) {
+      // Old Pi committed these Steers but the Host receipt survived; a native requeue would duplicate them.
+      const steers = sql.exec<{ message_id: string; harness_entry_id: string | null; ui_message_json: string | null }>("SELECT message_id,harness_entry_id,ui_message_json FROM pi_pending_steers").toArray();
+      for (const steer of steers) {
+        const record = converted.get(steer.harness_entry_id ?? "") ?? converted.get(steer.message_id);
+        if (!record) continue;
+        if (steer.ui_message_json) {
+          sql.exec("CREATE TABLE IF NOT EXISTS pi_message_ui (message_id TEXT PRIMARY KEY, body TEXT NOT NULL)");
+          sql.exec("INSERT OR IGNORE INTO pi_message_ui VALUES (?,?)", String(record.id), steer.ui_message_json);
+        }
+        sql.exec("DELETE FROM pi_pending_steers WHERE message_id=?", steer.message_id);
+      }
+    }
     for (const table of ["pi_approvals", "pi_tool_interactions"]) {
       if (!hasTable(sql, table)) continue;
       const rows = sql.exec<{ rowid: number; input_json: string }>(`SELECT rowid,input_json FROM ${table} WHERE tool_name='ask_user'`).toArray();
       for (const row of rows) sql.exec(`UPDATE ${table} SET input_json=? WHERE rowid=?`, JSON.stringify(normalizeLegacyAskUserInput(JSON.parse(row.input_json))), row.rowid);
+      // An interrupted operation can no longer continue its parked call, so its decision must not park Host recovery.
+      if (active && interrupted && hasColumns(sql, table, ["submission_id", "status"])) {
+        sql.exec(`UPDATE ${table} SET status=? WHERE submission_id=? AND status='pending'`, table === "pi_approvals" ? "rejected" : "cancelled", active);
+      }
     }
     if (hasTable(sql, "cf_agents_schedules")) {
       for (const callback of ["_cleanupStreamBuffers", "_piPlannedContinuation", "_piContinuationWatchdog", "_piApprovalContinuation", "_chatRecoveryRetry"]) sql.exec("DELETE FROM cf_agents_schedules WHERE callback=?", callback);
     }
   });
 }
+
+function hasColumns(sql: SqlStorage, table: string, names: string[]): boolean {
+  const columns = new Set(sql.exec<{ name: string }>(`PRAGMA table_info(${table})`).toArray().map((row) => row.name));
+  return names.every((name) => columns.has(name));
+}
+
+const LEGACY_TABLES = [
+  "pi_entries", "pi_values", "pi_lists", "pi_usage", "pi_storage_state", "pi_session_entries", "pi_session_metadata",
+  "pi_legacy_entries_backup", "pi_recovery_milestones", "pi_session_message_submission", "pi_tool_settlements",
+];
+
+/** Drops the inert pre-upgrade baseline once the migrated history it backs up is deleted. */
+export async function dropLegacyPiTables(storage: DurableObjectStorage, session: Session): Promise<void> {
+  if (!(await session.snapshot(Migration, BACKGROUND_CONTEXT))?.completed) throw new Error("Legacy Pi tables are still the migration source");
+  for (const table of LEGACY_TABLES) storage.sql.exec(`DROP TABLE IF EXISTS ${table}`);
+}

package/src/submission/finalization.ts

@@ -13,12 +13,14 @@ import type { SteerRepository } from "./steer-repository";
 
 /** Commits the Submission outcome and human/Host facts after accepted steering is preserved. */
 export class SubmissionFinalizer {
+  /** User-stop markers appended after their terminal commit; `finish()` awaits its own. */
+  private readonly stopMarkers = new Map<string, Promise<unknown>>();
   constructor(private readonly options: {
     submissions: SubmissionRepository;
     steers: SteerRepository;
     messageUi: MessageUiRepository;
     transaction<T>(run: () => T): T;
-    conversation: Pick<ConversationHistory, "append" | "storedMessages">;
+    conversation: Pick<ConversationHistory, "append" | "appendTurnAbortedMarker" | "storedMessages">;
     decisions: Pick<HarnessHumanDecisions, "cancelForSubmission">;
     events: Pick<RuntimeTurnEvents, "submissionTerminal">;
     telemetry: Pick<RuntimeTelemetryCoordinator, "capture">;
@@ -53,7 +55,13 @@ export class SubmissionFinalizer {
     const output = (await this.options.conversation.storedMessages())
       .filter((entry) => entry.submissionId === submissionId && entry.message.role === "assistant")
       .at(-1)?.message;
-    return this.commit(submissionId, outcome, message, output?.role === "assistant" ? output : undefined);
+    const completed = this.commit(submissionId, outcome, message, output?.role === "assistant" ? output : undefined);
+    const marker = this.stopMarkers.get(submissionId);
+    if (marker) {
+      this.stopMarkers.delete(submissionId);
+      await marker;
+    }
+    return completed;
   }
 
   /** Shares atomic terminal facts with an admitted handoff cancelled before execution. */
@@ -63,7 +71,8 @@ export class SubmissionFinalizer {
     message?: string,
     output?: AssistantMessage,
   ): StoredSubmission {
-    return this.options.transaction(() => {
+    let stoppedByUser = false;
+    const completed = this.options.transaction(() => {
       // Host admission and history reads can await while an explicit stop wins.
       const latest = this.read(submissionId);
       if (isTerminalSubmissionStatus(latest.status)) return latest;
@@ -79,6 +88,10 @@ export class SubmissionFinalizer {
       const status = effectiveOutcome === "succeeded" ? "completed" : effectiveOutcome === "aborted" ? "aborted" : "error";
       this.options.submissions.updateTerminal(submissionId, status, reason, Date.now());
       const completed = this.read(submissionId);
+      stoppedByUser = effectiveOutcome === "aborted" && reason === USER_STOP_REASON;
+      if (stoppedByUser && completed.completedAt === null) {
+        throw new Error(`Aborted SpringBrand submission has no completion time: ${submissionId}`);
+      }
       this.options.events.submissionTerminal(completed);
       this.options.telemetry.capture("turnFinished", {
         submissionId,
@@ -90,6 +103,20 @@ export class SubmissionFinalizer {
       });
       return completed;
     });
+    if (stoppedByUser) this.appendStopMarker(submissionId, completed.completedAt!);
+    return completed;
+  }
+
+  /**
+   * The browser projects `interruptedByUser` from this marker and the next model request sees it as user context.
+   * Pi history writes are async, so the marker follows the synchronous terminal commit.
+   */
+  private appendStopMarker(submissionId: string, completedAt: number): void {
+    const marker = this.options.conversation.appendTurnAbortedMarker(submissionId, completedAt).catch((error: unknown) => {
+      console.warn("[runtime-stop-marker:failed]", submissionId, error instanceof Error ? error.message : String(error));
+    });
+    this.stopMarkers.set(submissionId, marker);
+    this.options.waitUntil(marker);
   }
 
   private read(submissionId: string): StoredSubmission {

package/src/tools/runtime/compiler.ts

@@ -168,8 +168,15 @@ export function compileHarnessTools(
       ...(candidate.deferLoading ? { deferLoading: true as const } : {}),
       async execute(args, api, context) {
         const toolCallId = api.callId;
+        // AgentTool progress is a replacing snapshot (web_search sends its accumulated text), but Pi output only
+        // appends and has no replace operation: append a grown snapshot's suffix, and start a new line otherwise.
+        let shown = "";
         const onUpdate = (update: AgentToolResult<unknown>) => {
-          for (const part of update.content) if (part.type === "text") api.output(part.text);
+          const text = update.content.flatMap((part) => part.type === "text" ? [part.text] : []).join("");
+          if (text && text !== shown) {
+            api.output(text.startsWith(shown) ? text.slice(shown.length) : shown ? `\n${text}` : text);
+            shown = text;
+          }
           if (update.details !== undefined) void api.details(update.details, context).catch(() => {});
         };
         const signal = context.abortSignal ?? new AbortController().signal;