@springbrand/agent-runtime 0.2.0-alpha.72 → 0.3.0-alpha.1

package/src/{kernel/submission-lifecycle.ts → submission/lifecycle.ts}

@@ -2,7 +2,7 @@ import { TurnQueue } from "agents/chat";
 import {
   isTerminalSubmissionStatus,
   type SubmissionStatus,
-} from "../db/submission.repo";
+} from "./repository";
 
 /**
  * 本文件统一管理一次提交从接收到结束的过程。
@@ -130,10 +130,9 @@ export type SubmissionOutcome = "succeeded" | "failed" | "aborted";
  * @remarks
  * `SubmissionLifecycle` 把它交给 `execute`，Runtime 据此选择执行前置动作。
  *
- * `recovery` 和 `continuation` 必须分开：前者的内存状态已经丢了、transcript 可能停在半路，
- * 要走完整的里程碑重放；后者是本轮主动让出执行片，transcript 完好、什么都不用重建。
- * 合成一个布尔量意味着最常跑的那条路径每次都去趟最脆弱的恢复代码，
- * 而且重放成本会随让步次数增长。
+ * `recovery` 和 `continuation` 必须分开：前者的进程内配置已经丢失，需重新装配原 runtime key 再打开 Session；
+ * 后者是本轮主动让出执行片，持久 operation 和已固定配置保持完好。
+ * 区分两者可避免主动让出时重复加载原 runtime key。
  */
 export type SubmissionExecutionMode =
   /** 首次执行一条新接收的提交。 */
@@ -156,6 +155,8 @@ export interface SubmissionInput<
 > {
   requestId: string;
   idempotencyKey?: string;
+  /** Only a repository-validated accepted Steer may transfer despite a full new-work queue. */
+  isSteerHandoff?: true;
   /**
    * 准备接收所需数据，并返回同步创建记录的函数。
    *
@@ -202,10 +203,6 @@ interface SubmissionLifecycleOptions<
     submissionId: string,
     mode: SubmissionExecutionMode,
   ): Promise<TSubmission>;
-  // 作用：记录可恢复的取消意图。
-  // 调用：`cancel` 在同一存储事务内与取消原因一起写入。
-  // 原因：持久化里程碑可以让恢复路径看到已经发生的取消。
-  appendAbortIntent(submission: TSubmission, reason: string): void;
   // 作用：把一条非终态提交写成最终结果。
   // 调用：`finish` 在重读并确认仍非终态后调用。
   // 原因：状态映射和其他终态副作用必须由 Runtime 在一个边界完成。
@@ -217,7 +214,9 @@ interface SubmissionLifecycleOptions<
   // 作用：通知当前执行器中断运行。
   // 调用：`cancel` 命中活动执行器，或 `activate` 发现早到取消时调用。
   // 原因：生命周期不依赖具体执行器类型，只通过这个回调中断。
-  abortActive(active: TActive): void;
+  abortActive(active: TActive): void | Promise<void>;
+  /** Close a persisted operation after its process-local executor has parked. */
+  abortDormant(submission: TSubmission): void | Promise<void>;
   /**
    * 中断活动执行器，但让这条提交留给持久续跑接手。
    *
@@ -244,6 +243,7 @@ export class SubmissionLifecycle<
   private readonly queue = new TurnQueue();
   private readonly executions = new Map<string, Promise<TSubmission>>();
   private readonly activeBySubmission = new Map<string, TActive>();
+  private readonly terminalCommits = new Map<string, Promise<TSubmission>>();
 
   // #region 提交与恢复
 
@@ -322,10 +322,10 @@ export class SubmissionLifecycle<
    * 等当前执行片退出后，接着跑同一条非终态 Submission。
    *
    * @remarks
-   * `_piPlannedContinuation` 在计划让步的唤醒里调用。先 await 当前执行片，
+   * `_piHarnessContinuation` 在计划让步或 Provider 等待的唤醒里调用。先 await 当前执行片，
    * 是为了避开 `executions` 的实例内去重 —— 否则这次唤醒会被合流到正在退场的那一片上。
    *
-   * 走 `continuation` 而不是 `recovery`：这一轮什么都没丢，不需要重放里程碑。
+   * 走 `continuation` 而不是 `recovery`：这一轮什么都没丢，只需重新 drive 同一个持久 operation。
    */
   async continueAfterCurrent(submissionId: string): Promise<TSubmission> {
     const current = this.executions.get(submissionId);
@@ -382,16 +382,15 @@ export class SubmissionLifecycle<
           rejected: false,
         };
       }
-      if (
-        this.options.store.countPending() >=
-        MAX_PENDING_SUBMISSIONS
+      if (!input.isSteerHandoff &&
+        this.options.store.countPending() >= MAX_PENDING_SUBMISSIONS
       ) {
         throw new SubmissionQueueFullError();
       }
       const submission = create();
       return {
         submission,
-        admitted: submission.admissionRejected !== true,
+        admitted: !isTerminalSubmissionStatus(submission.status),
         rejected: submission.admissionRejected === true,
       };
     });
@@ -520,17 +519,27 @@ export class SubmissionLifecycle<
    *
    * 写入前重读最新记录并保留已有终态，避免较晚到达的结果覆盖先完成的结果。
    */
-  async finish(
+  finish(
     submission: TSubmission,
     outcome: SubmissionOutcome,
     message?: string,
   ): Promise<TSubmission> {
+    const existing = this.terminalCommits.get(submission.submissionId);
+    if (existing) return existing;
     const latest = this.options.store.find(submission.submissionId);
     if (!latest) {
-      throw new Error(`Unknown SpringBrand submission: ${submission.submissionId}`);
+      return Promise.reject(
+        new Error(`Unknown SpringBrand submission: ${submission.submissionId}`),
+      );
     }
-    if (isTerminalSubmissionStatus(latest.status)) return latest;
-    return this.options.commitTerminal(latest, outcome, message);
+    if (isTerminalSubmissionStatus(latest.status)) return Promise.resolve(latest);
+    const commit = this.options.commitTerminal(latest, outcome, message);
+    this.terminalCommits.set(submission.submissionId, commit);
+    void commit.then(
+      () => this.terminalCommits.delete(submission.submissionId),
+      () => this.terminalCommits.delete(submission.submissionId),
+    );
+    return commit;
   }
 
   /**
@@ -648,14 +657,16 @@ export class SubmissionLifecycle<
     if (!submission || isTerminalSubmissionStatus(submission.status)) {
       return { ok: false };
     }
-    this.options.store.transaction(() => {
-      this.options.store.updateAbortReason(submissionId, reason);
-      this.options.appendAbortIntent(submission, reason);
-    });
+    this.options.store.transaction(() =>
+      this.options.store.updateAbortReason(submissionId, reason)
+    );
     const active = this.activeBySubmission.get(submissionId);
-    if (active) this.options.abortActive(active);
+    if (active) await this.options.abortActive(active);
+    else if (submission.status === "running") {
+      await this.options.abortDormant(submission);
+    }
     await this.finish(submission, "aborted", reason);
-    if (!active) this.pump();
+    this.pump();
     return { ok: true };
   }
 
@@ -699,12 +710,14 @@ export class SubmissionLifecycle<
     this.options.store.transaction(() => {
       for (const submission of submissions) {
         this.options.store.updateAbortReason(submission.submissionId, reason);
-        this.options.appendAbortIntent(submission, reason);
       }
     });
     for (const submission of submissions) {
       const active = this.activeBySubmission.get(submission.submissionId);
-      if (active) this.options.abortActive(active);
+      if (active) await this.options.abortActive(active);
+      else if (submission.status === "running") {
+        await this.options.abortDormant(submission);
+      }
       await this.finish(submission, "aborted", reason);
     }
     this.pump();

package/src/{db/submission.repo.ts → submission/repository.ts}

@@ -1,4 +1,5 @@
 import type { SqlTaggedTemplate } from "agents/chat";
+import type { LaneSnapshot } from "@earendil-works/pi-agent-core";
 
 // Submission 的统一定义见 ./index.ts。
 // #region 状态与行类型
@@ -9,11 +10,6 @@ export type SubmissionStatus =
   | "aborted"
   | "skipped"
   | "error";
-export type SubmissionRecoveryReason =
-  | "no_meaningful_model_progress"
-  | "server_tool_timeout"
-  | "transient_model_error"
-  | "context_overflow";
 
 const TERMINAL_SUBMISSION_STATUSES: ReadonlySet<SubmissionStatus> = new Set([
   "completed",
@@ -23,7 +19,7 @@ const TERMINAL_SUBMISSION_STATUSES: ReadonlySet<SubmissionStatus> = new Set([
 ]);
 
 // 判断 Submission 是否已经结束。
-// Runtime、SubmissionLifecycle 和 ApprovalLifecycle 在决定是否继续执行、等待或接受审批时调用。
+// Runtime、SubmissionLifecycle 和 HarnessDecisionGate 在决定是否继续执行、等待或接受审批时调用。
 // 终态集合收口在一处防止各生命周期的判断漂移；增加状态时必须先确认它是否真的不可再继续。
 export function isTerminalSubmissionStatus(
   status: SubmissionStatus,
@@ -42,20 +38,21 @@ export interface StoredSubmission {
   completedAt: number | null;
   assemblyRevision: string;
   assemblyDescriptor: string;
+  runtimeKey: string;
   assistantMessageId: string;
   abortReason: string | null;
   queuedInputJson: string | null;
   queuedUiMessageJson: string | null;
   userMessageId: string | null;
   regenerateMessageId: string | null;
-  recoveryErrorCount: number;
-  recoveryReason: SubmissionRecoveryReason | null;
   runId: string | null;
   retryable?: boolean;
-  /** 跨执行片累计的模型回合数，全局回合预算的唯一事实来源。 */
-  modelTurns: number;
-  /** 当前让步执行片的标识；没有未完成让步时为 null。 */
-  continuationId: string | null;
+}
+
+/** Reuse durable stop intent when transferring work out of the source Submission. */
+export function submissionAbortReason(submission: StoredSubmission | null): string | undefined {
+  return submission?.abortReason ||
+    (submission?.status === "aborted" ? submission.error || "Cancelled" : undefined);
 }
 
 export interface NewSubmission {
@@ -65,6 +62,7 @@ export interface NewSubmission {
   createdAt: number;
   assemblyRevision: string;
   assemblyDescriptor: string;
+  runtimeKey?: string;
   assistantMessageId: string;
   queuedInputJson?: string | null;
   queuedUiMessageJson?: string | null;
@@ -84,18 +82,15 @@ type SubmissionRow = {
   completed_at: number | null;
   assembly_revision: string;
   assembly_descriptor: string;
+  runtime_key: string;
   assistant_message_id: string;
   abort_reason: string | null;
   queued_input_json: string | null;
   queued_ui_message_json: string | null;
   user_message_id: string | null;
   regenerate_message_id: string | null;
-  recovery_error_count: number;
-  recovery_reason: string | null;
   run_id: string | null;
   admission_retryable: number | null;
-  model_turns: number;
-  continuation_id: string | null;
 };
 
 // #endregion
@@ -115,20 +110,17 @@ function mapRow(row: SubmissionRow): StoredSubmission {
     completedAt: row.completed_at,
     assemblyRevision: row.assembly_revision,
     assemblyDescriptor: row.assembly_descriptor,
+    runtimeKey: row.runtime_key,
     assistantMessageId: row.assistant_message_id,
     abortReason: row.abort_reason,
     queuedInputJson: row.queued_input_json,
     queuedUiMessageJson: row.queued_ui_message_json,
     userMessageId: row.user_message_id,
     regenerateMessageId: row.regenerate_message_id,
-    recoveryErrorCount: row.recovery_error_count,
-    recoveryReason: row.recovery_reason as SubmissionRecoveryReason | null,
     runId: row.run_id,
     retryable: row.admission_retryable === null
       ? undefined
       : row.admission_retryable === 1,
-    modelTurns: row.model_turns ?? 0,
-    continuationId: row.continuation_id,
   };
 }
 
@@ -138,7 +130,14 @@ export class SubmissionRepository {
   // 保存当前 Agent SQLite 的查询入口。
   // RuntimeDatabase 构造时调用，SubmissionLifecycle 和 Runtime 随后共享这个 Repository。
   // Submission 的准入、执行和恢复必须看同一 Agent 存储，不能混入其他 Durable Object 的 sql。
-  constructor(private readonly sql: SqlTaggedTemplate) {}
+  constructor(
+    private readonly sql: SqlTaggedTemplate,
+    private readonly transact: <T>(run: () => T) => T,
+  ) {}
+
+  transaction<T>(run: () => T): T {
+    return this.transact(run);
+  }
 
   // 按 submissionId 读取一条完整 Submission，不存在时返回 null。
   // Runtime 和 SubmissionLifecycle 在准入、执行、取消、结束与恢复时调用，调用方必须处理 null。
@@ -147,12 +146,11 @@ export class SubmissionRepository {
     const row = this.sql<SubmissionRow>`
       SELECT submission_id, request_id, idempotency_key, status, accepted,
              error, created_at, completed_at, assembly_revision,
-             assembly_descriptor, assistant_message_id, abort_reason,
+             assembly_descriptor, runtime_key, assistant_message_id, abort_reason,
              queued_input_json, queued_ui_message_json, user_message_id,
-             regenerate_message_id, recovery_error_count, recovery_reason,
+             regenerate_message_id,
              run_id,
-             admission_retryable,
-             model_turns, continuation_id
+             admission_retryable
       FROM pi_submissions
       WHERE submission_id = ${id}
     `[0];
@@ -250,7 +248,7 @@ export class SubmissionRepository {
     this.sql`
       INSERT INTO pi_submissions (
         submission_id, request_id, idempotency_key, status, accepted,
-        created_at, assembly_revision, assembly_descriptor,
+        created_at, assembly_revision, assembly_descriptor, runtime_key,
         assistant_message_id, queued_input_json, queued_ui_message_json,
         user_message_id, regenerate_message_id,
         run_id
@@ -263,6 +261,7 @@ export class SubmissionRepository {
         ${s.createdAt},
         ${s.assemblyRevision},
         ${s.assemblyDescriptor},
+        ${s.runtimeKey ?? ""},
         ${s.assistantMessageId},
         ${s.queuedInputJson ?? null},
         ${s.queuedUiMessageJson ?? null},
@@ -280,17 +279,19 @@ export class SubmissionRepository {
     createdAt: number;
     code: string;
     retryable: boolean;
+    userMessageId?: string;
+    assistantMessageId?: string;
   }): void {
     this.sql`
       INSERT INTO pi_submissions (
         submission_id, request_id, idempotency_key, status, accepted,
         error, created_at, completed_at, assembly_revision,
-        assembly_descriptor, assistant_message_id, abort_reason,
-        recovery_error_count, recovery_reason, run_id, admission_retryable
+        assembly_descriptor, runtime_key, assistant_message_id, abort_reason,
+        run_id, admission_retryable, user_message_id
       ) VALUES (
         ${s.submissionId}, ${s.requestId}, ${s.idempotencyKey}, 'skipped', 0,
-        ${s.code}, ${s.createdAt}, ${s.createdAt}, '', '', '', NULL,
-        0, NULL, ${s.submissionId}, ${s.retryable ? 1 : 0}
+        ${s.code}, ${s.createdAt}, ${s.createdAt}, '', '', '', ${s.assistantMessageId ?? s.submissionId}, NULL,
+        ${s.submissionId}, ${s.retryable ? 1 : 0}, ${s.userMessageId ?? null}
       )
     `;
   }
@@ -309,24 +310,6 @@ export class SubmissionRepository {
     return updated.length === 1;
   }
 
-  // 把一条已 pin 的 Submission 换到另一对 revision / descriptor 上。
-  // Runtime 在「停在人机等待期间换了装配」之后调用，必须与那次装配迁移里程碑同事务。
-  // 与 pinAssembly 的区别就是它要求已经 pin 过：首次 pin 走 pinAssembly，
-  // 这里不接受空值，避免把一次漏写的准入 pin 伪装成一次迁移。
-  repinAssembly(id: string, revision: string, descriptor: string): boolean {
-    const updated = this.sql<{ submission_id: string }>`
-      UPDATE pi_submissions
-      SET assembly_revision = ${revision},
-          assembly_descriptor = ${descriptor}
-      WHERE submission_id = ${id}
-        AND assembly_revision <> ''
-        AND assembly_descriptor <> ''
-        AND status IN ('pending', 'running')
-      RETURNING submission_id
-    `;
-    return updated.length === 1;
-  }
-
   // 只在当前状态属于 from 时把 Submission 切换到 to，否则返回 false。
   // SubmissionLifecycle 开始 Turn 时调用，调用方用返回值识别过期或重复的状态切换。
   // Cloudflare SQLite 查询是同步的，两条语句之间不会让其他事件交错；UPDATE 再次带旧状态条件，不能去掉这层幂等保护。
@@ -393,84 +376,44 @@ export class SubmissionRepository {
     `;
   }
 
-  // chatRecovery 遇到 partial 会重置 attempt；Submission 计数保证同一 Turn 的可恢复模型错误仍绝对封顶。
-  incrementRecoveryErrorCount(
-    id: string,
-    reason: SubmissionRecoveryReason,
-  ): number {
-    return this.sql<{ recovery_error_count: number }>`
-      UPDATE pi_submissions
-      SET recovery_error_count = recovery_error_count + 1,
-          recovery_reason = ${reason}
-      WHERE submission_id = ${id}
-        AND status IN ('pending', 'running')
-      RETURNING recovery_error_count
-    `[0]?.recovery_error_count ?? 0;
-  }
-
-  claimContextOverflowRecovery(id: string): boolean {
-    return Boolean(this.sql<{ claimed: number }>`
-      UPDATE pi_submissions
-      SET context_overflow_retried = 1
-      WHERE submission_id = ${id}
-        AND status IN ('pending', 'running')
-        AND context_overflow_retried = 0
-      RETURNING 1 AS claimed
-    `[0]?.claimed);
-  }
-
-  /**
-   * 记录一个让步执行片的累计模型回合数和续跑标识。
-   *
-   * @remarks
-   * Runtime 在一片主动让出后、排出续跑调度之前调用。
-   *
-   * 两个值必须一起写：全局回合预算靠 `model_turns` 拦住不收敛的工具循环，
-   * 续跑去重和看门狗靠 `continuation_id` 判断这一轮到底有没有推进。
-   * 只写非终态记录，避免一次迟到的写入复活已经结束的 Submission。
-   */
-  recordYieldedSlice(
-    id: string,
-    modelTurns: number,
-    continuationId: string,
-  ): void {
-    this.sql`
-      UPDATE pi_submissions
-      SET model_turns = ${modelTurns},
-          continuation_id = ${continuationId}
-      WHERE submission_id = ${id}
-        AND status IN ('pending', 'running')
-    `;
-  }
-
-  /** 记录累计模型回合数，不改动续跑标识。终态提交前的最后一次结算用它。 */
-  recordModelTurns(id: string, modelTurns: number): void {
+  // 持久化 Session entry 到 Submission 的关联，使 Host 可以从 Pi 分支
+  // 回填 message、ToolResult 和 compaction 的用量与结算 Outbox。
+  linkSessionEntry(entryId: string, submissionId: string): void {
     this.sql`
-      UPDATE pi_submissions
-      SET model_turns = ${modelTurns}
-      WHERE submission_id = ${id}
-        AND status IN ('pending', 'running')
+      INSERT OR IGNORE INTO pi_session_entry_submission
+        (entry_id, submission_id)
+      VALUES (${entryId}, ${submissionId})
     `;
   }
 
-  clearRecoveryReason(id: string): void {
-    this.sql`
-      UPDATE pi_submissions
-      SET recovery_reason = NULL
-      WHERE submission_id = ${id}
-        AND status IN ('pending', 'running')
-    `;
+  /** Recover ownership from the matching Pi operation, using only its active branch. */
+  associateSessionEntries(
+    submissionId: string,
+    snapshot: Pick<LaneSnapshot, "operation" | "lastResult" | "tipId" | "transcript">,
+  ): void {
+    const boundary = snapshot.operation?.id === submissionId
+      ? { fromTipId: snapshot.operation.fromTipId, tipId: snapshot.tipId }
+      : snapshot.lastResult?.operationId === submissionId
+        ? snapshot.lastResult
+        : undefined;
+    if (!boundary) return;
+    const start = boundary.fromTipId === null
+      ? 0
+      : snapshot.transcript.findIndex(({ id }) => id === boundary.fromTipId) + 1;
+    const end = boundary.tipId === null
+      ? snapshot.transcript.length
+      : snapshot.transcript.findIndex(({ id }) => id === boundary.tipId) + 1;
+    for (const entry of snapshot.transcript.slice(start, end || undefined)) {
+      this.linkSessionEntry(entry.id, submissionId);
+    }
   }
 
-  // 返回所有标准会话消息到 Submission 的关联映射。
-  // Transcript.storedMessages 读取 Pi Session 分支时调用，它用 Map 为每条消息补回 submissionId。
-  // 关联表由 Pi Session 存储拥有，本方法只读不写；不能在 RuntimeDatabase.clearAll 中单独删它而破坏 Transcript 的所有权。
-  listMessageSubmissionLinks(): Map<string, string> {
+  listSessionEntrySubmissionLinks(): Map<string, string> {
     const rows = this.sql<{
-      message_id: string;
+      entry_id: string;
       submission_id: string;
-    }>`SELECT message_id, submission_id FROM pi_session_message_submission`;
-    return new Map(rows.map((r) => [r.message_id, r.submission_id] as [string, string]));
+    }>`SELECT entry_id, submission_id FROM pi_session_entry_submission`;
+    return new Map(rows.map((r) => [r.entry_id, r.submission_id] as [string, string]));
   }
 }
 // #endregion

package/src/submission/steer-delivery.ts

@@ -0,0 +1,167 @@
+import type { CancelQueuedResult, LaneSnapshot } from "@earendil-works/pi-agent-core";
+import type { UIMessage } from "ai";
+import type { ConversationHistory } from "../conversation/history";
+import type { SubmitMessageOptions } from "./admission";
+import type { SubmissionHandle } from "./lifecycle";
+import { submissionAbortReason, type StoredSubmission, type SubmissionRepository } from "./repository";
+import type { PiCanonicalUserInput } from "../conversation/message/contract";
+import type { MessageUiRepository } from "../conversation/repository";
+import type { PendingSteer, SteerRepository } from "./steer-repository";
+
+interface PendingSteerDeliveryOptions {
+  steers: SteerRepository;
+  messageUi: MessageUiRepository;
+  transaction<T>(run: () => T): T;
+  enqueue(message: PiCanonicalUserInput): Promise<string>;
+}
+
+/** Reconciles Host steer receipts with Pi queue identities, without owning execution. */
+export class PendingSteerDelivery {
+  constructor(private readonly options: PendingSteerDeliveryOptions) {}
+
+  async queue(steer: PendingSteer): Promise<void> {
+    const entryId = await this.options.enqueue(
+      JSON.parse(steer.canonicalJson) as PiCanonicalUserInput,
+    );
+    this.link(steer, entryId);
+  }
+
+  /** Called after Pi commits the original queued user entry. */
+  settle(entryId: string): boolean {
+    const steer = this.options.steers.findByHarnessEntryId(entryId);
+    if (!steer) return false;
+    this.options.transaction(() => {
+      this.persistSidecar(steer, entryId);
+      this.options.steers.deleteByMessageId(steer.messageId);
+    });
+    return true;
+  }
+
+  async reconcile(
+    submissionId: string,
+    snapshot: Pick<LaneSnapshot, "queues" | "transcript">,
+  ): Promise<void> {
+    const pending = this.options.steers.listForSubmission(submissionId);
+    const queuedIds = new Set(snapshot.queues.map(({ entryId }) => entryId));
+    const transcriptIds = new Set(snapshot.transcript.map(({ id }) => id));
+    const linkedIds = new Set(pending.flatMap(({ harnessEntryId }) =>
+      harnessEntryId ? [harnessEntryId] : []
+    ));
+    const unlinked = snapshot.queues.filter((entry) =>
+      entry.kind === "steer" && entry.type === "message" &&
+      !linkedIds.has(entry.entryId)
+    );
+    // Both durable queues preserve acceptance order; identical text is not identity.
+    for (const steer of pending) {
+      if (steer.harnessEntryId && transcriptIds.has(steer.harnessEntryId)) {
+        this.settle(steer.harnessEntryId);
+      } else if (steer.harnessEntryId && queuedIds.has(steer.harnessEntryId)) {
+        this.options.transaction(() =>
+          this.persistSidecar(steer, steer.harnessEntryId!)
+        );
+      } else {
+        const queued = !steer.harnessEntryId ? unlinked.shift() : undefined;
+        if (queued) this.link(steer, queued.entryId);
+        else await this.queue(steer);
+      }
+    }
+  }
+
+  private link(steer: PendingSteer, entryId: string): void {
+    this.options.transaction(() => {
+      if (steer.harnessEntryId && steer.harnessEntryId !== entryId) {
+        this.options.messageUi.delete(steer.harnessEntryId);
+      }
+      this.options.steers.linkHarnessEntry(steer.messageId, entryId);
+      this.persistSidecar(steer, entryId);
+    });
+  }
+
+  private persistSidecar(steer: PendingSteer, entryId: string): void {
+    if (steer.uiMessageJson) {
+      this.options.messageUi.upsert(entryId, steer.uiMessageJson);
+    }
+  }
+}
+
+
+/** Keep accepted steers visible on stop, or transfer unconsumed messages to new Submissions. */
+export async function finishPendingSteers(options: {
+  submissionId: string;
+  aborted: boolean;
+  submissions: SubmissionRepository;
+  cancelHandoff(submissionId: string, reason: string): StoredSubmission;
+  steers: SteerRepository;
+  messageUi: MessageUiRepository;
+  transaction<T>(run: () => T): T;
+  conversation: Pick<ConversationHistory, "append">;
+  cancelQueued(entryId: string): Promise<CancelQueuedResult | undefined>;
+  submit(
+    message: PiCanonicalUserInput,
+    options: SubmitMessageOptions,
+  ): Promise<SubmissionHandle<StoredSubmission>>;
+  waitUntil(promise: Promise<unknown>): void;
+}): Promise<void> {
+  for (const steer of options.steers.listForSubmission(options.submissionId)) {
+    const message = JSON.parse(steer.canonicalJson) as PiCanonicalUserInput;
+    const userMessage = steer.uiMessageJson
+      ? JSON.parse(steer.uiMessageJson) as UIMessage & { role: "user" }
+      : undefined;
+    const requestId = `${options.submissionId}:steer:${steer.steerId}`;
+    if (options.aborted) {
+      options.transaction(() => {
+        let handoff = options.submissions.findByRequestId(requestId);
+        if (handoff?.status === "pending") {
+          const reason = submissionAbortReason(options.submissions.find(options.submissionId)) ?? "Cancelled";
+          options.submissions.updateAbortReason(handoff.submissionId, reason);
+          handoff = options.cancelHandoff(handoff.submissionId, reason);
+        }
+        if (steer.harnessEntryId) options.messageUi.delete(steer.harnessEntryId);
+        options.conversation.append(steer.messageId, message, {
+          submissionId: handoff?.status === "aborted" || handoff?.status === "skipped"
+            ? handoff.submissionId
+            : options.submissionId,
+          ...(userMessage ? { userMessage } : {}),
+        });
+        options.steers.deleteByMessageId(steer.messageId);
+      });
+      continue;
+    }
+    if (steer.harnessEntryId) {
+      const cancelled = await options.cancelQueued(steer.harnessEntryId);
+      if (cancelled) {
+        if (!cancelled.ok) throw cancelled.error;
+        if (cancelled.value.kind === "already_consumed") {
+          options.transaction(() => options.steers.deleteByMessageId(steer.messageId));
+          continue;
+        }
+        options.transaction(() => options.messageUi.delete(steer.harnessEntryId!));
+      }
+    }
+    // A queued Submission moved to this Turn already owns messageId and is aborted.
+    // Handoff needs its own stable identity while preserving the user's message identity.
+    const submitted = await options.submit(message, {
+      requestId,
+      idempotencyKey: requestId,
+      userMessageId: steer.messageId,
+      steerHandoff: { submissionId: options.submissionId, steerId: steer.steerId },
+      ...(userMessage ? { userMessage } : {}),
+    });
+    options.waitUntil(submitted.completion);
+    options.transaction(() => {
+      let handoff = options.submissions.find(submitted.receipt.submissionId) ?? submitted.receipt;
+      const abortReason = submissionAbortReason(options.submissions.find(options.submissionId));
+      if (abortReason && handoff.status === "pending" && handoff.requestId === requestId) {
+        options.submissions.updateAbortReason(handoff.submissionId, abortReason);
+        handoff = options.cancelHandoff(handoff.submissionId, abortReason);
+      }
+      if (handoff.status === "skipped" || handoff.status === "aborted") {
+        options.conversation.append(steer.messageId, message, {
+          submissionId: handoff.submissionId,
+          ...(userMessage ? { userMessage } : {}),
+        });
+      }
+      options.steers.deleteByMessageId(steer.messageId);
+    });
+  }
+}