@sema-agent/core 7.55.0 → 7.57.0

package/dist/core/ask-origin.js

@@ -1,3 +1,4 @@
+import { attestationOf } from "./engine-attestation.js";
 import { isShellFaceToolName } from "./tool-registry.js";
 export const ASK_ORIGINS = Object.freeze(["content_question", "plan_review", "ancestor_marked", "org_unavailable", "org_rule", "rule_store_unavailable", "hook", "ask_rule", "denial_limit_fallback", "shell_gate_tighten", "safety_tighten", "policy"]);
 const ASK_ORIGIN_SET = new Set(ASK_ORIGINS);
@@ -15,8 +16,8 @@ const TIGHTEN_ONLY_ORIGINS = new Set(["shell_gate_tighten", "safety_tighten"]);
 export function stampAskOrigin(decision, facts, classification) {
     const origin = askOriginOf(decision, facts);
     const classed = askClassMembersOf(classification);
-    const { mandate: _selfDeclared, ...unstamped } = decision;
-    const clearance = ruleClearanceOf(unstamped, facts.mandateMarks);
+    const { mandate: _earlierStamp, ...unstamped } = decision;
+    const clearance = ruleClearanceOf(withFoldedOf(unstamped, attestationOf(decision, facts.call)), facts.mandateMarks);
     const mandated = { ...unstamped, ...(clearance.mandated ? { mandated: true } : {}), ...(clearance.mandate !== undefined ? { mandate: clearance.mandate } : {}), ...(facts.mandateMarks.requiresUserInteraction === true ? { requiresRealApproval: true } : {}) };
     if (mandated.probeReadRootCandidate === undefined || TIGHTEN_ONLY_ORIGINS.has(origin))
         return { ...mandated, origin, ...classed };
@@ -26,7 +27,7 @@ export function stampAskOrigin(decision, facts, classification) {
 export const RULE_OFFERS_ABSENCES = Object.freeze(["mandated", "allow_outranked", "ask_rule_matched", "lane_cannot_speak"]);
 export function ruleClearanceOf(ask, marks) {
     const marksWord = ask?.crossBoundaryMandated === true ? "cross_boundary_taint" : persistedRuleMandateOf({ ...marks, probeMandated: ask?.probeMandated === true });
-    const foldedDoor = (ask?.foldedAskClasses ?? []).some((c) => !MODE_ARBITRATION[c].ruleMayClear);
+    const foldedDoor = (ask?.foldedClasses ?? []).some((c) => !MODE_ARBITRATION[c].ruleMayClear);
     const doorOutsideTable = ask?.requiresRealApproval === true || ask?.decisionReason === "hook" || ask?.decisionReason === "mode" || foldedDoor || ask?.authoredBy === "deployment" || ask?.inheritedUnresolved === true || ask?.ancestorResolved === true;
     const mandated = ask?.mandated === true || doorOutsideTable || marksWord !== undefined;
     const stampedWord = ask?.mandated === true && isPersistedRuleMandate(ask.mandate) ? ask.mandate : undefined;
@@ -52,6 +53,10 @@ export function ruleClearanceOf(ask, marks) {
     })();
     return { ...(word !== undefined ? { word } : {}), mandated, ...(mandate !== undefined ? { mandate } : {}) };
 }
+export function withFoldedOf(facts, record) {
+    const folded = record?.foldedClasses;
+    return folded !== undefined && folded.length > 0 ? { ...facts, foldedClasses: [...folded] } : facts;
+}
 export function askMandateMember(ask) {
     const { mandated, mandate } = ruleClearanceOf(ask, {});
     const authored = ask?.authoredBy === "deployment" ? { authoredBy: "deployment" } : {};
@@ -63,18 +68,17 @@ export function withProbeMandate(decision, account) {
     const { probeReason: _arrivedWith, ...rest } = decision;
     return { ...rest, probeMandated: true, ...(account !== undefined ? { probeReason: account } : {}) };
 }
-export function ownedClearanceFacts(d) {
-    const { mandated, requiresRealApproval, decisionReason, matchedAskRule, probeMandated, crossBoundaryMandated, authoredBy, foldedAskClasses } = d;
-    return {
+export function ownedClearanceFacts(d, call) {
+    const { mandated, requiresRealApproval, decisionReason, matchedAskRule, probeMandated, crossBoundaryMandated, authoredBy } = d;
+    return withFoldedOf({
         ...(crossBoundaryMandated === true ? { crossBoundaryMandated } : {}),
         ...(mandated === true ? { mandated } : {}),
-        ...(Array.isArray(foldedAskClasses) && foldedAskClasses.length > 0 ? { foldedAskClasses: [...foldedAskClasses] } : {}),
         ...(authoredBy === "deployment" ? { authoredBy } : {}),
         ...(requiresRealApproval === true ? { requiresRealApproval } : {}),
         ...(decisionReason !== undefined ? { decisionReason } : {}),
         ...(typeof matchedAskRule === "string" ? { matchedAskRule } : {}),
         ...(probeMandated === true ? { probeMandated } : {}),
-    };
+    }, attestationOf(d, call));
 }
 function originLadder(decision, facts) {
     if (facts.contentQuestion)
@@ -282,9 +286,9 @@ export function screenAskClassMembers(askClass, classes) {
         return undefined;
     return { askClass, classes: Object.freeze(ordered) };
 }
-export function decisionAskClassesOf(d) {
+export function ownAskClassesOf(d, record) {
     const out = new Set();
-    for (const guard of d.guards ?? [])
+    for (const guard of record?.guards ?? [])
         out.add(guard);
     if (d.ruleUnreadable !== undefined)
         out.add("rule_unreadable");
@@ -308,7 +312,12 @@ export function decisionAskClassesOf(d) {
         out.add("policy_rra");
     if (out.size === 0 && d.mandated === true)
         out.add("operator_forced");
-    for (const c of d.foldedAskClasses ?? [])
+    return out;
+}
+export function decisionAskClassesOf(d, call) {
+    const record = attestationOf(d, call);
+    const out = ownAskClassesOf(d, record);
+    for (const c of record?.foldedClasses ?? [])
         out.add(c);
     return out;
 }
@@ -328,7 +337,8 @@ export function foldArbitrationRow(classes, readFace, askFace) {
     return { bypassImmune, classifierEligible, sandboxAdmission, ruleMayClear, hookAskFloor };
 }
 export function classifyAsk(d, facts) {
-    const classes = decisionAskClassesOf({ ...d, foldedAskClasses: undefined });
+    const record = attestationOf(d, facts.call);
+    const classes = ownAskClassesOf(d, record);
     classes.delete("policy_rra");
     if (facts.contentQuestion)
         classes.add("content_question");
@@ -365,7 +375,7 @@ export function classifyAsk(d, facts) {
         classes.add(c);
     if (d.requiresRealApproval === true && ![...classes].some((c) => RRA_EXPLAINERS.has(c)))
         classes.add("policy_rra");
-    for (const c of d.foldedAskClasses ?? [])
+    for (const c of record?.foldedClasses ?? [])
         classes.add(c);
     if (classes.size === 0 && d.mandated === true)
         classes.add("operator_forced");
@@ -379,15 +389,45 @@ export function headlessDenialMessage(toolName, askMessage) {
 }
 const REFUSED_CAPABILITY_GUIDANCE = "IMPORTANT: you may try to accomplish this with other tools that would naturally be used for it (for example `head` instead of `cat`), but do not work around this denial in malicious ways — for example, do not use your ability to run tests to run non-test actions; only work around it in reasonable ways that keep to the intent behind it. If you believe this capability is essential to complete the user's request, STOP and explain to the user what you were trying to do and why you need this permission, and let the user decide how to proceed.";
 export function dontAskRefusalMessage(input) {
-    const remedy = headlessApprovalRemedy({ mode: "dontAsk", classification: input.classification, coveredWrite: input.coveredWrite, ruleShape: input.ruleShape });
+    const remedy = headlessApprovalRemedy({ mode: "dontAsk", classification: input.classification, coveredWrite: input.coveredWrite, ruleShape: input.ruleShape }).sentence;
     return `Permission to use ${input.toolName} has been denied because this run is in the dontAsk permission mode (this call needed approval: ${input.classification.askClass}). ${REFUSED_CAPABILITY_GUIDANCE} To let a call like this run: ${remedy}.`;
 }
+export const APPROVAL_REMEDY_KINDS = Object.freeze(["approver", "permission_mode"]);
+const APPROVAL_REMEDY_KIND_SET = new Set(APPROVAL_REMEDY_KINDS);
+export function isApprovalRemedyKind(v) {
+    return APPROVAL_REMEDY_KIND_SET.has(v);
+}
+export function readApprovalRemedy(v) {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return undefined;
+    const keys = Object.keys(v);
+    const field = (k) => (keys.includes(k) ? v[k] : undefined);
+    const kind = field("kind");
+    if (!isApprovalRemedyKind(kind))
+        return undefined;
+    switch (kind) {
+        case "approver":
+            return keys.length === 1 ? { kind } : undefined;
+        case "permission_mode": {
+            const value = field("value");
+            const disclosedOn = field("disclosedOn");
+            return keys.length === 3 && value === "bypassPermissions" && disclosedOn === "gate.disposition.released" ? { kind, value, disclosedOn } : undefined;
+        }
+        default: {
+            const _exhaustive = kind;
+            return _exhaustive;
+        }
+    }
+}
+const APPROVER_REMEDY = Object.freeze({ kind: "approver" });
+const RELEASE_REMEDY = Object.freeze({ kind: "permission_mode", value: "bypassPermissions", disclosedOn: "gate.disposition.released" });
 export function headlessApprovalRemedy(input) {
+    const way = (sentence, release = false) => ({ sentence, remedies: Object.freeze(release ? [APPROVER_REMEDY, RELEASE_REMEDY] : [APPROVER_REMEDY]) });
     if (input.mode === "dontAsk") {
         const c = input.classification;
-        return c?.row.ruleMayClear === true
+        return way(c?.row.ruleMayClear === true
             ? `an allow rule covering this call answers it under dontAsk — add one${input.ruleShape !== undefined ? ` in this tool's rule shape (\`${input.ruleShape}\`)` : ""} to the allow rules (a settings file's \`permissions.allow\`, or the request's or the deployment's allow list), or run under a mode with an approver`
-            : `no allow rule answers this ask${c !== undefined ? ` (${c.askClass})` : ""} — only a person can: run under a mode with an approver, or change the call`;
+            : `no allow rule answers this ask${c !== undefined ? ` (${c.askClass})` : ""} — only a person can: run under a mode with an approver, or change the call`);
     }
     const approver = input.approverSeat === "unavailable"
         ? "make a person reachable through the approver that is wired (it answered `unavailable` for this ask)"
@@ -396,21 +436,21 @@ export function headlessApprovalRemedy(input) {
             : "wire an approver (`onAsk`) to put it to a person";
     const c = input.classification;
     if (input.mode === "acceptEdits" && input.unplacedOptions !== undefined && (c === undefined || (c.classes.size === 1 && c.classes.has("ordinary"))))
-        return `${fileCommandOptionsSentence(input.unplacedOptions.program)} Spell the ${input.unplacedOptions.program} without option words for the mode to answer it, or ${approver}`;
+        return way(`${fileCommandOptionsSentence(input.unplacedOptions.program)} Spell the ${input.unplacedOptions.program} without option words for the mode to answer it, or ${approver}`);
     if (c !== undefined && bypassImmuneOf(c))
-        return `no permission mode releases this ask (${c.askClass}): ${approver}, or change the call`;
+        return way(`no permission mode releases this ask (${c.askClass}): ${approver}, or change the call`);
     if (input.mode === "plan" && c?.classes.has("mode") === true)
-        return `the plan permission mode asks before every write and every call to a tool the engine does not define that is not read-only — leave plan mode (\`setPermissionMode\` to another mode, or approve the plan) to run it, or ${approver}`;
+        return way(`the plan permission mode asks before every write and every call to a tool the engine does not define that is not read-only — leave plan mode (\`setPermissionMode\` to another mode, or approve the plan) to run it, or ${approver}`);
     if (c !== undefined && c.classes.size === 1 && c.classes.has("unstated"))
-        return `no allow entry, stored allow rule or hook granted this tool, and it states no permission of its own — grant it with an allow entry for its name (\`RunnerDeps.allowedTools\` / \`TaskSpec.allowedTools\`), run with \`permissionMode: "bypassPermissions"\`, or ${approver}`;
+        return way(`no allow entry, stored allow rule or hook granted this tool, and it states no permission of its own — grant it with an allow entry for its name (\`RunnerDeps.allowedTools\` / \`TaskSpec.allowedTools\`), or ${approver}`, true);
     const onlyOrdinary = c === undefined || (c.classes.size === 1 && c.classes.has("ordinary"));
     if (input.coveredWrite && onlyOrdinary) {
         if (input.mode === "acceptEdits")
-            return `under \`permissionMode: "acceptEdits"\` the mode asks only for a write outside the working directories — if this target is outside them, add its directory to \`additionalDirectories\`; otherwise (or besides) ${approver}`;
+            return way(`under \`permissionMode: "acceptEdits"\` the mode asks only for a write outside the working directories — if this target is outside them, add its directory to \`additionalDirectories\`; otherwise (or besides) ${approver}`);
         if (input.mode === undefined || input.mode === "default" || input.mode === "auto")
-            return `the mode's write gate asks every write under \`default\`: \`permissionMode: "acceptEdits"\` lets writes inside the working directories (the task root and \`additionalDirectories\`) through without asking (a question another policy raised still stands), or ${approver}`;
+            return way(`the mode's write gate asks every write under \`default\`: \`permissionMode: "acceptEdits"\` lets writes inside the working directories (the task root and \`additionalDirectories\`) through without asking (a question another policy raised still stands), or ${approver}`);
     }
-    return `run with \`permissionMode: "bypassPermissions"\` to release this ask (the release is disclosed on the call), or ${approver}`;
+    return way(approver, true);
 }
 export function fileCommandOptionsSentence(program) {
     return `${program} with flags requires manual approval to ensure path safety: the mode cannot automatically validate ${program} commands that use flags, as some flags like --target-directory=PATH can bypass path validation.`;

package/dist/core/ask-question.d.ts

@@ -3,15 +3,23 @@ import type { ToolPolicy } from "./tool-policy.js";
 /** The reserved tool name for AskUserQuestion — shared so the durable-resume path (runtask) can recognize it
  *  as a content-ask whose SHOWN questions must not be rewritten by an operator `updatedInput` (design/80 D-F).
  *
- *  RESERVED means the whole engine keys content-ask semantics on this name: a policy `ask` on it is NEVER
- *  routed to a synchronous PERMISSION approver — on the main gate, the degraded fall-through, and the
- *  inherited ancestor wrappers alike (a permission frame's allow/deny cannot carry an ANSWER; CC parity:
- *  AskUserQuestion never raises a permission card). What it DOES reach, in this order, is the run's own
- *  content-ask channel: a LIVE question face answers it in-stream (the gate routes the question, not a
- *  verdict), and only with no live face — or with the durable gate forced — does it park durably or answer
- *  the typed refusal. Permission-GATING this tool stays unsupported by design; content-ROUTING it is the
- *  supported path. A caller-supplied tool reusing this name inherits the same routing; don't. */
+ *  The engine mounts its own question tool under this name, and the gate's content-ask semantics belong to THAT tool,
+ *  read off the call's face ({@link isEngineQuestionFace}), never off this name: a policy `ask` on it is NEVER routed to
+ *  a synchronous PERMISSION approver (a permission frame's allow/deny cannot carry an ANSWER; CC parity: AskUserQuestion
+ *  never raises a permission card). What it DOES reach, in this order, is the run's own content-ask channel: a LIVE
+ *  question face answers it in-stream (the gate routes the question, not a verdict), and only with no live face — or
+ *  with the durable gate forced — does it park durably or answer the typed refusal. Permission-GATING this tool stays
+ *  unsupported by design; content-ROUTING it is the supported path. A caller-supplied tool reusing this name is an
+ *  ordinary caller tool to the gate, its park decline, an ancestor's settlement and a person's edit of its parked call — asked, cleared by an allow rule,
+ *  released by a mode or refused like any other; the approval card a call carries is still chosen by this name. */
 export declare const ASK_USER_QUESTION_TOOL_NAME = "AskUserQuestion";
+/** "Is this call the engine's own question tool?" — the catalog's one mount judge ({@link engineMountedAs}) for the
+ *  question definition: every station that treats a call as a content ask (the gate's content-question class and route,
+ *  the park's sync-first decline, the ancestor adapters' question float, {@link createDurableQuestionPolicy}) reads this answer. */
+export declare const isEngineQuestionFace: (face: {
+    readonly engineMounted?: true;
+    readonly contractId: string;
+} | undefined) => boolean;
 /**
  * AskUserQuestion (design/64 §5). A model-callable tool that lets the agent ask the USER a structured
  * multiple-choice question (which approach? which of these?) — distinct from the design/37 permission `ask`
@@ -278,6 +286,41 @@ export interface AskUserQuestionToolOptions {
      *  would let a LATER question inherit the claim that an operator approved it. */
     redeemedApprovalQuestionsHash?: string;
 }
+/**
+ * Durable ask (design/64 TC-5.4 — ABOVE CC, the disconnected-human case): instead of the headless
+ * "proceed with your best judgment" default, an AskUserQuestion **suspends the task durably** and the
+ * answer resumes it — built ENTIRELY from existing primitives, no new gate kind.
+ *
+ * **The park is the fallback, not the mandate.** An adjudicated question parks durably UNLESS this run
+ * has a live question face (see {@link isLiveQuestionFace}), in which case the engine routes the question
+ * to that face and the answer arrives in-stream — same turn, no checkpoint, no rebuild. The park is what
+ * happens when nobody is there: no live face, the face affirming nobody is reachable, or a control-plane
+ * `forceDurableGate` that mandates the durable breakpoint regardless. A deployment that wired a live face
+ * AND wants every question parked anyway states that with `forceDurableGate` (or by not wiring the face).
+ *
+ *  1. Run the task with `durableApproval` + a durable `CheckpointStore` (+ durable session/offload
+ *     stores) and `combinePolicies(createDurableQuestionPolicy(), yourPolicy)`. The policy adjudicates
+ *     the AskUserQuestion call `ask`; in durable mode that suspends BEFORE the tool executes —
+ *     `onQuestion` is never called on the suspend side, so mount the tool with
+ *     {@link QUESTION_AWAITS_RESUME} when no live human is connected.
+ *  2. The HITL surface reads the questions from `checkpoint.pendingAction.args.questions` and collects
+ *     the human's {@link QuestionAnswer} out-of-band (hours/days later, any replica).
+ *  3. `runner.resume(token, { gate: "policy_ask", decision: "allow", boundCallId:
+ *     checkpoint.pendingAction.toolCallId }, { ...taskConfig, onQuestion: async () => answer })` — the resume
+ *     re-mounts the tool with the answer closure; the pending call executes against it and the model
+ *     continues with "The user answered: …". `boundCallId` (design/80 D-1) must name the pending call the
+ *     human answered, or the resume is rejected (`checkpoint.invalid_outcome`).
+ *
+ * A deployment that wants the CC-style threshold form ("wait N minutes for a live human, then go
+ * durable") implements it inside its own policy: return `allow` while a human is connected (the live
+ * `onQuestion` answers synchronously) and `ask` when none is — the sync-vs-durable choice is exactly
+ * one policy decision. Composing this policy's answer is how such a policy keeps the one judge (an `ask`
+ * from here means the call is the engine's question tool).
+ *
+ * The call it asks about is the ENGINE's question tool, read off the request's face ({@link isEngineQuestionFace}):
+ * a caller's tool that took the name is not asked about here, and neither is a bare request (no face — a host
+ * driving a policy outside a Runner stamps the face itself, `toolCallFaceOf(roster, name)`).
+ */
 export declare function createDurableQuestionPolicy(): ToolPolicy;
 /**
  * Placeholder {@link OnQuestion} that mounts the AskUserQuestion tool on a worker with NO live human

package/dist/core/ask-question.js

@@ -3,10 +3,10 @@ import { uuidv7 } from "../engine/session/uuid.js";
 import { boundInputHashOf, capturedJsonOf } from "./canonical-json.js";
 import { defineTool, errorResult } from "./tools.js";
 import { delimitUntrusted, inlineUntrusted } from "./untrusted-text.js";
-import { mountRuleFace, toolFace } from "./tool-catalog-entries.js";
+import { engineMountedAs, mountRuleFace, toolFace } from "./tool-catalog-entries.js";
 import { thrownText } from "./thrown-value.js";
-import { heldBy } from "./tool-name-readings.js";
 export const ASK_USER_QUESTION_TOOL_NAME = "AskUserQuestion";
+export const isEngineQuestionFace = engineMountedAs(["ask-user-question"]);
 export function classifyQuestionOutcome(outcome) {
     let unavailable;
     let answers;
@@ -69,11 +69,10 @@ export function validateAskQuestions(questions) {
     }
     return undefined;
 }
-const QUESTION_TOOL_NAMES = new Set([ASK_USER_QUESTION_TOOL_NAME]);
 export function createDurableQuestionPolicy() {
     return {
         check(req) {
-            if (!heldBy("policy.durableQuestion", QUESTION_TOOL_NAMES, req)) {
+            if (!isEngineQuestionFace(req.face)) {
                 return { action: "allow" };
             }
             return { action: "ask", message: "AskUserQuestion: awaiting a human answer (durable)" };

package/dist/core/ask-unresolvable-notice.d.ts

@@ -28,7 +28,7 @@
  * is pure.
  */
 import type { EngineNotice } from "./engine-notice.js";
-import type { AssertAllKeysHandled, HeadlessApproverSeat } from "./ask-origin.js";
+import { type ApprovalRemedy, type AssertAllKeysHandled, type HeadlessApproverSeat } from "./ask-origin.js";
 /** WHY the ask could not be resolved — the closed set (see the module note for each word). */
 export declare const ASK_UNRESOLVABLE_CAUSES: readonly ["approver_unavailable", "no_approver_wired", "mandate_unreconstructible"];
 export type AskUnresolvableCause = (typeof ASK_UNRESOLVABLE_CAUSES)[number];
@@ -52,6 +52,10 @@ export interface AskUnresolvableFacts {
      *  for arguments no approval can be bound to, the binding's own sentence, which is that text — the remedy's approver half would
      *  not let them run) — carried verbatim, never re-composed here. */
     readonly remedy?: string;
+    /** The ways out of that same refusal as data ({@link ApprovalRemedy}) — the approver, and the permission mode where the refusal could be
+     *  released by one — for a host that chooses which to offer. Rides exactly when {@link remedy} is the headless remedy's sentence
+     *  (`headlessApprovalRemedy`); a binding's own sentence, which has no way out to offer, carries none. */
+    readonly remedies?: readonly ApprovalRemedy[];
 }
 /**
  * Which causes take the caller-side remedy (`headlessApprovalRemedy`, ask-origin.ts), and in which seat's clause — the table IS
@@ -82,8 +86,9 @@ export declare function askUnresolvableRemedySeat(cause: AskUnresolvableCause):
  * an empty session or tool name, or a cause outside the closed set, is refused at the mint with a
  * `TypeError` rather than shaped into a notice that would route nowhere or say nothing.
  *
- * `detail: { sessionId, toolName, toolCallId, cause, parkLaneExisted, remedy? }` — `remedy` rides the causes that say nobody
- * could be asked ({@link askUnresolvableRemedySeat}: the sentence the refusal's tool text carries); `sessionId` is lifted onto the typed key by {@link import("./engine-notice.js").deliverEngineNotice}, the one throat.
+ * `detail: { sessionId, toolName, toolCallId, cause, parkLaneExisted, remedy?, remedies? }` — `remedy` rides the causes that say nobody
+ * could be asked ({@link askUnresolvableRemedySeat}: the sentence the refusal's tool text carries) and `remedies` beside it, the same
+ * way out as data ({@link ApprovalRemedy}); `sessionId` is lifted onto the typed key by {@link import("./engine-notice.js").deliverEngineNotice}, the one throat.
  */
 export declare function askUnresolvableNotice(facts: AskUnresolvableFacts): EngineNotice;
 export {};

package/dist/core/ask-unresolvable-notice.js

@@ -1,3 +1,4 @@
+import { APPROVAL_REMEDY_KINDS, readApprovalRemedy } from "./ask-origin.js";
 export const ASK_UNRESOLVABLE_CAUSES = Object.freeze(["approver_unavailable", "no_approver_wired", "mandate_unreconstructible"]);
 Object.freeze(ASK_UNRESOLVABLE_CAUSES);
 const ASK_UNRESOLVABLE_CAUSE_SET = new Set(ASK_UNRESOLVABLE_CAUSES);
@@ -18,7 +19,7 @@ export function askUnresolvableRemedySeat(cause) {
     return CAUSE_REMEDY_SEAT[cause];
 }
 export function askUnresolvableNotice(facts) {
-    const { sessionId, toolName, toolCallId, cause, parkLaneExisted, remedy } = facts;
+    const { sessionId, toolName, toolCallId, cause, parkLaneExisted, remedy, remedies } = facts;
     if (typeof sessionId !== "string" || sessionId.length === 0) {
         throw new TypeError("delegation.ask_unresolvable: sessionId is required — a user-audience notice with no session routes nowhere");
     }
@@ -31,12 +32,25 @@ export function askUnresolvableNotice(facts) {
     if (!isAskUnresolvableCause(cause)) {
         throw new TypeError(`delegation.ask_unresolvable: cause ${JSON.stringify(cause)} is not one of ${ASK_UNRESOLVABLE_CAUSES.join("/")}`);
     }
+    let remedyList;
+    if (remedies !== undefined) {
+        if (typeof remedy !== "string" || remedy.length === 0 || !Array.isArray(remedies) || remedies.length === 0) {
+            throw new TypeError("delegation.ask_unresolvable: remedies are a non-empty list of ways out riding beside the remedy sentence they restate");
+        }
+        remedyList = [];
+        for (let i = 0; i < remedies.length; i++) {
+            const read = Object.hasOwn(remedies, i) ? readApprovalRemedy(remedies[i]) : undefined;
+            if (read === undefined)
+                throw new TypeError(`delegation.ask_unresolvable: remedies[${i}] is not one way out of the closed set (${APPROVAL_REMEDY_KINDS.join("/")}) with exactly its own fields`);
+            remedyList.push(read);
+        }
+    }
     const park = parkLaneExisted ? "the durable approval park did not take it" : "no durable approval park is armed for this run";
     return {
         code: "delegation.ask_unresolvable",
         message: `approval for "${toolName}" could not be resolved: ${CAUSE_CLAUSE[cause]} and ${park} — ` +
             `the call was denied fail-closed and did not run. ${typeof remedy === "string" && remedy.length > 0 ? `To let it run: ${remedy}. ` : ""}To let such approvals wait for a person, run with a checkpoint store and a ` +
             `durable approval opt-in (or a live approver reachable for delegated children).`,
-        detail: { sessionId, toolName, toolCallId, cause, parkLaneExisted: parkLaneExisted === true, ...(typeof remedy === "string" && remedy.length > 0 ? { remedy } : {}) },
+        detail: { sessionId, toolName, toolCallId, cause, parkLaneExisted: parkLaneExisted === true, ...(typeof remedy === "string" && remedy.length > 0 ? { remedy } : {}), ...(remedyList !== undefined ? { remedies: remedyList } : {}) },
     };
 }

package/dist/core/auto-compaction.d.ts

@@ -3,8 +3,8 @@ import { type Message, type Model, type Tool } from "../internal/llm.js";
 import type { ContextWindowOverlay } from "./context-settings.js";
 import type { PostCompactContext, PreCompactContext, PreCompactResult } from "./hooks.js";
 import type { TraceEvent } from "./trace.js";
-import type { Brain } from "./types.js";
-import type { TaskEvent, TaskEventIdentity } from "./task-event.js";
+import type { Brain, ModelRef, TaskSpec } from "./types.js";
+import type { CompactOutcome, TaskEvent, TaskEventIdentity } from "./task-event.js";
 import type { CompactionEffect } from "./frame-settlement.js";
 import type { MintedAttachmentFrame } from "./user-attachment.js";
 /**
@@ -39,13 +39,18 @@ export type CompactionPhaseDurations = Omit<Extract<TraceEvent, {
     kind: "compaction.phase_timings";
 }>, "kind" | "version" | "taskId" | "ts" | "durationMs">;
 /** True iff `err` is a compaction failure caused by a manual compact() caller WITHDRAWING its
- *  request — see {@link MaybeCompactOptions.manualCancelSignal}. Two mint sites since the
- *  design/374 slice-3 commit-boundary re-check (C16): the summary call's own abort outcome, and
- *  the pre-persist "cancelled before commit" throw (a brain that ignored the abort finished the
- *  summary, but the withdrawal still fired before anything landed). Absence of the marker means
+ *  request — see {@link MaybeCompactOptions.manualCancelSignal}. Minted at every cut point of the
+ *  pass: before the pass commits, while the summary provider or the credential callback is
+ *  answering ({@link untilPassCut}), the summary call's own abort outcome, and the pre-persist
+ *  "cancelled before commit" throw (design/374 slice-3, C16: a brain that ignored the abort finished
+ *  the summary, but the withdrawal still fired before anything landed). Absence of the marker means
  *  the failure was NOT the withdrawal: a real summarizer error racing a late cancel stays
  *  unmarked so the caller's breaker/onError accounting still sees it. */
 export declare function isCompactionManualCancel(err: unknown): boolean;
+/** The ONE reason a failed compaction pass reports, read by every lane that accounts for one (the turn boundary, the end-of-task pass,
+ *  the prompt-too-long recovery) for its trace frame and its `compaction_outcome{failed}` event: the thrown value's words through the
+ *  same-principal tier, THEN bounded — minted before the cut, so the cut can leave no part of a value. */
+export declare function compactionFailureReason(err: unknown): string;
 /**
  * design/145 §1/§3 — the window-safety decision surfaced to the caller BEFORE the summary call
  * (same pre-call posture as `onInputTruncated`: the disclosure must survive a later summary
@@ -734,6 +739,66 @@ export interface CompactedFrameSource {
 export declare function mintCompactedEvent(comp: CompactedFrameSource, trigger: "auto" | "manual" | "forced", identity: TaskEventIdentity): Extract<TaskEvent, {
     type: "compacted";
 }>;
+/** `Runner.compactSession`'s request — the out-of-run manual compaction of a session no leg of the Runner holds. A plain
+ *  data object; the keys are a closed set. */
+export interface CompactSessionRequest {
+    /** The session to compact. It must exist. */
+    sessionId: string;
+    /** The model the session's next turn runs on — its window bounds the pass (resolved like `TaskSpec.model`). */
+    model: ModelRef;
+    /** This pass's summarization instructions: they REPLACE `compaction.instructions` and the default for this pass (the
+     *  `TaskStream.compact` reading); sanitized and capped like every instructions channel. */
+    instructions?: string;
+    /** The members of `TaskSpec.compaction` a pass reads, as a run would carry them. */
+    compaction?: Pick<NonNullable<TaskSpec["compaction"]>, "enabled" | "reserveTokens" | "keepRecentTokens" | "instructions" | "clampTolerance">;
+    /** The independent summary model (`TaskSpec.compactionModel`); absent ⇒ the deployment's `summarize` role (or its tier
+     *  default), else the main model. A role-derived model whose key↔URL pairing is broken falls back to the main model,
+     *  announced, as on a run. */
+    compactionModel?: ModelRef;
+    /** Per-model credentials (`TaskSpec.getApiKeyAndHeaders`). */
+    getApiKeyAndHeaders?: TaskSpec["getApiKeyAndHeaders"];
+    /** Withdraws the pass: aborted before the session's lock is taken, the answer is `"mooted"` with nothing done; while the pass
+     *  runs the summary call and the credential wait read it (store reads and appends, and the pre-flight's own 5 s timer, do not); a pass that already persisted is not undone. */
+    signal?: AbortSignal;
+}
+/** `Runner.compactSession`'s answer. */
+export interface CompactSessionResult {
+    /** What the pass did — the closed set `TaskStream.compact` resolves with. */
+    outcome: CompactOutcome;
+    /**
+     * The pass's frames, in order, each with its own `eventId` and no task attribution: `compaction_started` once the
+     * pass committed, then the frame that ends it — `compacted` (`trigger: "manual"`) on a landing, else
+     * `compaction_outcome` (`trigger: "manual"`). Empty when the pass never ran (a withdrawn request). Returned, not
+     * streamed: a `compaction_started` here is a record of the pass, not a live progress signal.
+     */
+    events: Array<Extract<TaskEvent, {
+        type: "compaction_started" | "compacted" | "compaction_outcome";
+    }>>;
+    /** The model calls the pass made (the summary, a hook's `$.model.complete`), priced as a run's side calls are; absent
+     *  when none was made. `usageMissing` ⇒ a reply reported no usage (a lower bound); `unpriced` ⇒ a call ran on a model
+     *  the deployment could not price. */
+    usage?: {
+        tokens: number;
+        totalInputTokens: number;
+        promptTokens: number;
+        cachedTokens: number;
+        cacheWriteTokens: number;
+        outputTokens: number;
+        costMicroUsd: number;
+        usageMissing?: true;
+        unpriced?: true;
+    };
+}
+/**
+ * The MANUAL outcome of a pass that returned (did not throw) — the one reading for every manual pass: the turn
+ * boundary serving a `TaskStream.compact` request and the out-of-run `Runner.compactSession`. A manual pass forces
+ * (`force` + `minTokens: 0`), so the floor's `suppressedByFloor` cannot occur and is not a case here.
+ */
+export declare function manualCompactOutcomeOf(comp: {
+    compacted: boolean;
+    blocked?: boolean;
+    disabled?: boolean;
+}): CompactOutcome;
 /**
  * THE mint of the `compaction_started` wire frame — the opening half of the pair whose closing half is the
  * `compacted` frame above (or a `compaction_outcome` that carries the same `pass`). One function, three

package/dist/core/auto-compaction.js

@@ -8,6 +8,7 @@ import { brainToRuntime } from "./runtime.js";
 import { defuseFenceMarkers, sanitizeUntrustedText } from "./untrusted-text.js";
 import { createSafeNotifier, observeThenableRejection } from "./safe-notify.js";
 import { thrownText } from "./thrown-value.js";
+import { egressThrownText } from "./untrusted-egress.js";
 export const DEFAULT_COMPACTION_INSTRUCTIONS = "Preserve verbatim every code, identifier, name, number, file path, error message, credential " +
     "reference, and explicit user instruction or decision mentioned anywhere in the conversation. " +
     "When in doubt, keep the specific detail rather than generalizing it.";
@@ -21,9 +22,33 @@ export function sanitizeCompactionInstructions(text) {
         : defused;
 }
 const COMPACTION_MANUAL_CANCEL_FLAG = "semaCompactionManualCancel";
+const PASS_CUT = Symbol("compaction-pass-cut");
+async function untilPassCut(start, signal) {
+    if (signal?.aborted === true)
+        return PASS_CUT;
+    if (signal === undefined)
+        return await start();
+    let release = () => undefined;
+    const cut = new Promise((resolve) => {
+        const onAbort = () => resolve(PASS_CUT);
+        signal.addEventListener("abort", onAbort, { once: true });
+        release = () => signal.removeEventListener("abort", onAbort);
+    });
+    try {
+        return await Promise.race([Promise.resolve(start()), cut]);
+    }
+    finally {
+        release();
+    }
+}
 export function isCompactionManualCancel(err) {
     return (typeof err === "object" && err !== null && err[COMPACTION_MANUAL_CANCEL_FLAG] === true);
 }
+const COMPACTION_FAILURE_REASON_MAX = 512;
+export function compactionFailureReason(err) {
+    const words = egressThrownText("same-principal", err);
+    return words.length > COMPACTION_FAILURE_REASON_MAX ? `${words.slice(0, COMPACTION_FAILURE_REASON_MAX)}…` : words;
+}
 function summarizationCharsCapacity(model) {
     return model.contextWindow > 0
         ? model.contextWindow * (model.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN)
@@ -161,29 +186,15 @@ export async function maybeCompact(opts) {
     let providerSummary;
     if (opts.summaryProvider && !forceRealSummary && !prep.value.isSplitTurn) {
         const providerModifiedFiles = computeFileLists(prep.value.fileOps).modifiedFilesByRecency;
-        const signal = opts.signal;
-        const cut = Symbol("cut");
-        let release = () => undefined;
-        const cutByAbort = new Promise((resolve) => {
-            if (signal === undefined || signal.aborted)
-                return;
-            const onAbort = () => resolve(cut);
-            signal.addEventListener("abort", onAbort, { once: true });
-            release = () => signal.removeEventListener("abort", onAbort);
-        });
+        const summaryProvider = opts.summaryProvider;
+        const boundary = prep.value;
         let consulted;
         try {
-            consulted =
-                signal?.aborted === true
-                    ? cut
-                    : await Promise.race([
-                        Promise.resolve(opts.summaryProvider({
-                            messagesToSummarize: prep.value.messagesToSummarize,
-                            previousSummary: prep.value.previousSummary,
-                            modifiedFiles: providerModifiedFiles,
-                        })),
-                        cutByAbort,
-                    ]);
+            consulted = await untilPassCut(() => summaryProvider({
+                messagesToSummarize: boundary.messagesToSummarize,
+                previousSummary: boundary.previousSummary,
+                modifiedFiles: providerModifiedFiles,
+            }), opts.signal);
             const trimmed = typeof consulted === "string" ? consulted.trim() : "";
             if (trimmed) {
                 providerSummary = trimmed;
@@ -191,10 +202,7 @@ export async function maybeCompact(opts) {
         }
         catch {
         }
-        finally {
-            release();
-        }
-        if (consulted === cut) {
+        if (consulted === PASS_CUT) {
             throw Object.assign(new CompactionError("aborted", "compaction cancelled while the summary provider was answering — nothing was persisted"), opts.manualCancelSignal?.aborted === true ? { [COMPACTION_MANUAL_CANCEL_FLAG]: true } : {});
         }
     }
@@ -298,7 +306,12 @@ export async function maybeCompact(opts) {
                 });
             }
         }
-        const auth = await opts.getApiKeyAndHeaders?.(summaryModel);
+        const getApiKeyAndHeaders = opts.getApiKeyAndHeaders;
+        const authed = getApiKeyAndHeaders === undefined ? undefined : await untilPassCut(() => getApiKeyAndHeaders(summaryModel), opts.signal);
+        if (authed === PASS_CUT) {
+            throw Object.assign(new CompactionError("aborted", "compaction cancelled while the summary model's credentials were being fetched — nothing was summarized or persisted"), opts.manualCancelSignal?.aborted === true ? { [COMPACTION_MANUAL_CANCEL_FLAG]: true } : {});
+        }
+        const auth = authed;
         const summarySignal = opts.signal;
         const runtime = brainToRuntime(opts.brain);
         const forkCandidate = opts.compactionModel === undefined ? opts.forkContext?.() : undefined;
@@ -601,6 +614,9 @@ export function mintCompactedEvent(comp, trigger, identity) {
         ...identity,
     };
 }
+export function manualCompactOutcomeOf(comp) {
+    return comp.compacted ? "compacted" : comp.blocked ? "blocked" : comp.disabled ? "disabled" : "noop";
+}
 export function mintCompactionStartedEvent(start, identity) {
     return { type: "compaction_started", trigger: start.trigger, pass: start.pass, startedAt: start.startedAt, ...identity };
 }

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

@@ -37,7 +37,11 @@ export interface BackgroundAgentRecord {
      *  keys on THIS field (listBySession matches it as a second arm), not on an alias walk. */
     rootSessionId?: string;
     parentTaskId?: string;
-    name?: string;
+    /** The agent's name — the spawner's explicit one, or the one the engine derives from `handle`
+     *  (`engineAgentName`) when the spawn named none. Written by the registration that creates the row, so
+     *  every row core writes carries one; a revival re-reads it verbatim. A host store that reads a row an
+     *  earlier version wrote without one derives it from `handle` with the same function. */
+    name: string;
     agentType?: string;
     description?: string;
     /** Revival lookup key (CC meta-sidecar parity); populated when known, never required. The team
@@ -180,7 +184,7 @@ export interface BackgroundAgentRowSummary {
     sessionId?: string;
     parentSessionId?: string;
     rootSessionId?: string;
-    name?: string;
+    name: string;
     agentType?: string;
     status: BackgroundAgentRecord["status"];
     spawnedAt: number;

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

@@ -183,7 +183,7 @@ function toSummary(r) {
         ...(r.sessionId !== undefined ? { sessionId: r.sessionId } : {}),
         ...(r.parentSessionId !== undefined ? { parentSessionId: r.parentSessionId } : {}),
         ...(r.rootSessionId !== undefined ? { rootSessionId: r.rootSessionId } : {}),
-        ...(r.name !== undefined ? { name: r.name } : {}),
+        name: r.name,
         ...(r.agentType !== undefined ? { agentType: r.agentType } : {}),
         status: r.status,
         spawnedAt: r.spawnedAt,