@sema-agent/core 1.451.0 → 1.452.0

package/dist/agents/observer.js

@@ -340,18 +340,21 @@ export function createObserverReportToolSpec(opts) {
                 return {
                     content: "ObserverReport is only available to an observer agent; the main session does not have an observed pairing.",
                     details: { success: false },
+                    isError: true,
                 };
             }
             if (pairing.state !== "armed") {
                 return {
                     content: "Your observer pairing is not armed (stopped, retired, or never installed). The report was not delivered.",
                     details: { success: false },
+                    isError: true,
                 };
             }
             if (!pairing.observedRunning) {
                 return {
                     content: `The observed agent (${pairing.observedEnvelopeName}) is not running. The report was not delivered.`,
                     details: { success: false },
+                    isError: true,
                 };
             }
             await opts.queueReport(frameObserverReport(pairing.observerAgentName, report));

package/dist/agents/subagent.js

@@ -650,6 +650,7 @@ function makeSubagentResume(deps) {
                     }
                 }
                 const stoppedByRevive = status === "killed" ? deps.registry?.getStopAttribution(deps.taskId ?? "") ?? "system" : undefined;
+                const completionIdRevive = deps.registry?.getCompletionId(deps.taskId ?? "");
                 const reviveName = deps.rowDescription ?? `sub-agent ${marker}`;
                 reviveEmit?.({
                     kind: "terminal",
@@ -664,6 +665,7 @@ function makeSubagentResume(deps) {
                     summary: `Agent "${reviveName}" (resumed) ${status === "killed" ? "stopped" : child.status === "completed" ? "finished" : String(child.status)}${ccElapsedTag(Date.now() - reviveStartedAt)}`,
                     resumable: status !== "killed",
                     usage: { tokens: child.stats.tokens, turns: child.stats.turns, costMicroUsd: child.stats.costMicroUsd },
+                    ...(completionIdRevive !== undefined ? { completionId: completionIdRevive } : {}),
                 });
                 const resumeFrame = {
                     task_id: deps.taskId ?? entry.childSessionId,
@@ -679,6 +681,7 @@ function makeSubagentResume(deps) {
                     ...resumeResidual(),
                     resumable: status !== "killed",
                     usage: { tokens: child.stats.tokens, turns: child.stats.turns, costMicroUsd: child.stats.costMicroUsd },
+                    ...(completionIdRevive !== undefined ? { completionId: completionIdRevive } : {}),
                 };
                 const gateOwner = status === "completed" && deps.notify !== undefined && deps.registry !== undefined && ledger.get(deps.parentToolCallId) === entry
                     ? entry.childSessionId
@@ -714,6 +717,7 @@ function makeSubagentResume(deps) {
                     }
                 }
                 const stoppedByReject = abort.signal.aborted ? deps.registry?.getStopAttribution(deps.taskId ?? "") ?? "system" : undefined;
+                const completionIdRejectRevive = deps.registry?.getCompletionId(deps.taskId ?? "");
                 const rejectName = deps.rowDescription ?? `sub-agent ${marker}`;
                 reviveEmit?.({
                     kind: "terminal",
@@ -726,6 +730,7 @@ function makeSubagentResume(deps) {
                     seq: entry.cycleSeq,
                     ...(stoppedByReject !== undefined ? { stoppedBy: stoppedByReject } : {}),
                     summary: `Agent "${rejectName}" (resumed) ${abort.signal.aborted ? "stopped" : "failed"}${ccElapsedTag(Date.now() - reviveStartedAt)}`.slice(0, 300),
+                    ...(completionIdRejectRevive !== undefined ? { completionId: completionIdRejectRevive } : {}),
                 });
                 try {
                     deps.notify?.({
@@ -737,6 +742,7 @@ function makeSubagentResume(deps) {
                         seq: entry.cycleSeq,
                         ...(stoppedByReject !== undefined ? { stoppedBy: stoppedByReject } : {}),
                         summary: `Agent "${rejectName}" (resumed) ${abort.signal.aborted ? "stopped" : `failed: ${e instanceof Error ? e.message : String(e)}`}${ccElapsedTag(Date.now() - reviveStartedAt)}`.slice(0, 300),
+                        ...(completionIdRejectRevive !== undefined ? { completionId: completionIdRejectRevive } : {}),
                     }, { priority: "later" });
                 }
                 catch {
@@ -1805,6 +1811,7 @@ function makeSubagentTool(opts, depth, excluded, extraToolsBudget) {
                             ...(!okBg ? { error: reapedBg ? BG_AGENT_REAP_STOP_ERROR : child.errorMessage ?? String(child.status) } : {}),
                         }) ?? (abort.signal.aborted ? "killed" : okBg ? "completed" : "failed");
                         const stoppedByBg = settledBg === "killed" ? bg.registry.getStopAttribution(taskId) ?? "system" : undefined;
+                        const completionIdFork = bg.registry.getCompletionId(taskId);
                         const stillbornFork = child.errorCode === "resume.session_not_found";
                         if (stillbornFork) {
                             try {
@@ -1829,6 +1836,7 @@ function makeSubagentTool(opts, depth, excluded, extraToolsBudget) {
                             ...residualFork,
                             resumable: resumableFork,
                             usage: { tokens: child.stats.tokens, turns: child.stats.turns, costMicroUsd: (child.stats.costMicroUsd ?? 0) + (child.stats.nested?.costMicroUsd ?? 0) },
+                            ...(completionIdFork !== undefined ? { completionId: completionIdFork } : {}),
                         });
                         try {
                             notify?.({
@@ -1844,6 +1852,7 @@ function makeSubagentTool(opts, depth, excluded, extraToolsBudget) {
                                 ...residualFork,
                                 resumable: resumableFork,
                                 usage: { tokens: child.stats.tokens, turns: child.stats.turns, costMicroUsd: (child.stats.costMicroUsd ?? 0) + (child.stats.nested?.costMicroUsd ?? 0) },
+                                ...(completionIdFork !== undefined ? { completionId: completionIdFork } : {}),
                             }, { priority: "later" });
                         }
                         catch {
@@ -1858,6 +1867,7 @@ function makeSubagentTool(opts, depth, excluded, extraToolsBudget) {
                             error: killed ? BG_AGENT_REAP_STOP_ERROR : e instanceof Error ? e.message : String(e),
                         }) ?? (killed ? "killed" : "failed");
                         const stoppedByBg = settledBg === "killed" ? bg.registry.getStopAttribution(taskId) ?? "system" : undefined;
+                        const completionIdForkReject = bg.registry.getCompletionId(taskId);
                         const summaryBg = `${shortDesc} — ${settledBg === "failed" ? `failed: ${e instanceof Error ? e.message : String(e)}` : settledBg}`.slice(0, 300);
                         sinkEmit({
                             kind: "terminal",
@@ -1869,6 +1879,7 @@ function makeSubagentTool(opts, depth, excluded, extraToolsBudget) {
                             status: settledBg,
                             ...(stoppedByBg !== undefined ? { stoppedBy: stoppedByBg } : {}),
                             summary: summaryBg,
+                            ...(completionIdForkReject !== undefined ? { completionId: completionIdForkReject } : {}),
                         });
                         try {
                             notify?.({
@@ -1879,6 +1890,7 @@ function makeSubagentTool(opts, depth, excluded, extraToolsBudget) {
                                 sessionId: forkedId,
                                 ...(stoppedByBg !== undefined ? { stoppedBy: stoppedByBg } : {}),
                                 summary: summaryBg,
+                                ...(completionIdForkReject !== undefined ? { completionId: completionIdForkReject } : {}),
                             }, { priority: "later" });
                         }
                         catch {
@@ -2390,6 +2402,7 @@ task_id: ${taskId}
                         }
                     }
                     const stoppedBy = settled === "killed" ? bg.registry.getStopAttribution(taskId) ?? "system" : undefined;
+                    const completionIdBg = bg.registry.getCompletionId(taskId);
                     const observerNote = observerNoteFor(await startBoundedObserverDrain());
                     const residual = residualFields();
                     const resumableBg = bgRetain !== undefined && settled !== "killed";
@@ -2406,6 +2419,7 @@ task_id: ${taskId}
                         ...residual,
                         resumable: resumableBg,
                         usage: { tokens: child.stats.tokens, turns: child.stats.turns, costMicroUsd: (child.stats.costMicroUsd ?? 0) + (child.stats.nested?.costMicroUsd ?? 0) },
+                        ...(completionIdBg !== undefined ? { completionId: completionIdBg } : {}),
                     });
                     const completionFrame = {
                         task_id: taskId,
@@ -2421,6 +2435,7 @@ task_id: ${taskId}
                         ...residual,
                         resumable: resumableBg,
                         usage: { tokens: child.stats.tokens, turns: child.stats.turns, costMicroUsd: (child.stats.costMicroUsd ?? 0) + (child.stats.nested?.costMicroUsd ?? 0) },
+                        ...(completionIdBg !== undefined ? { completionId: completionIdBg } : {}),
                     };
                     const gateOwner = settled === "completed" && notify !== undefined ? bgRetain?.childSessionId : undefined;
                     const aliveBgCount = gateOwner !== undefined ? bg.registry.countRunningBackgroundForOwner(gateOwner) : 0;
@@ -2465,6 +2480,7 @@ task_id: ${taskId}
                         }
                     }
                     const stoppedBy = settled === "killed" ? bg.registry.getStopAttribution(taskId) ?? "system" : undefined;
+                    const completionIdBgReject = bg.registry.getCompletionId(taskId);
                     const observerNote = observerNoteFor(await startBoundedObserverDrain());
                     sinkEmit({
                         kind: "terminal",
@@ -2477,6 +2493,7 @@ task_id: ${taskId}
                         ...(seqAtSettle !== undefined ? { seq: seqAtSettle } : {}),
                         ...(stoppedBy !== undefined ? { stoppedBy } : {}),
                         summary: `${settled === "failed" ? `Agent "${shortDesc}" failed: ${msg}${ccElapsedTag(Date.now() - bgStartedAt)}` : ccCompletionText(shortDesc, settled, settled, Date.now() - bgStartedAt)}${observerNote}`.slice(0, 300),
+                        ...(completionIdBgReject !== undefined ? { completionId: completionIdBgReject } : {}),
                     });
                     try {
                         notify?.({
@@ -2488,6 +2505,7 @@ task_id: ${taskId}
                             ...(seqAtSettle !== undefined ? { seq: seqAtSettle } : {}),
                             ...(stoppedBy !== undefined ? { stoppedBy } : {}),
                             summary: `${settled === "failed" ? `Agent "${shortDesc}" failed: ${msg}${ccElapsedTag(Date.now() - bgStartedAt)}` : ccCompletionText(shortDesc, settled, settled, Date.now() - bgStartedAt)}${observerNote}`.slice(0, 300),
+                            ...(completionIdBgReject !== undefined ? { completionId: completionIdBgReject } : {}),
                         }, { priority: "later" });
                     }
                     catch {
@@ -2736,15 +2754,15 @@ export function createSendMessageTool(opts) {
             const to = String(a.to ?? "").trim();
             const message = String(a.message ?? "").trim();
             if (!to)
-                return { content: "Message not sent: 'to' was empty. Pass the agent's task_id (a…).", details: { error: "empty to" } };
+                return { content: "Message not sent: 'to' was empty. Pass the agent's task_id (a…).", details: { error: "empty to" }, isError: true };
             if (!message)
-                return { content: "Message not sent: 'message' was empty.", details: { error: "empty message" } };
+                return { content: "Message not sent: 'message' was empty.", details: { error: "empty message" }, isError: true };
             const senderId = ctx.taskId ?? opts.owner;
             if (senderId !== undefined && isObserverTaskId(senderId)) {
-                return { content: OBSERVER_SENDMESSAGE_SENDER_REFUSAL, details: { error: "observer_sender" } };
+                return { content: OBSERVER_SENDMESSAGE_SENDER_REFUSAL, details: { error: "observer_sender" }, isError: true };
             }
             if (isObserverTaskId(to)) {
-                return { content: OBSERVER_SENDMESSAGE_TARGET_REFUSAL, details: { error: "observer_target", to } };
+                return { content: OBSERVER_SENDMESSAGE_TARGET_REFUSAL, details: { error: "observer_target", to }, isError: true };
             }
             if (normalizeAgentName(to) === "main") {
                 if (opts.uplink && senderId !== undefined) {
@@ -2761,7 +2779,7 @@ export function createSendMessageTool(opts) {
                         }, { priority: "next" });
                     }
                     catch (e) {
-                        return { content: `Message not sent: the parent's notification lane rejected it (${e instanceof Error ? e.message : String(e)}).`, details: { error: "uplink_failed", to } };
+                        return { content: `Message not sent: the parent's notification lane rejected it (${e instanceof Error ? e.message : String(e)}).`, details: { error: "uplink_failed", to }, isError: true };
                     }
                     return {
                         content: `Message sent to main — it will reach the spawning conversation at its next turn boundary. Continue with your task; do not wait for a reply.`,
@@ -2772,6 +2790,7 @@ export function createSendMessageTool(opts) {
                     content: `Message not sent: "main" (the spawning conversation) is not a deliverable target here. ` +
                         `Your completion is reported to it automatically — finish your task and your final report will be relayed.`,
                     details: { error: "main_not_deliverable", to },
+                    isError: true,
                 };
             }
             const access = {
@@ -2808,12 +2827,14 @@ export function createSendMessageTool(opts) {
                     return {
                         content: `Message not sent: ${whoT3} was stopped${row.stoppedBy !== undefined ? ` (by ${row.stoppedBy})` : ""} — a stopped agent is not revived. Launch a new agent with the needed context instead.`,
                         details: { error: "killed", to, ...(row.stoppedBy !== undefined ? { stoppedBy: row.stoppedBy } : {}) },
+                        isError: true,
                     };
                 }
                 if (row.status === "parked") {
                     return {
                         content: `Message not sent: ${whoT3} is parked on a pending approval — it resumes when the approval is decided (durable approval inbox), not by message delivery. Send again after it resumes.`,
                         details: { error: "parked_pending_approval", to },
+                        isError: true,
                     };
                 }
                 if (row.status === "running") {
@@ -2821,17 +2842,20 @@ export function createSendMessageTool(opts) {
                         return {
                             content: `Message not sent: ${whoT3} is currently running in this process but its mid-run delivery channel is not reachable from here. Wait for its completion notification, then send again to continue it.`,
                             details: { error: "still_running", to },
+                            isError: true,
                         };
                     }
                     if (Date.now() - row.updatedAt > 10 * DURABLE_AGENT_HEARTBEAT_MS) {
                         return {
                             content: `Message not sent: ${whoT3} last ran on another host that has stopped renewing its record (no heartbeat). Its row will be settled by the stale-row sweep — send again after that to revive it.`,
                             details: { error: "host_gone", to },
+                            isError: true,
                         };
                     }
                     return {
                         content: `Message not sent: ${whoT3} is running on another host — this process has no delivery channel to it. Wait for its completion notification, then send again to continue it.`,
                         details: { error: "running_elsewhere", to },
+                        isError: true,
                     };
                 }
                 if (row.sessionId === undefined)
@@ -2840,6 +2864,7 @@ export function createSendMessageTool(opts) {
                     return {
                         content: `Message not sent: ${whoT3} is being revived or recycled right now — send again in a moment.`,
                         details: { error: "claim_contended", to },
+                        isError: true,
                     };
                 }
                 try {
@@ -2873,11 +2898,13 @@ export function createSendMessageTool(opts) {
                             return {
                                 content: `Message not sent: ${whoT3} was just revived by another delivery — it is running now. Send again to reach the running agent.`,
                                 details: { error: "claim_lost", to },
+                                isError: true,
                             };
                         }
                         return {
                             content: `Message not sent: ${whoT3}'s durable record changed underneath this delivery — send again.`,
                             details: { error: "claim_lost", to },
+                            isError: true,
                         };
                     }
                     const claimedRev = row.rev + 1;
@@ -2897,11 +2924,13 @@ export function createSendMessageTool(opts) {
                             return {
                                 content: `Message not sent: ${whoT3}'s transcript session no longer exists (evicted or reaped) — it cannot be revived. Launch a new agent with the needed context instead.`,
                                 details: { error: "resume.session_not_found", to },
+                                isError: true,
                             };
                         }
                         return {
                             content: `Message not sent: ${whoT3}'s transcript store did not answer (${e instanceof Error ? e.message : String(e)}) — nothing was parked; send again.`,
                             details: { error: "session_store_unavailable", to },
+                            isError: true,
                         };
                     }
                     const clipped = message.length > UPLINK_RESULT_MAX ? `${message.slice(0, UPLINK_RESULT_MAX)}\n[message truncated: ${message.length} chars total]` : message;
@@ -2915,6 +2944,7 @@ export function createSendMessageTool(opts) {
                         return {
                             content: `Message not sent: the durable mailbox refused the message (${e instanceof Error ? e.message : String(e)}) — nothing was parked and the agent was not revived.`,
                             details: { error: "mailbox_failed", to },
+                            isError: true,
                         };
                     }
                     const leaseOwner = `${opts.registry.writerId}:${ctx.toolCallId}`;
@@ -2954,7 +2984,7 @@ export function createSendMessageTool(opts) {
                         };
                     }
                     try {
-                        await opts.mailbox.ack(scope, handle, lease.maxSeq);
+                        await opts.mailbox.ack(scope, handle, leaseOwner, lease.maxSeq);
                     }
                     catch {
                     }
@@ -2996,7 +3026,7 @@ export function createSendMessageTool(opts) {
                     }
                 }
                 if (byName.status === "ambiguous") {
-                    return { content: `Message not sent: ${byName.message}`, details: { error: "ambiguous", to } };
+                    return { content: `Message not sent: ${byName.message}`, details: { error: "ambiguous", to }, isError: true };
                 }
                 if (byName.status === "found") {
                     const h = byName.handle;
@@ -3019,6 +3049,7 @@ export function createSendMessageTool(opts) {
                             content: `Message not sent: "${to}" is on the durable roster (agent ${rosterHit.agentId}) but not reachable in this run — its session belongs to an earlier process. ` +
                                 `Launch a new agent with the needed context instead.`,
                             details: { error: "roster_only", to, agentId: rosterHit.agentId },
+                            isError: true,
                         };
                     }
                     const labels = opts.registry.runningBackgroundAgentLabels(access);
@@ -3028,16 +3059,17 @@ export function createSendMessageTool(opts) {
                             (labels.length > 0 ? ` Running background agents: ${labels.join(", ")}.` : "") +
                             ` Note: a completed foreground agent is not resumable (its transcript is not retained) — spawn with run_in_background to keep an agent addressable, or launch a new agent.`,
                         details: { error: "not_found", to, ...(byName.suggestion !== undefined ? { suggestion: byName.suggestion } : {}) },
+                        isError: true,
                     };
                 }
             }
             const row = target;
             if (row === undefined)
-                return { content: `Message not sent: no agent named "${to}" is reachable.`, details: { error: "not_found", to } };
+                return { content: `Message not sent: no agent named "${to}" is reachable.`, details: { error: "not_found", to }, isError: true };
             const targetId = row.task_id;
             const who = targetId === to ? `agent ${targetId}` : `agent "${to}" (${targetId})`;
             if (row.type !== "background_agent") {
-                return { content: `Message not sent: ${targetId} is a ${row.type} task, not a background agent.`, details: { error: "wrong_type", to } };
+                return { content: `Message not sent: ${targetId} is a ${row.type} task, not a background agent.`, details: { error: "wrong_type", to }, isError: true };
             }
             if (row.status === "running" || row.status === "pending") {
                 const s2Summary = typeof a.summary === "string" && a.summary.trim() !== "" ? a.summary.trim().slice(0, 200) : undefined;
@@ -3066,11 +3098,13 @@ export function createSendMessageTool(opts) {
                     return {
                         content: `Message not sent: ${who} is still running and this deployment has no mid-run delivery channel for it. Wait for its completion notification, then SendMessage to continue it.`,
                         details: { error: "still_running", to },
+                        isError: true,
                     };
                 }
                 return {
                     content: `Message not sent: ${who} just finished (delivery raced its completion). Send again to continue it from its transcript.`,
                     details: { error: "settle_race", to },
+                    isError: true,
                 };
             }
             if (row.status === "killed") {
@@ -3078,6 +3112,7 @@ export function createSendMessageTool(opts) {
                 return {
                     content: `Message not sent: ${who} was stopped${by ? ` (by ${by})` : ""} — a stopped agent is not resumable. Launch a new agent with the needed context instead.`,
                     details: { error: "killed", to, ...(by !== undefined ? { stoppedBy: by } : {}) },
+                    isError: true,
                 };
             }
             const runLedger = ctx.subagentRetain ?? opts.retain;
@@ -3096,6 +3131,7 @@ export function createSendMessageTool(opts) {
                 return {
                     content: `Message not sent: ${who}'s session was not retained (this run did not enable retainSubagentSessions), so it cannot be continued — relaunch a new agent with the needed context instead.`,
                     details: { error: "not_retained", to },
+                    isError: true,
                 };
             }
             const resume = makeSubagentResume({
@@ -3144,7 +3180,7 @@ export function createSendMessageTool(opts) {
                                     : code === "resume.row_gone"
                                         ? `${who}'s registry row no longer exists (terminal GC) — relaunch a new agent instead.`
                                         : `${e instanceof Error ? e.message : String(e)}`;
-                return { content: `Message not sent: ${text}`, details: { error: code ?? "resume_failed", to } };
+                return { content: `Message not sent: ${text}`, details: { error: code ?? "resume_failed", to }, isError: true };
             }
         },
     });
@@ -3169,7 +3205,7 @@ export function createAgentTranscriptTool(opts) {
             const a = args;
             const id = String(a.id ?? "").trim();
             if (!id)
-                return { content: "No transcript read: 'id' was empty. Pass the agent's task_id (a…).", details: { error: "empty id" } };
+                return { content: "No transcript read: 'id' was empty. Pass the agent's task_id (a…).", details: { error: "empty id" }, isError: true };
             const lastN = typeof a.lastN === "number" && Number.isFinite(a.lastN) ? Math.max(1, Math.min(AGENT_TRANSCRIPT_MAX_N, Math.floor(a.lastN))) : AGENT_TRANSCRIPT_DEFAULT_N;
             const access = {
                 owner: ctx.taskId ?? opts.owner,
@@ -3214,12 +3250,13 @@ export function createAgentTranscriptTool(opts) {
                     return {
                         content: `No transcript: "${id}" is a WORKFLOW run id — AgentTranscript reads sub-agent transcripts only. For the run's per-agent rows (which agent failed, why, elapsed) call TaskOutput({ task_id: "${id}" }); to continue a fixed script, re-invoke the workflow with resumeFromRunId: "${id}".`,
                         details: { error: "workflow_id", id },
+                        isError: true,
                     };
                 }
                 const durable = await readDurableSteps();
                 if (durable)
                     return durable;
-                return { content: `No transcript: no background agent task "${id}" (unknown id, not yours, or expired).`, details: { error: "not_found", id } };
+                return { content: `No transcript: no background agent task "${id}" (unknown id, not yours, or expired).`, details: { error: "not_found", id }, isError: true };
             }
             const runLedger = ctx.subagentRetain ?? undefined;
             const atLedgerSessionId = ctx.sessionId ?? opts.sessionId;
@@ -3232,6 +3269,7 @@ export function createAgentTranscriptTool(opts) {
                 return {
                     content: `No transcript: agent ${id}'s session was not retained (this run did not enable retainSubagentSessions), so its history is unavailable. Its completion notification carried the recent steps.`,
                     details: { error: "not_retained", id },
+                    isError: true,
                 };
             }
             let steps;
@@ -3246,6 +3284,7 @@ export function createAgentTranscriptTool(opts) {
                 return {
                     content: `No transcript: agent ${id}'s session could not be read (${code ?? (e instanceof Error ? e.message : String(e))}).`,
                     details: { error: code ?? "read_failed", id },
+                    isError: true,
                 };
             }
             if (steps.length === 0) {

package/dist/core/ask-question.js

@@ -1,5 +1,5 @@
 import { Type } from "typebox";
-import { defineTool } from "./tools.js";
+import { defineTool, errorResult } from "./tools.js";
 import { delimitUntrusted, inlineUntrusted } from "./untrusted-text.js";
 export const ASK_USER_QUESTION_TOOL_NAME = "AskUserQuestion";
 const NO_HUMAN = "No human is available to answer right now. Proceed with your best judgment: pick the most reasonable " +
@@ -66,23 +66,23 @@ export function createAskUserQuestionTool(onQuestion, source) {
         execute: async (args, ctx) => {
             const { questions } = args;
             if (!Array.isArray(questions) || questions.length < 1 || questions.length > 4) {
-                return "Error (AskUserQuestion): provide between 1 and 4 questions.";
+                return errorResult("Error (AskUserQuestion): provide between 1 and 4 questions.");
             }
             const seenHeaders = new Set();
             for (const q of questions) {
                 if (!Array.isArray(q.options) || q.options.length < 2 || q.options.length > 4) {
-                    return `Error (AskUserQuestion): the question "${q.header || q.question}" must have between 2 and 4 options.`;
+                    return errorResult(`Error (AskUserQuestion): the question "${q.header || q.question}" must have between 2 and 4 options.`);
                 }
                 const key = typeof q.header === "string" ? q.header.trim() : "";
                 if (key === "" || seenHeaders.has(key)) {
-                    return `Error (AskUserQuestion): each question needs a distinct, non-empty header (got a duplicate or empty one).`;
+                    return errorResult(`Error (AskUserQuestion): each question needs a distinct, non-empty header (got a duplicate or empty one).`);
                 }
                 seenHeaders.add(key);
                 const seenLabels = new Set();
                 for (const o of q.options) {
                     const labelKey = typeof o?.label === "string" ? o.label.trim() : "";
                     if (seenLabels.has(labelKey)) {
-                        return `Error (AskUserQuestion): the question "${q.header || q.question}" has duplicate option labels — option labels must be unique within each question.`;
+                        return errorResult(`Error (AskUserQuestion): the question "${q.header || q.question}" has duplicate option labels — option labels must be unique within each question.`);
                     }
                     seenLabels.add(labelKey);
                 }

package/dist/core/background-agent-store.d.ts

@@ -28,6 +28,7 @@ export interface BackgroundAgentRecord {
     settledAt?: number;
     status: "running" | "parked" | "completed" | "failed" | "killed";
     stoppedBy?: string;
+    completionId?: string;
     seq?: number;
     parkedCheckpointToken?: string;
     parkedAt?: number;
@@ -66,6 +67,7 @@ export declare function canAccessAgentRecord(record: Pick<BackgroundAgentRecord,
     scope?: string;
     sessionId?: string;
 }): boolean;
+export declare const STALE_RUNNING_REAP_ATTRIBUTION = "the host process was interrupted while this agent was running \u2014 its in-process state was lost. Check its worktree / output file for partial work before assuming the task landed (stale running row reaped).";
 export interface BackgroundAgentStore {
     put(record: BackgroundAgentRecord): Promise<void>;
     get(handle: string, scope: string): Promise<BackgroundAgentRecord | null>;

package/dist/core/background-agent-store.js

@@ -1,3 +1,4 @@
+import { uuidv7 } from "../internal/harness.js";
 export class BackgroundAgentStoreError extends Error {
     code;
     constructor(code, message) {
@@ -20,6 +21,7 @@ export function canAccessAgentRecord(record, access) {
     }
     return false;
 }
+export const STALE_RUNNING_REAP_ATTRIBUTION = "the host process was interrupted while this agent was running — its in-process state was lost. Check its worktree / output file for partial work before assuming the task landed (stale running row reaped).";
 export async function reconcileParkedAgents(stores, scope, now, opts) {
     const out = { failed: 0, rolledBack: 0 };
     const excluded = (row) => (opts?.excludeHandles?.has(row.handle) ?? false) ||
@@ -31,6 +33,7 @@ export async function reconcileParkedAgents(stores, scope, now, opts) {
         next.stoppedBy = "system";
         next.settledAt = now;
         next.updatedAt = now;
+        next.completionId ??= uuidv7();
         delete next.parkedCheckpointToken;
         delete next.parkClaimId;
         delete next.parkedAt;
@@ -248,7 +251,8 @@ export class InMemoryBackgroundAgentStore {
                 const flipped = structuredClone(r);
                 flipped.status = "failed";
                 flipped.stoppedBy = "system";
-                flipped.summary = flipped.summary ?? "host process interrupted (stale running row reaped)";
+                flipped.summary = flipped.summary ?? STALE_RUNNING_REAP_ATTRIBUTION;
+                flipped.error = flipped.error ?? STALE_RUNNING_REAP_ATTRIBUTION;
                 flipped.settledAt = now;
                 flipped.updatedAt = now;
                 flipped.rev = r.rev + 1;

package/dist/core/exec-output-tail.d.ts

@@ -1,9 +1,11 @@
+import { StringDecoder } from "node:string_decoder";
 export declare const MAX_EXEC_OUTPUT_BYTES: number;
 export declare class RollingTailBuffer {
     private readonly maxBytes;
     private readonly chunks;
     private size;
-    private dropped;
+    private headDropped;
+    private sourceSkipped;
     constructor(maxBytes?: number);
     push(chunk: Buffer): void;
     recordSkippedBytes(n: number): void;
@@ -11,5 +13,20 @@ export declare class RollingTailBuffer {
         text: string;
         droppedBytes: number;
     };
+    bytes(): Buffer;
+    headDroppedBytes(): number;
+    sourceSkippedBytes(): number;
 }
+export interface StreamCursorState {
+    tail: RollingTailBuffer;
+    cursorBytes: number;
+    acceptedBytes: number;
+    disclosedSkippedBytes: number;
+    decoder: StringDecoder;
+}
+export declare function newStreamCursorState(tail?: RollingTailBuffer): StreamCursorState;
+export declare function sliceStreamIncrement(s: StreamCursorState, terminal: boolean): {
+    inc: string;
+    droppedBeforeCursor: number;
+};
 export declare function markTruncated(text: string, droppedBytes: number): string;

package/dist/core/exec-output-tail.js

@@ -1,9 +1,11 @@
+import { StringDecoder } from "node:string_decoder";
 export const MAX_EXEC_OUTPUT_BYTES = 8 * 1024 * 1024;
 export class RollingTailBuffer {
     maxBytes;
     chunks = [];
     size = 0;
-    dropped = 0;
+    headDropped = 0;
+    sourceSkipped = 0;
     constructor(maxBytes = MAX_EXEC_OUTPUT_BYTES) {
         this.maxBytes = maxBytes;
     }
@@ -18,22 +20,53 @@ export class RollingTailBuffer {
             if (over >= head.length) {
                 this.chunks.shift();
                 this.size -= head.length;
-                this.dropped += head.length;
+                this.headDropped += head.length;
             }
             else {
                 this.chunks[0] = head.subarray(over);
                 this.size -= over;
-                this.dropped += over;
+                this.headDropped += over;
             }
         }
     }
     recordSkippedBytes(n) {
         if (n > 0)
-            this.dropped += n;
+            this.sourceSkipped += n;
     }
     result() {
-        return { text: Buffer.concat(this.chunks).toString("utf8"), droppedBytes: this.dropped };
+        return { text: Buffer.concat(this.chunks).toString("utf8"), droppedBytes: this.headDropped + this.sourceSkipped };
     }
+    bytes() {
+        return Buffer.concat(this.chunks);
+    }
+    headDroppedBytes() {
+        return this.headDropped;
+    }
+    sourceSkippedBytes() {
+        return this.sourceSkipped;
+    }
+}
+export function newStreamCursorState(tail = new RollingTailBuffer()) {
+    return { tail, cursorBytes: 0, acceptedBytes: 0, disclosedSkippedBytes: 0, decoder: new StringDecoder("utf8") };
+}
+export function sliceStreamIncrement(s, terminal) {
+    const headDropped = s.tail.headDroppedBytes();
+    const sourceSkipped = s.tail.sourceSkippedBytes();
+    const newSkipped = Math.max(0, sourceSkipped - s.disclosedSkippedBytes);
+    s.disclosedSkippedBytes = sourceSkipped;
+    const droppedBeforeCursor = Math.max(0, headDropped - s.cursorBytes) + newSkipped;
+    const buf = s.tail.bytes();
+    const startInTail = Math.min(Math.max(s.cursorBytes, headDropped) - headDropped, buf.length);
+    const incBuf = startInTail <= 0 ? buf : buf.subarray(startInTail);
+    if (droppedBeforeCursor > 0)
+        s.decoder = new StringDecoder("utf8");
+    let inc = s.decoder.write(incBuf);
+    if (terminal) {
+        inc += s.decoder.end();
+        s.decoder = new StringDecoder("utf8");
+    }
+    s.cursorBytes = s.acceptedBytes;
+    return { inc, droppedBeforeCursor };
 }
 export function markTruncated(text, droppedBytes) {
     return droppedBytes > 0

package/dist/core/lsp-session.d.ts

@@ -18,6 +18,7 @@ export declare class TransportLspSession implements LspSession {
     request(op: LspOperation, params: LspRequestParams, signal?: AbortSignal): Promise<LspResult>;
     private syncOpenedFiles;
     private syncOne;
+    private static classifyUnbranded;
     get closed(): boolean;
     openedFiles(): string[];
     warmOpen(filePaths: string[], signal?: AbortSignal): Promise<void>;