@nuvin/session 0.4.0-rc.1 → 0.4.0-rc.11

package/dist/controller/index.js

@@ -2,7 +2,9 @@ import {
   resolveGrantDir
 } from "../chunk-UVJIG4DT.js";
 import {
+  appendRecallEntry,
   asJsonObject,
+  copyRecallState,
   createMessageStateFromMessages,
   createSessionViewState,
   isToolAutoApprovedForMode,
@@ -11,7 +13,7 @@ import {
   sanitizeCoordinatorDeliveryText,
   scopedToolKey,
   summarizeToolCallInput
-} from "../chunk-DTLHDYZC.js";
+} from "../chunk-4FXP5TSI.js";
 
 // src/controller/agent-channel.ts
 import { EventEmitter } from "events";
@@ -27,12 +29,22 @@ var AgentChannel = class {
   decider = null;
   questionHandler = null;
   // ---------- Agent-side (publishers) ----------
-  publishEvent(event, scope) {
+  publishEvent(event, scope, executionId) {
     this.emitter.emit("event", {
       event,
+      ...executionId === void 0 ? {} : { executionId },
       scope: scope === void 0 ? void 0 : toWireSessionScope(scope)
     });
   }
+  publishRecallEntry(entry) {
+    this.emitter.emit("recall-entry", entry);
+  }
+  onRecallEntry(listener) {
+    this.emitter.on("recall-entry", listener);
+    return () => {
+      this.emitter.off("recall-entry", listener);
+    };
+  }
   publishSessionLoaded(loaded) {
     this.emitter.emit("session-loaded", loaded);
   }
@@ -80,8 +92,10 @@ var AgentChannel = class {
 };
 
 // src/controller/session-controller.ts
+import { randomUUID } from "crypto";
 import {
-  isAbortError
+  isAbortError,
+  isAgentOnlyCoordinatorNotice
 } from "@nuvin/agent-core/shared";
 function formatBashPolicyDenial(diagnostics) {
   const denied = diagnostics.operations.filter((operation) => operation.decision === "deny");
@@ -94,22 +108,109 @@ function formatBashPolicyDenial(diagnostics) {
   });
   return `Bash command rejected by policy: ${details.join("; ")}.`;
 }
+function coordinatorInfoMeta(submission) {
+  if (submission.origin !== "coordinator") return {};
+  if (isAgentOnlyCoordinatorNotice(submission)) {
+    return {
+      deliveryKind: submission.deliveryKind,
+      transcriptVisibility: "agent-only"
+    };
+  }
+  return submission.subagentReport === void 0 ? {} : { subagentReport: structuredClone(submission.subagentReport) };
+}
 function preservesVerbatimCoordinatorInput(submission) {
-  return submission?.origin === "coordinator" && submission.deliveryKind === "subagent-report";
+  return submission?.origin === "coordinator" && (submission.deliveryKind === "subagent-report" || isAgentOnlyCoordinatorNotice(submission));
 }
 var MAX_AUTO_COMPACTION_CHAIN = 10;
+function substantiveEventActivity(event) {
+  if (event.type === "assistant_chunk")
+    return event.chunk.text?.length ? "assistant-text" : void 0;
+  if (event.type === "reasoning_chunk") return event.text.length ? "reasoning" : void 0;
+  if (event.type === "tool_call" || event.type === "tool_use_chunk" || event.type === "tool_use_message")
+    return "tool";
+  const content = event.type === "model_response" ? event.response.content : event.type === "assistant_message" || event.type === "reasoning_message" || event.type === "final_message" ? event.message.content : [];
+  for (const block of content) {
+    if (block.type === "text" && block.text.length > 0) return "assistant-text";
+    if (block.type === "tool_use") return "tool";
+    if (block.type === "anthropic_thinking" && block.thinking.length > 0 || block.type === "anthropic_redacted_thinking" && block.data.length > 0 || block.type === "openai_reasoning" && (block.text?.length || block.encryptedContent?.length || block.summary.some((part) => part.text.length > 0)))
+      return "reasoning";
+  }
+  return void 0;
+}
 function createSessionController(deps) {
   const now = deps.now ?? Date.now;
   const errorDetail = deps.errorDetail ?? ((error) => error instanceof Error ? error.message : String(error));
   let serverCommands = deps.serverCommands ?? [];
+  let submissionRecovery = deps.submissionRecovery;
   let compaction = deps.compaction;
   let guardPrompt = deps.guardPrompt;
   let autoCompactionChain = 0;
   let state = createSessionViewState();
+  const activeHumans = [];
+  const hostHumanReservations = /* @__PURE__ */ new Set();
+  const matchesIdentity = (key) => {
+    const identity = state.recall.identity;
+    return identity !== null && identity.profile === key.identity.profile && identity.workspace === key.identity.workspace && identity.sessionId === key.identity.sessionId;
+  };
+  const inputText = (input) => typeof input === "string" ? input : typeof input.content === "string" ? input.content : (input.content ?? []).filter((block) => block.type === "text").map((block) => block.text).join("");
+  const humanId = (submission) => submission?.origin === "user" ? submission.humanSubmission?.submissionId : void 0;
+  const admitHuman = (input, opts) => {
+    if (opts.human !== void 0 && !matchesIdentity({
+      identity: opts.human.identity,
+      submissionId: opts.human.submission.submissionId
+    }))
+      throw new Error("Human submission identity mismatch");
+    if (opts.submission !== void 0 && opts.submission.origin !== "user") {
+      return {
+        ...opts,
+        ...opts.human === void 0 ? {} : { human: structuredClone(opts.human) }
+      };
+    }
+    const humanSubmission = structuredClone(
+      opts.human?.submission ?? (opts.submission?.origin === "user" ? opts.submission.humanSubmission : void 0) ?? {
+        submissionId: randomUUID(),
+        rawText: inputText(input)
+      }
+    );
+    if (typeof humanSubmission.submissionId !== "string" || humanSubmission.submissionId.trim().length === 0 || typeof humanSubmission.rawText !== "string" || Object.keys(humanSubmission).some((key) => key !== "submissionId" && key !== "rawText"))
+      throw new Error("Invalid human submission");
+    const previous = [
+      ...state.recall.entries.map((entry) => ({
+        submissionId: entry.key.submissionId,
+        rawText: entry.rawText
+      })),
+      ...activeHumans,
+      ...[...hostHumanReservations].filter(
+        (entry) => matchesIdentity({
+          identity: entry.identity,
+          submissionId: entry.submission.submissionId
+        })
+      ).map((entry) => entry.submission),
+      ...queue.flatMap(
+        (entry) => entry.opts.submission?.origin === "user" && entry.opts.submission.humanSubmission !== void 0 ? [entry.opts.submission.humanSubmission] : []
+      )
+    ].find((entry) => entry.submissionId === humanSubmission.submissionId);
+    if (previous !== void 0 && previous.rawText !== humanSubmission.rawText)
+      throw new Error("Conflicting submission raw text");
+    return {
+      ...opts,
+      submission: { origin: "user", humanSubmission },
+      ...opts.human === void 0 ? {} : { human: structuredClone(opts.human) }
+    };
+  };
   let seq = 0;
   let approvalMode = deps.approvalMode ?? "readOnly";
   let abortController = null;
   let activeTurnPromise = null;
+  let executionOwner = null;
+  let recoveryPromise = null;
+  const recoveryResults = /* @__PURE__ */ new Map();
+  const recoveryKey = (key) => JSON.stringify([
+    key.identity.profile,
+    key.identity.workspace,
+    key.identity.sessionId,
+    key.submissionId
+  ]);
   let closePromise = null;
   let closing = false;
   let detached = false;
@@ -129,7 +230,7 @@ function createSessionController(deps) {
   let draining = false;
   const emit = (body, explicitTurnId) => {
     seq += 1;
-    const turnId = explicitTurnId ?? activeTurnId;
+    const turnId = explicitTurnId === null ? void 0 : explicitTurnId ?? activeTurnId;
     const event = Object.assign(
       {},
       body,
@@ -155,26 +256,45 @@ function createSessionController(deps) {
     }
   };
   const emitTurnStatus = () => {
+    const visible = queue.filter((q) => !isAgentOnlyCoordinatorNotice(q.opts.submission));
     emit({
       type: "turn-status",
       busy: abortController !== null || hostBusyCount > 0,
-      queuedCount: queue.length,
-      queued: queue.map((q) => ({
+      queuedCount: visible.length,
+      queued: visible.map((q) => ({
         id: q.id,
         displayText: q.opts.displayText,
         ...q.opts.attachmentLabels?.length ? { attachmentLabels: q.opts.attachmentLabels } : {}
       }))
     });
   };
-  const unsubscribeEvents = deps.channel.onEvent(({ event, scope }) => {
+  const unsubscribeEvents = deps.channel.onEvent(({ event, scope, executionId }) => {
+    const owner = executionId === void 0 ? void 0 : executionOwner;
+    if (executionId !== void 0) {
+      if (!owner || owner.control.executionId !== executionId || owner.phase === "recovering" || owner.phase === "finished")
+        return;
+      const substantive = substantiveEventActivity(event);
+      if (substantive && !owner.control.claimActivity(substantive)) return;
+    }
     if (event.type === "tool_call") return;
-    emit({ type: "agent-event", event, ...scope ? { scope } : {} });
+    emit(
+      { type: "agent-event", event, ...scope ? { scope } : {} },
+      executionId === void 0 ? void 0 : owner?.turnId ?? null
+    );
+  });
+  const unsubscribeRecall = deps.channel.onRecallEntry((entry) => {
+    const recall = appendRecallEntry(state.recall, entry);
+    if (recall !== state.recall) emit({ type: "recall-state", recall });
   });
   const unsubscribeLoaded = deps.channel.onSessionLoaded((loaded) => {
+    copyRecallState(loaded.recall);
+    if (loaded.recall.identity !== null && loaded.recall.identity.sessionId !== loaded.id)
+      throw new Error("Loaded recall identity mismatch");
     if (persistenceInFlight.size > 0) {
       return;
     }
     queue.length = 0;
+    activeHumans.length = 0;
     alwaysApproved.clear();
     abortController?.abort(new Error("Session loaded; the active turn was cancelled."));
     rejectAllPending("Session loaded; pending interactions were cancelled.");
@@ -188,11 +308,15 @@ function createSessionController(deps) {
         ...createSessionViewState(),
         busy: hostBusyCount > 0,
         meta: state.meta,
-        messages: createMessageStateFromMessages(loaded.messages)
+        messages: createMessageStateFromMessages(loaded.messages),
+        recall: loaded.recall
       }
     });
   });
   deps.channel.setToolDecider((request) => {
+    if (request.executionId !== void 0 && (executionOwner?.control.executionId !== request.executionId || !executionOwner.control.claimActivity("tool"))) {
+      return { action: "reject", reason: "Originating execution is no longer active." };
+    }
     const { toolCall, agentId, toolCallPath, dirAccess, bashPolicy } = request;
     const scope = toolCallPath === void 0 ? void 0 : { agentId, toolCallPath: [...toolCallPath] };
     const approvalKey = request.approvalKey ?? `${agentId}:${toolCall.name}`;
@@ -408,80 +532,150 @@ function createSessionController(deps) {
       return { ok: false, message: errorDetail(error) };
     }
   }
+  function allowsSteering(opts) {
+    return opts.turnId === void 0 || deps.headless !== true && opts.submission?.origin === "coordinator" && opts.submission.deliveryKind === "subagent-report";
+  }
   function startNextQueuedSubmission() {
     if (closing || abortController || hostBusyCount > 0) return;
-    const next = queue.shift();
+    let next = queue.shift();
+    let dropped = false;
+    while (next?.opts.signal?.aborted) {
+      dropped = true;
+      next = queue.shift();
+    }
+    if (dropped) emitTurnStatus();
     if (!next) return;
     const coordinatorOwned = next.opts.submission?.origin === "coordinator";
-    if (!coordinatorOwned && !next.opts.silent) {
-      emit(
-        {
-          type: "user-message",
-          text: next.opts.displayText,
-          ...next.opts.attachmentLabels?.length ? { attachmentLabels: next.opts.attachmentLabels } : {}
-        },
-        next.opts.turnId
-      );
-    }
-    void startTrackedTurn(next.input, {
+    const turn = startTrackedTurn(next.input, {
+      echo: coordinatorOwned || next.opts.silent ? void 0 : next.opts,
+      human: next.opts.human,
       turnId: next.opts.turnId,
-      allowSteering: next.opts.turnId === void 0,
+      allowSteering: allowsSteering(next.opts),
       submission: next.opts.submission ?? { origin: "user" },
       ...coordinatorOwned ? { coordinatorDisplayText: next.opts.displayText } : {},
       ...next.opts.signal === void 0 ? {} : { signal: next.opts.signal }
     });
+    if (next.opts.waitFor === "acceptance") observeAcceptedTurn(turn, next.opts.turnId);
+  }
+  function sealExecution(owner) {
+    owner.phase = "finished";
+    if (owner.key && !recoveryResults.has(recoveryKey(owner.key)))
+      recoveryResults.set(
+        recoveryKey(owner.key),
+        Promise.resolve({ status: "not-retracted", target: owner.key, reason: "already-finished" })
+      );
   }
   function finalizeTurn(controller, reason) {
-    if (abortController !== controller) return false;
-    abortController = null;
+    if (abortController !== controller || executionOwner?.phase === "recovering") return false;
+    const endingOwner = executionOwner;
+    if (endingOwner?.controller === controller) sealExecution(endingOwner);
     rejectAllPending(reason);
+    if (abortController !== controller || executionOwner !== endingOwner) return false;
+    executionOwner = null;
+    abortController = null;
+    activeHumans.length = 0;
+    emit({ type: "active-human-submission", key: null });
     emitTurnStatus();
     return true;
   }
   async function runTurn(input, opts) {
-    const controller = new AbortController();
+    if (opts.submission.origin === "user" && opts.submission.humanSubmission !== void 0)
+      activeHumans.push(opts.submission.humanSubmission);
+    const controller = opts.enclosingExecution?.controller ?? new AbortController();
+    const openingHuman = opts.human?.submission ?? (opts.submission.origin === "user" ? opts.submission.humanSubmission : void 0);
+    const identity = opts.human?.identity ?? state.recall.identity;
+    let resolveSettlement;
+    let rejectSettlement;
+    const settled = new Promise((resolve, reject) => {
+      resolveSettlement = resolve;
+      rejectSettlement = reject;
+    });
+    void settled.catch(() => {
+    });
+    const owner = {
+      controller,
+      turnId: opts.correlationTurnId ?? opts.turnId,
+      key: openingHuman && identity ? { identity: { ...identity }, submissionId: openingHuman.submissionId } : null,
+      rawText: openingHuman?.rawText ?? "",
+      phase: "eligible",
+      settled,
+      settle() {
+        if (owner.abortFailure !== void 0) rejectSettlement(owner.abortFailure);
+        else resolveSettlement();
+      },
+      control: Object.freeze({
+        executionId: randomUUID(),
+        claimActivity() {
+          if (executionOwner !== owner || owner.phase === "recovering" || owner.phase === "finished")
+            return false;
+          owner.phase = "activity-started";
+          return true;
+        }
+      })
+    };
+    executionOwner = owner;
     const abortFromCaller = () => controller.abort(opts.signal?.reason);
     if (opts.signal !== void 0) {
       if (opts.signal.aborted) abortFromCaller();
       else opts.signal.addEventListener("abort", abortFromCaller, { once: true });
     }
+    const steeringClosed = () => owner.phase === "recovering" || owner.phase === "finished";
     const drainSteering = async () => {
-      if (abortController !== controller || controller.signal.aborted) return [];
+      if (abortController !== controller || controller.signal.aborted || steeringClosed())
+        return [];
       const barrierIndex = queue.findIndex((entry) => entry.delivery === "next-turn");
       const steeringCount = barrierIndex === -1 ? queue.length : barrierIndex;
       if (steeringCount === 0) return [];
       const drained = queue.splice(0, steeringCount);
+      for (const entry of drained) {
+        if (entry.opts.submission?.origin === "user" && entry.opts.submission.humanSubmission !== void 0)
+          activeHumans.push(entry.opts.submission.humanSubmission);
+      }
       emitTurnStatus();
       const accepted = [];
       for (const entry of drained) {
+        if (entry.opts.signal?.aborted) continue;
         const guarded = await guardQueuedSteering(entry.input);
+        if (entry.opts.signal?.aborted) continue;
         if (guarded.ok) {
           accepted.push({
             input: preservesVerbatimCoordinatorInput(entry.opts.submission) ? entry.input : guarded.prompt,
-            opts: entry.opts
+            opts: entry.opts,
+            queuedAt: entry.queuedAt
           });
         } else {
           emit({ type: "error", message: guarded.message });
         }
       }
-      if (abortController !== controller || controller.signal.aborted) return [];
-      for (const entry of accepted) {
+      if (abortController !== controller || controller.signal.aborted || steeringClosed())
+        return [];
+      const current = accepted.filter((entry) => !entry.opts.signal?.aborted);
+      for (const entry of current) {
         if (entry.opts.submission?.origin === "coordinator") {
           emit({
             type: "info",
             message: sanitizeCoordinatorDeliveryText(entry.opts.displayText),
-            ...entry.opts.submission.subagentReport === void 0 ? {} : { subagentReport: structuredClone(entry.opts.submission.subagentReport) }
+            ...coordinatorInfoMeta(entry.opts.submission)
           });
         } else if (!entry.opts.silent) {
           emit({
             type: "user-message",
             text: entry.opts.displayText,
-            ...entry.opts.attachmentLabels?.length ? { attachmentLabels: entry.opts.attachmentLabels } : {}
+            ...humanId(entry.opts.submission) === void 0 ? {} : { submissionId: humanId(entry.opts.submission) },
+            ...entry.opts.attachmentLabels?.length ? { attachmentLabels: entry.opts.attachmentLabels } : {},
+            // The drain stamps event.at at delivery; steeredAt preserves when
+            // the client actually queued the input — the HUD's "time since
+            // last input" and the persisted steer marker both key off it.
+            steeredAt: entry.queuedAt
           });
         }
       }
-      return accepted.map(
-        (entry) => entry.opts.submission?.origin === "coordinator" ? { input: entry.input, submission: entry.opts.submission } : entry.input
+      return current.map(
+        (entry) => ({
+          input: entry.input,
+          submission: entry.opts.submission ?? { origin: "user" },
+          steeredAt: entry.queuedAt
+        })
       );
     };
     const previousTurnId = activeTurnId;
@@ -491,6 +685,18 @@ function createSessionController(deps) {
     let terminalStatus = "completed";
     let terminalMessage;
     try {
+      emit({ type: "active-human-submission", key: owner.key });
+      if (opts.echo) {
+        emit(
+          {
+            type: "user-message",
+            text: opts.echo.displayText,
+            ...humanId(opts.submission) === void 0 ? {} : { submissionId: humanId(opts.submission) },
+            ...opts.echo.attachmentLabels?.length ? { attachmentLabels: opts.echo.attachmentLabels } : {}
+          },
+          opts.turnId
+        );
+      }
       emitTurnStatus();
       if (!opts.systemInitiated) autoCompactionChain = 0;
       compaction?.setEnabled(true);
@@ -498,7 +704,15 @@ function createSessionController(deps) {
       if (!opts.systemInitiated && guardPrompt) {
         let guarded;
         try {
+          if (opts.signal?.aborted) {
+            terminalStatus = "aborted";
+            return;
+          }
           guarded = await guardPrompt(input);
+          if (opts.signal?.aborted) {
+            terminalStatus = "aborted";
+            return;
+          }
         } catch (error) {
           terminalStatus = "failed";
           terminalMessage = errorDetail(error);
@@ -513,18 +727,27 @@ function createSessionController(deps) {
         }
         finalInput = preservesVerbatimCoordinatorInput(opts.submission) ? input : guarded.prompt;
       }
+      if (opts.signal?.aborted) {
+        terminalStatus = "aborted";
+        return;
+      }
       if (opts.coordinatorDisplayText !== void 0) {
         emit({
           type: "info",
           message: sanitizeCoordinatorDeliveryText(opts.coordinatorDisplayText),
-          ...opts.submission.origin === "coordinator" && opts.submission.subagentReport !== void 0 ? { subagentReport: structuredClone(opts.submission.subagentReport) } : {}
+          ...coordinatorInfoMeta(opts.submission)
         });
       }
       const compactionSend = (text) => runTurn(text, {
         systemInitiated: true,
         transientInput: true,
+        correlationTurnId: owner.turnId,
+        enclosingExecution: owner,
         allowSteering: opts.allowSteering,
-        submission: opts.submission,
+        submission: {
+          origin: "synthetic",
+          syntheticKind: "compaction"
+        },
         ...opts.signal === void 0 ? {} : { signal: opts.signal }
       });
       const compactionIo = {
@@ -533,8 +756,14 @@ function createSessionController(deps) {
         onInfo: (message) => emit({ type: "info", message }),
         onError: (message) => emit({ type: "error", message })
       };
+      const sealForMaintenance = () => {
+        if (owner.phase === "recovering") return false;
+        sealExecution(owner);
+        if (executionOwner === owner) emit({ type: "active-human-submission", key: null });
+        return true;
+      };
       const runCompaction = async () => {
-        if (!compaction) return;
+        if (!compaction || owner.phase === "recovering") return;
         if (autoCompactionChain >= MAX_AUTO_COMPACTION_CHAIN) {
           compaction.setEnabled(false);
           emit({
@@ -548,16 +777,17 @@ function createSessionController(deps) {
       };
       try {
         const result = await deps.agent.send(finalInput, {
+          execution: owner.control,
           streaming: true,
           signal: controller.signal,
           submission: opts.submission,
           ...opts.transientInput === true ? { transientInput: true } : {},
           ...opts.allowSteering ? { drainSteering } : {}
-        });
+        }).finally(owner.settle);
         if (typeof result === "object" && result !== null && "status" in result && result.status === "aborted") {
           terminalStatus = "aborted";
         }
-        if (compaction && !controller.signal.aborted) {
+        if (sealForMaintenance() && compaction && !controller.signal.aborted) {
           if (compaction.consumePendingAction() === "compact") {
             await runCompaction();
           }
@@ -567,7 +797,7 @@ function createSessionController(deps) {
           terminalStatus = "aborted";
         }
         try {
-          const recovered = compaction ? compaction.messagesFromError(error) : null;
+          const recovered = sealForMaintenance() && compaction && !controller.signal.aborted ? compaction.messagesFromError(error) : null;
           if (recovered) {
             deps.agent.messages = recovered;
             await runCompaction();
@@ -583,67 +813,206 @@ function createSessionController(deps) {
         }
       }
     } finally {
+      owner.settle();
       opts.signal?.removeEventListener("abort", abortFromCaller);
-      const ownedTurn = finalizeTurn(
-        controller,
-        "Turn ended before pending interactions could be resolved."
-      );
-      if (activePolicyDenial !== void 0) {
+      const ownedExecution = executionOwner === owner && abortController === controller;
+      const policyDenial = ownedExecution ? activePolicyDenial : void 0;
+      let ownedTurn = false;
+      if (opts.enclosingExecution !== void 0) {
+        if (ownedExecution) {
+          sealExecution(owner);
+          executionOwner = opts.enclosingExecution;
+          abortController = opts.enclosingExecution.controller;
+          activeTurnId = opts.enclosingExecution.turnId;
+        }
+      } else if (ownedExecution) {
+        ownedTurn = finalizeTurn(
+          controller,
+          "Turn ended before pending interactions could be resolved."
+        );
+      }
+      if (controller.signal.aborted) terminalStatus = "aborted";
+      if (policyDenial !== void 0) {
         terminalStatus = "failed";
-        terminalMessage = activePolicyDenial;
+        terminalMessage = policyDenial;
       }
       if (opts.turnId !== void 0) {
         emit(
           {
             type: "turn-completed",
             status: terminalStatus,
-            ...activePolicyDenial !== void 0 ? { reason: "policy-denied" } : {},
+            ...policyDenial !== void 0 ? { reason: "policy-denied" } : {},
             ...terminalMessage !== void 0 ? { message: terminalMessage } : {}
           },
           opts.turnId
         );
       }
-      if (!opts.systemInitiated) activePolicyDenial = void 0;
-      activeTurnId = previousTurnId;
+      if (opts.enclosingExecution === void 0 && (executionOwner === owner || ownedTurn && executionOwner === null)) {
+        if (!opts.systemInitiated) activePolicyDenial = void 0;
+        activeTurnId = previousTurnId;
+      }
       if (ownedTurn) startNextQueuedSubmission();
     }
   }
   function startTrackedTurn(input, opts) {
-    let tracked;
-    tracked = runTurn(input, opts).finally(() => {
-      if (activeTurnPromise === tracked) activeTurnPromise = null;
+    let resolve;
+    let reject;
+    const tracked = new Promise((done, fail) => {
+      resolve = done;
+      reject = fail;
     });
     activeTurnPromise = tracked;
+    void runTurn(input, opts).then(resolve, reject).finally(() => {
+      if (activeTurnPromise === tracked) activeTurnPromise = null;
+    });
     return tracked;
   }
+  function observeAcceptedTurn(turn, turnId) {
+    void turn.catch((error) => {
+      emit({ type: "error", message: errorDetail(error) }, turnId);
+    });
+  }
   function detachController() {
     if (detached) return;
     detached = true;
     unsubscribeEvents();
     unsubscribeLoaded();
+    unsubscribeRecall();
     deps.channel.setToolDecider(null);
     deps.channel.setQuestionHandler(null);
     listeners.clear();
     abortListeners.clear();
   }
+  function cancelRecoveryOwner(owner) {
+    queue.length = 0;
+    const reason = new Error("User aborted the current turn.");
+    for (const listener of abortListeners) {
+      try {
+        listener(reason, "cancel");
+      } catch (error) {
+        owner.abortFailure = new AggregateError(
+          [
+            ...owner.abortFailure instanceof AggregateError ? owner.abortFailure.errors : [],
+            error
+          ],
+          "Interactive cancellation failed"
+        );
+      }
+    }
+    owner.controller.abort(reason);
+    rejectAllPending(reason.message);
+  }
+  function abort(intent = "cancel") {
+    const reason = new Error("User aborted the current turn.");
+    for (const listener of abortListeners) {
+      try {
+        listener(reason, intent);
+      } catch {
+      }
+    }
+    queue.length = 0;
+    abortController?.abort(reason);
+    rejectAllPending("User aborted the current turn.");
+  }
   return {
-    abort() {
-      queue.length = 0;
-      const reason = new Error("User aborted the current turn.");
-      for (const listener of abortListeners) {
-        try {
-          listener(reason);
-        } catch {
-        }
+    abortWithRecovery(request) {
+      request = structuredClone(request);
+      const known = request.target === null ? void 0 : recoveryResults.get(recoveryKey(request.target));
+      if (known) return known;
+      const owner = executionOwner;
+      if (request.target === null && (owner?.key == null || owner.phase === "finished")) {
+        abort();
+        return Promise.resolve({
+          status: "not-retracted",
+          target: null,
+          reason: "no-active-human"
+        });
+      }
+      if (!owner?.key || !request.target || !matchesIdentity(request.target) || recoveryKey(owner.key) !== recoveryKey(request.target)) {
+        return Promise.resolve({
+          status: "not-retracted",
+          target: request.target,
+          reason: "target-mismatch"
+        });
       }
-      abortController?.abort(reason);
-      rejectAllPending("User aborted the current turn.");
+      if (owner.phase !== "eligible") {
+        const result = Promise.resolve({
+          status: "not-retracted",
+          target: request.target,
+          reason: owner.phase === "finished" ? "already-finished" : "activity-started"
+        });
+        recoveryResults.set(recoveryKey(owner.key), result);
+        if (owner.phase === "activity-started") abort();
+        return result;
+      }
+      owner.phase = "recovering";
+      let resolve;
+      const pending = new Promise((done) => {
+        resolve = done;
+      });
+      recoveryResults.set(recoveryKey(owner.key), pending);
+      recoveryPromise = pending;
+      const persistenceAvailable = submissionRecovery !== void 0;
+      let work;
+      try {
+        if (!submissionRecovery) throw new Error("Submission recovery persistence is unavailable");
+        work = submissionRecovery.retract(
+          { key: owner.key, rawText: owner.rawText, executionId: owner.control.executionId },
+          owner.settled
+        );
+      } catch (error) {
+        work = Promise.reject(error);
+      }
+      cancelRecoveryOwner(owner);
+      const key = owner.key;
+      void work.then(
+        async () => {
+          await owner.settled;
+          const result = { status: "retracted", key, rawText: owner.rawText };
+          const removedMessageIds = state.messages.messages.filter((row) => row.role === "user" && row.submissionId === key.submissionId).map((row) => row.id);
+          emit({ type: "submission-retracted", result, removedMessageIds });
+          return result;
+        },
+        async (error) => {
+          await owner.settled.catch(() => {
+          });
+          return {
+            status: "failed",
+            target: key,
+            code: owner.abortFailure !== void 0 ? "abort-failed" : persistenceAvailable ? "persistence-failed" : "persistence-unavailable",
+            message: errorDetail(owner.abortFailure ?? error)
+          };
+        }
+      ).catch(
+        (error) => ({
+          status: "failed",
+          target: key,
+          code: owner.abortFailure !== void 0 ? "abort-failed" : "persistence-failed",
+          message: error instanceof Error ? error.message : "Recovery publication failed"
+        })
+      ).finally(() => {
+        owner.phase = "finished";
+        finalizeTurn(owner.controller, "Recovery ended.");
+        if (recoveryPromise === pending) recoveryPromise = null;
+        startNextQueuedSubmission();
+      }).then(
+        resolve,
+        (error) => resolve({
+          status: "failed",
+          target: key,
+          code: "persistence-failed",
+          message: error instanceof Error ? error.message : "Recovery finalization failed"
+        })
+      );
+      return pending;
     },
+    abort,
     onAbort(listener) {
       abortListeners.add(listener);
       return () => abortListeners.delete(listener);
     },
     attachHostHooks(hooks) {
+      if (hooks.submissionRecovery) submissionRecovery = hooks.submissionRecovery;
       if (hooks.compaction) compaction = hooks.compaction;
       if (hooks.guardPrompt) guardPrompt = hooks.guardPrompt;
     },
@@ -666,8 +1035,10 @@ function createSessionController(deps) {
     appendInfo(message) {
       emit({ type: "info", message });
     },
-    commitCompaction(messages) {
+    commitCompaction({ messages, recall }) {
+      copyRecallState(recall);
       queue.length = 0;
+      activeHumans.length = 0;
       rejectAllPending("Session compacted; pending interactions were cancelled.");
       alwaysApproved.clear();
       emit({
@@ -677,7 +1048,8 @@ function createSessionController(deps) {
           busy: abortController !== null || hostBusyCount > 0,
           meta: state.meta,
           mcp: state.mcp,
-          messages: createMessageStateFromMessages([...messages])
+          messages: createMessageStateFromMessages([...messages]),
+          recall
         }
       });
     },
@@ -690,12 +1062,13 @@ function createSessionController(deps) {
       rejectAllPending("Session closed.");
       if (shouldEmitTurnStatus) emitTurnStatus();
       const active = activeTurnPromise;
-      if (!active) {
+      const recovery = recoveryPromise;
+      if (!active && !recovery) {
         detachController();
         closePromise = Promise.resolve();
         return closePromise;
       }
-      closePromise = active.then(detachController, detachController);
+      closePromise = Promise.allSettled([active, recovery]).then(detachController);
       return closePromise;
     },
     dequeue(queuedId) {
@@ -821,12 +1194,27 @@ function createSessionController(deps) {
         emitTurnStatus();
       }
     },
-    echoUserMessage(text, attachmentLabels) {
+    reserveHumanSubmission(human) {
+      admitHuman("", { displayText: "", human });
+      const captured = structuredClone(human);
+      hostHumanReservations.add(captured);
+      return () => {
+        hostHumanReservations.delete(captured);
+      };
+    },
+    echoUserMessage(text, attachmentLabels, key) {
+      if (key !== void 0 && !matchesIdentity(key)) return false;
       emit({
         type: "user-message",
         text,
-        ...attachmentLabels?.length ? { attachmentLabels } : {}
+        ...key === void 0 ? {} : { submissionId: key.submissionId },
+        ...attachmentLabels?.length ? { attachmentLabels } : {},
+        // An echo emitted while a turn is in flight is a display-only
+        // interjection, never a turn opener — mark it like a drained steer so
+        // the WorkingStatusLine anchor and the persisted row both skip it.
+        ...abortController !== null || hostBusyCount > 0 ? { steeredAt: now() } : {}
       });
+      return true;
     },
     getSnapshot() {
       return { seq, state, serverCommands };
@@ -872,11 +1260,13 @@ function createSessionController(deps) {
     publishMcpState(mcpState) {
       emit({ type: "mcp-state", state: mcpState });
     },
-    reset(options = {}) {
+    reset(options) {
+      copyRecallState(options.recall);
       if (persistenceInFlight.size > 0) {
         return;
       }
       queue.length = 0;
+      activeHumans.length = 0;
       if (options.preserveHostBusy !== true) hostBusyCount = 0;
       abortController?.abort(new Error("Session reset."));
       rejectAllPending("Session reset; pending interactions were cancelled.");
@@ -886,6 +1276,7 @@ function createSessionController(deps) {
         type: "state-reset",
         state: {
           ...createSessionViewState(),
+          recall: options.recall,
           busy: hostBusyCount > 0,
           meta: state.meta,
           mcp: state.mcp
@@ -907,34 +1298,30 @@ function createSessionController(deps) {
     async submit(input, opts) {
       if (closing) throw new Error("Session is closing.");
       opts.signal?.throwIfAborted();
+      opts = admitHuman(input, opts);
       if (abortController || hostBusyCount > 0) {
         queue.push({
           id: `q-${++queueCounter}`,
           input,
           opts,
-          delivery: abortController !== null && opts.turnId === void 0 ? "steering" : "next-turn"
+          delivery: abortController !== null && executionOwner?.phase !== "recovering" && allowsSteering(opts) ? "steering" : "next-turn",
+          queuedAt: now()
         });
         emitTurnStatus();
         return;
       }
       const coordinatorOwned = opts.submission?.origin === "coordinator";
-      if (!coordinatorOwned && !opts.silent) {
-        emit(
-          {
-            type: "user-message",
-            text: opts.displayText,
-            ...opts.attachmentLabels?.length ? { attachmentLabels: opts.attachmentLabels } : {}
-          },
-          opts.turnId
-        );
-      }
-      await startTrackedTurn(input, {
+      const turn = startTrackedTurn(input, {
+        echo: coordinatorOwned || opts.silent ? void 0 : opts,
+        human: opts.human,
         turnId: opts.turnId,
-        allowSteering: opts.turnId === void 0,
+        allowSteering: allowsSteering(opts),
         submission: opts.submission ?? { origin: "user" },
         ...coordinatorOwned ? { coordinatorDisplayText: opts.displayText } : {},
         ...opts.signal === void 0 ? {} : { signal: opts.signal }
       });
+      if (opts.waitFor === "acceptance") observeAcceptedTurn(turn, opts.turnId);
+      else await turn;
     }
   };
 }