@sema-agent/core 7.16.0 → 7.17.0

package/dist/config/defaults.js

@@ -2,8 +2,6 @@ export const RETAIN_DEFAULT_TTL_MS = 30 * 60 * 1000;
 export const RETAIN_DEFAULT_MAX = 16;
 export const DELEGATION_MAX_CONCURRENT_DEFAULT = 20;
 export const DELEGATION_MAX_PER_SESSION_DEFAULT = 200;
-export const ORPHAN_ADOPT_WINDOW_MS_DEFAULT = 48 * 60 * 60 * 1000;
-export const ORPHAN_ADOPT_MAX_DEFAULT = 20;
 export const SUBAGENT_TRANSCRIPT_RETENTION_DAYS_DEFAULT = 30;
 export const SESSION_DEFAULT_TTL_DAYS = 7;
 export const RUNNING_AGENT_OBSERVE_EVERY_BEATS = 4;

package/dist/core/artifact-host.d.ts

@@ -0,0 +1,218 @@
+import type { AssertAllKeysHandled } from "./ask-origin.js";
+/** The model-facing action words. `publish` is the default action and the one every host must declare. */
+export declare const ARTIFACT_ACTIONS: readonly ["publish", "list", "read", "list_files", "read_file"];
+export type ArtifactAction = (typeof ARTIFACT_ACTIONS)[number];
+/** Which face the host serves. `"local-stub"` = publish-only local storage with `eval-stub://` links;
+ *  `"hosted"` = a hosting plane that mints its own URLs. Declared by the host, never detected. */
+export declare const ARTIFACT_PLANES: readonly ["hosted", "local-stub"];
+export type ArtifactPlane = (typeof ARTIFACT_PLANES)[number];
+/** The `publishContext` word a publish carries (default `"plain"`). */
+export declare const ARTIFACT_PUBLISH_CONTEXTS: readonly ["pr_review", "workshop", "whiteboard", "prototype", "plain"];
+export type ArtifactPublishContext = (typeof ARTIFACT_PUBLISH_CONTEXTS)[number];
+/** The `list` scope words. */
+export declare const ARTIFACT_LIST_SCOPES: readonly ["mine", "shared", "all"];
+export type ArtifactListScope = (typeof ARTIFACT_LIST_SCOPES)[number];
+/**
+ * The content-origin class of the mounted tool, derived from the declared plane: a hosted plane hands
+ * back host-controlled bytes (URLs, titles, page content) and is classified external; the local stub
+ * reads nothing back from outside the process. Plane-keyed, never implementation-keyed.
+ */
+export declare const ARTIFACT_PLANE_CONTENT_ORIGIN: {
+    readonly hosted: "external";
+    readonly "local-stub": "local";
+};
+export type ContentOriginTableCoversEveryPlane = AssertAllKeysHandled<Exclude<ArtifactPlane, keyof typeof ARTIFACT_PLANE_CONTENT_ORIGIN>>;
+/** The host method each declared action is served by; the mount-time validator probes the method's presence. */
+export declare const ARTIFACT_ACTION_HOST_METHOD: {
+    readonly publish: "publish";
+    readonly list: "list";
+    readonly read: "read";
+    readonly list_files: "listFiles";
+    readonly read_file: "readFile";
+};
+export type HostMethodTableCoversEveryAction = AssertAllKeysHandled<Exclude<ArtifactAction, keyof typeof ARTIFACT_ACTION_HOST_METHOD>>;
+/** The typed failure words a host outcome may carry (`ok: false`). */
+export declare const ARTIFACT_HOST_FAILURE_CODES: readonly ["conflict", "url_foreign", "forbidden", "payload_too_large", "not_found", "force_refused", "refused"];
+export type ArtifactHostFailureCode = (typeof ARTIFACT_HOST_FAILURE_CODES)[number];
+/** The tool-result `details.code` (and `tool_end.errorCode`) each host failure word is projected to. */
+export declare const ARTIFACT_FAILURE_RESULT_CODE: {
+    readonly conflict: "artifact.publish_conflict";
+    readonly url_foreign: "artifact.url_foreign";
+    readonly forbidden: "artifact.forbidden";
+    readonly payload_too_large: "artifact.payload_too_large";
+    readonly not_found: "artifact.not_found";
+    readonly force_refused: "artifact.force_refused";
+    readonly refused: "artifact.refused";
+};
+export type ResultCodeTableCoversEveryHostFailure = AssertAllKeysHandled<Exclude<ArtifactHostFailureCode, keyof typeof ARTIFACT_FAILURE_RESULT_CODE>>;
+/** The one result code that is not a host word: the host threw, timed out, or answered outside its contract. */
+export declare const ARTIFACT_HOST_ERROR_CODE = "artifact.host_error";
+export type ArtifactResultCode = (typeof ARTIFACT_FAILURE_RESULT_CODE)[ArtifactHostFailureCode] | typeof ARTIFACT_HOST_ERROR_CODE;
+/** The `details.type` card the Artifact tool mints on every result. */
+export declare const ARTIFACT_CARD = "artifact";
+/**
+ * What a host declares at mount time. Invariants (a violation refuses the mount and announces
+ * `config.artifact_host_invalid`): `actions` non-empty, duplicate-free, within {@link ARTIFACT_ACTIONS},
+ * containing `"publish"`; `plane: "local-stub"` ⇒ `actions` is exactly `["publish"]`;
+ * `defaultVisibility` is `"private"`; both byte limits are positive finite integers; `multiFile` is a
+ * boolean; every declared action's host method exists; `plane: "local-stub"` ⇒ `storageDir` is a non-empty
+ * absolute path.
+ */
+export interface ArtifactHostCapabilities {
+    plane: ArtifactPlane;
+    actions: ReadonlyArray<ArtifactAction>;
+    /** The on-disk store of a `"local-stub"` plane (required there; ignored on `"hosted"`). Contract: the store
+     *  must lie OUTSIDE every root the run may write or read (the task root, `additionalDirectories`,
+     *  `additionalReadDirectories`) — a store the model can reach through the fs tools is not a trust boundary;
+     *  the engine refuses the mount (`config.artifact_host_invalid`) when it is inside one. */
+    storageDir?: string;
+    /** The only value this version mounts: a page is private until its owner shares it. */
+    defaultVisibility: "private";
+    maxFileBytes: number;
+    maxTotalBytes: number;
+    /** `false` ⇒ the publish arm takes one `file_path` only (`files[]` leaves the schema). */
+    multiFile: boolean;
+}
+/**
+ * Engine-minted call attribution and idempotency keys — closure-supplied, never a tool parameter.
+ * `taskId` / `sessionId` / `agentName` are audit attribution, never an authorization subject: a host
+ * instance is bound to one principal at construction. `runId` and `attemptId` are engine-minted trusted
+ * keys: `runId` is the same value `onMount` received; `attemptId` is one opaque value per tool call,
+ * stable across any host retry of that call, so a host MUST replay the first outcome for a repeated
+ * `attemptId` (a fresh publish never mints a second page, an update never advances twice).
+ */
+export interface ArtifactCallContext {
+    taskId: string;
+    sessionId?: string;
+    agentName?: string;
+    runId: string;
+    attemptId: string;
+}
+export interface ArtifactFileContent {
+    path: string;
+    content: Uint8Array;
+    mediaType?: string;
+}
+export interface ArtifactPublishRequest {
+    slug?: string;
+    /** Update locator. Present without `baseVersion` ⇒ the host applies last-write-wins. */
+    url?: string;
+    files: ReadonlyArray<ArtifactFileContent>;
+    /** Reserved on the seam; the model face does not expose it in this version. A host MAY refuse it. */
+    removeFiles?: ReadonlyArray<string>;
+    title?: string;
+    description?: string;
+    favicon?: string;
+    label?: string;
+    baseVersion?: string;
+    force?: boolean;
+    publishContext: ArtifactPublishContext;
+}
+/** The reference shape every publish / list / read result carries. */
+export interface ArtifactRef {
+    url: string;
+    slug: string;
+    version: string;
+    title?: string;
+}
+export interface ArtifactListRow extends ArtifactRef {
+    owner: "mine" | "shared";
+    updatedAt: string;
+}
+export interface ArtifactConflictSnapshot {
+    files: ReadonlyArray<ArtifactFileContent>;
+    title?: string;
+    description?: string;
+    favicon?: string;
+    label?: string;
+}
+export type ArtifactPublishOutcome = {
+    ok: true;
+    ref: ArtifactRef;
+} | {
+    ok: false;
+    code: "conflict";
+    currentVersion: string;
+    current: ArtifactConflictSnapshot | "reread";
+} | {
+    ok: false;
+    code: Exclude<ArtifactHostFailureCode, "conflict">;
+    message: string;
+};
+export type ArtifactListOutcome = {
+    ok: true;
+    rows: ReadonlyArray<ArtifactListRow>;
+    truncated: boolean;
+} | {
+    ok: false;
+    code: "refused";
+    message: string;
+};
+export type ArtifactReadOutcome = {
+    ok: true;
+    ref: ArtifactRef;
+    content: string;
+    isolatedSummary: boolean;
+} | {
+    ok: false;
+    code: "not_found" | "forbidden";
+    message: string;
+};
+export type ArtifactFilesOutcome = {
+    ok: true;
+    entries: ReadonlyArray<{
+        path: string;
+        bytes: number;
+        mediaType?: string;
+    }>;
+} | {
+    ok: false;
+    code: "not_found" | "forbidden";
+    message: string;
+};
+export type ArtifactFileOutcome = {
+    ok: true;
+    file: ArtifactFileContent;
+} | {
+    ok: false;
+    code: "not_found" | "forbidden";
+    message: string;
+};
+/**
+ * The hosting seat. Atomicity contract: no half version is ever observable — a reader sees the old
+ * complete version or the new complete version, never a mix of files / metadata / version number.
+ * The commit itself may be uncertain from the engine's side (the answer was lost after the host
+ * committed); the `attemptId` replay rule above is what makes a retry of that call converge.
+ */
+export interface ArtifactHost {
+    capabilities(): ArtifactHostCapabilities;
+    /** Called at every materialization of a run (prepare and resume) with the engine-minted run id. */
+    onMount?(runId: string): void;
+    publish(req: ArtifactPublishRequest, ctx: ArtifactCallContext): Promise<ArtifactPublishOutcome>;
+    list?(req: {
+        scope: ArtifactListScope;
+        limit: number;
+    }, ctx: ArtifactCallContext): Promise<ArtifactListOutcome>;
+    read?(req: {
+        url: string;
+    }, ctx: ArtifactCallContext): Promise<ArtifactReadOutcome>;
+    listFiles?(req: {
+        url: string;
+    }, ctx: ArtifactCallContext): Promise<ArtifactFilesOutcome>;
+    readFile?(req: {
+        url: string;
+        path: string;
+    }, ctx: ArtifactCallContext): Promise<ArtifactFileOutcome>;
+}
+export type ArtifactHostCapabilitiesVerdict = {
+    ok: true;
+    capabilities: ArtifactHostCapabilities;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * Read and validate a host's declaration. Every invariant of {@link ArtifactHostCapabilities} is judged
+ * here and nowhere else; a `problem` names the first violated one in operator-facing words.
+ */
+export declare function readArtifactHostCapabilities(host: unknown): ArtifactHostCapabilitiesVerdict;

package/dist/core/artifact-host.js

@@ -0,0 +1,92 @@
+import { isAbsolute } from "node:path";
+export const ARTIFACT_ACTIONS = ["publish", "list", "read", "list_files", "read_file"];
+export const ARTIFACT_PLANES = ["hosted", "local-stub"];
+export const ARTIFACT_PUBLISH_CONTEXTS = ["pr_review", "workshop", "whiteboard", "prototype", "plain"];
+export const ARTIFACT_LIST_SCOPES = ["mine", "shared", "all"];
+export const ARTIFACT_PLANE_CONTENT_ORIGIN = {
+    hosted: "external",
+    "local-stub": "local",
+};
+export const ARTIFACT_ACTION_HOST_METHOD = {
+    publish: "publish",
+    list: "list",
+    read: "read",
+    list_files: "listFiles",
+    read_file: "readFile",
+};
+export const ARTIFACT_HOST_FAILURE_CODES = ["conflict", "url_foreign", "forbidden", "payload_too_large", "not_found", "force_refused", "refused"];
+export const ARTIFACT_FAILURE_RESULT_CODE = {
+    conflict: "artifact.publish_conflict",
+    url_foreign: "artifact.url_foreign",
+    forbidden: "artifact.forbidden",
+    payload_too_large: "artifact.payload_too_large",
+    not_found: "artifact.not_found",
+    force_refused: "artifact.force_refused",
+    refused: "artifact.refused",
+};
+export const ARTIFACT_HOST_ERROR_CODE = "artifact.host_error";
+export const ARTIFACT_CARD = "artifact";
+const isPositiveInt = (v) => typeof v === "number" && Number.isSafeInteger(v) && v > 0;
+const wordOf = (set, v) => typeof v === "string" && set.includes(v);
+export function readArtifactHostCapabilities(host) {
+    if (host === null || typeof host !== "object")
+        return { ok: false, problem: "artifactHost is not an object" };
+    const h = host;
+    if (typeof h.capabilities !== "function")
+        return { ok: false, problem: "artifactHost.capabilities is not a function" };
+    let raw;
+    try {
+        raw = h.capabilities.call(host);
+    }
+    catch (err) {
+        return { ok: false, problem: `artifactHost.capabilities() threw: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (raw === null || typeof raw !== "object")
+        return { ok: false, problem: "artifactHost.capabilities() did not return an object" };
+    const c = raw;
+    const plane = c["plane"];
+    if (!wordOf(ARTIFACT_PLANES, plane))
+        return { ok: false, problem: `capabilities.plane must be one of ${ARTIFACT_PLANES.join(" | ")}` };
+    const actions = c["actions"];
+    if (!Array.isArray(actions) || actions.length === 0)
+        return { ok: false, problem: "capabilities.actions must be a non-empty array" };
+    for (const a of actions)
+        if (!wordOf(ARTIFACT_ACTIONS, a))
+            return { ok: false, problem: `capabilities.actions carries a word outside ${ARTIFACT_ACTIONS.join(" | ")}` };
+    if (new Set(actions).size !== actions.length)
+        return { ok: false, problem: "capabilities.actions carries a duplicate" };
+    if (!actions.includes("publish"))
+        return { ok: false, problem: 'capabilities.actions must include "publish"' };
+    if (plane === "local-stub" && (actions.length !== 1 || actions[0] !== "publish"))
+        return { ok: false, problem: 'a "local-stub" plane must declare exactly ["publish"]' };
+    if (c["defaultVisibility"] !== "private")
+        return { ok: false, problem: 'capabilities.defaultVisibility must be "private"' };
+    if (!isPositiveInt(c["maxFileBytes"]))
+        return { ok: false, problem: "capabilities.maxFileBytes must be a positive integer" };
+    if (!isPositiveInt(c["maxTotalBytes"]))
+        return { ok: false, problem: "capabilities.maxTotalBytes must be a positive integer" };
+    if (typeof c["multiFile"] !== "boolean")
+        return { ok: false, problem: "capabilities.multiFile must be a boolean" };
+    const storageDir = c["storageDir"];
+    if (plane === "local-stub" && (typeof storageDir !== "string" || storageDir.length === 0 || !isAbsolute(storageDir)))
+        return { ok: false, problem: 'a "local-stub" plane must declare its absolute storageDir' };
+    if (storageDir !== undefined && typeof storageDir !== "string")
+        return { ok: false, problem: "capabilities.storageDir must be a string when present" };
+    for (const a of actions) {
+        const method = ARTIFACT_ACTION_HOST_METHOD[a];
+        if (typeof host[method] !== "function")
+            return { ok: false, problem: `capabilities.actions declares "${a}" but artifactHost.${method} is not a function` };
+    }
+    return {
+        ok: true,
+        capabilities: Object.freeze({
+            plane,
+            actions: Object.freeze([...actions]),
+            defaultVisibility: "private",
+            maxFileBytes: c["maxFileBytes"],
+            maxTotalBytes: c["maxTotalBytes"],
+            multiFile: c["multiFile"],
+            ...(typeof storageDir === "string" ? { storageDir } : {}),
+        }),
+    };
+}

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

@@ -246,11 +246,14 @@ export declare function classifierMayAnswer(origin: AskOrigin): boolean;
  * the same way every other per-call fact does: the gate stamps it on the surviving ask, the
  * synchronous sites read it off the decision they spread, and the park leg threads its own parameter.
  */
-export declare function persistedRuleMandateOf(marks: {
+export declare function persistedRuleMandateOf(marks: MandateMarks): "operator_always" | "tool_marks" | "probe_mandate" | "probe_unanswered" | undefined;
+/** The mark inputs of the two mandate derivations — properties of the tool SEAT (`egress`, `shellGated`,
+ *  `irreversibility`) beside the two per-call facts the gate stamps. */
+export interface MandateMarks {
     egress?: boolean;
     shellGated?: boolean;
     irreversibility?: "never" | "maybe" | "always";
-    /** #502: the surviving ask's engine-stamped `probeMandated` — see
+    /** The surviving ask's engine-stamped `probeMandated` — see
      *  {@link import("./types.js").ReversibilityVerdict.mandated}. */
     probeMandated?: boolean;
     /** The pass's own record that the probe was consulted and did not answer (`GatePass.probeUnanswered`):
@@ -258,7 +261,30 @@ export declare function persistedRuleMandateOf(marks: {
      *  not see the pass and never passes it — a card may offer a rule the lane then discloses as shadowed
      *  (loud, never a silent override), the same drift window the `matchedAskRule` conjunct already has. */
     probeUnanswered?: boolean;
-}): "operator_always" | "tool_marks" | "probe_mandate" | "probe_unanswered" | undefined;
+}
+/**
+ * The SAFETY AXIS of one ask — what makes its durable park NON-BUDGETABLE (`irreversible_ask`), judged
+ * from the same mark inputs as the rule-lane mandate plus the gate's own record of which tighten minted the
+ * ask. `egress` is the tool's static external-write mark, as it always was. `irreversible` is a mandate of
+ * THIS call: the tool's own tier (`tool_marks` — the deployment declared the tool may be irreversible,
+ * and a policy or hook asking first does not un-declare it), the operator's per-call doctrine
+ * (`operator_always`), the probe's structural verdict (`probe_mandate` / `probe_unanswered`), OR — under a
+ * shell-seat-installed `"maybe"` tier — the shell gate's own tighten having minted this ask (the doctrine's
+ * probe judged THIS command not reversible). A policy ask on a shell-gated tool that the doctrine's probe
+ * did not tighten and did not mandate is a plain ask: the tier was the probe's instrument, not a risk
+ * label, and the park stays the budgetable kind. Before this derivation the static tier alone set the bit,
+ * so every policy ask on Bash under `shellGate:"classify"` parked non-budgetable.
+ *
+ * Deliberately NOT the rule-lane predicate verbatim: a shell tighten's ask is rule-clearable (a person's
+ * past yes to this command shape stands) yet non-budgetable (a budget's mechanical yes is not a person's).
+ * The two derivations share every other row through {@link irreversibilityMandateOf}.
+ */
+export declare function safetyAxisOf(marks: MandateMarks & {
+    readonly tightened: AskOriginFacts["tightened"];
+}): {
+    egress: boolean;
+    irreversible: boolean;
+} | undefined;
 /** The PROBE half of the mandated family (the deployment's read boundary, judged per call): neither a standing rule
  *  nor the classifier clears these two words; `tool_marks`/`operator_always` bind the rule lane only (`safety_tighten`). */
 export declare function probeBoundaryMandate(word: ReturnType<typeof persistedRuleMandateOf>): boolean;

package/dist/core/ask-origin.js

@@ -68,19 +68,27 @@ export function classifierMayAnswer(origin) {
     return CLASSIFIER_MAY_ANSWER[origin];
 }
 export function persistedRuleMandateOf(marks) {
+    const word = irreversibilityMandateOf(marks);
+    return probeBoundaryMandate(word) ? word : marks.egress === true ? "tool_marks" : word;
+}
+function irreversibilityMandateOf(marks) {
     return marks.probeMandated === true
         ? "probe_mandate"
         : marks.probeUnanswered === true
             ? "probe_unanswered"
-            : marks.egress === true
-                ? "tool_marks"
-                : marks.shellGated === true
-                    ? marks.irreversibility === "always"
-                        ? "operator_always"
-                        : undefined
-                    : marks.irreversibility === "always" || marks.irreversibility === "maybe"
-                        ? "tool_marks"
-                        : undefined;
+            : marks.shellGated === true
+                ? marks.irreversibility === "always"
+                    ? "operator_always"
+                    : undefined
+                : marks.irreversibility === "always" || marks.irreversibility === "maybe"
+                    ? "tool_marks"
+                    : undefined;
+}
+export function safetyAxisOf(marks) {
+    const egress = marks.egress === true;
+    const irreversible = irreversibilityMandateOf(marks) !== undefined ||
+        (marks.shellGated === true && marks.irreversibility === "maybe" && marks.tightened === "shell_gate");
+    return egress || irreversible ? { egress, irreversible } : undefined;
 }
 export function probeBoundaryMandate(word) {
     return word === "probe_mandate" || word === "probe_unanswered";

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

@@ -348,3 +348,28 @@ source?: {
     principal?: string;
     sourceTaskId?: string;
 }, opts?: AskUserQuestionToolOptions): AgentTool;
+/**
+ * The ONE producer of the "engine stripped the spawn turn's question face" fact. The strip (removing `onQuestion`
+ * from a child spec — or from the parent SPEC seat a child is built from — when the child OUTLIVES the request that
+ * spawned it) and the disclosure flag (`RunInternals.questionFaceStripped` → the wiring manifest's
+ * `question.wired: "stripped_bg_lane"` + the posture door's exemption) are PAIR-PRODUCED from this single expression —
+ * never inferred from spec shape, never minted anywhere else. Three families ride it: the Agent tool's session-scoped
+ * background lanes (spec-override form), its retain snapshots (destructure-drop form; the flag then rides
+ * `internalsSnapshot`, so a revived leg keeps the exemption), and the Workflow tool (submit-and-return: every agent it
+ * spawns outlives the launching request, so the host's seat is stripped before it reaches the launch site). WHY:
+ * `spec.onQuestion` is by contract a per-REQUEST lane torn down with its turn; handing it to a leg that runs hours later
+ * would strand the child asking into a closed surface (`AskUserQuestion` awaits the answer). A key REMOVED and a key set
+ * `undefined` resolve identically through the engine's `spec.onQuestion ?? deps.onQuestion` reads — a process-level
+ * `RunnerDeps.onQuestion` still reaches the child; only the turn-bound value drops. Trust posture: RunInternals is a
+ * PUBLIC trusted-caller parameter, so the flag is an HONESTY device (the engine disclosing its own strip), not a
+ * security gate. The flag states "a face WAS removed here" — minted only when one actually existed (an inherently
+ * faceless lane reads `absent`, not `stripped_bg_lane`, and collects no exemption).
+ */
+export declare function stripSpawnTurnQuestionFace<S extends {
+    onQuestion?: OnQuestion;
+}>(spec: S): {
+    spec: Omit<S, "onQuestion">;
+    internalsFlag: {
+        questionFaceStripped?: true;
+    };
+};

package/dist/core/ask-question.js

@@ -378,3 +378,7 @@ export function createAskUserQuestionTool(onQuestion, source, opts) {
         },
     });
 }
+export function stripSpawnTurnQuestionFace(spec) {
+    const { onQuestion: spawnTurnQuestionFace, ...rest } = spec;
+    return { spec: rest, internalsFlag: spawnTurnQuestionFace !== undefined ? { questionFaceStripped: true } : {} };
+}

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

@@ -1,17 +1,22 @@
 /**
  * `delegation.ask_unresolvable` — the one mint of the notice the gate raises when an `ask` reached its
- * final deny with NOBODY having judged it: the approver consulted for the call (the run's own seat, or an
- * ancestor's frozen seat on a delegated child) answered the ROUTING question `unavailable` — no operator
- * is reachable for this ask — and no durable approval park took the call afterwards. The deny itself is
- * older than this notice and stands unchanged (the model reads the sentence as its tool result, the wire
- * carries `tool_end.gate.settlement.kind:"approver_unavailable"`); what was missing was any face a PERSON
- * watching notices could see. An operator reading notices alone saw nothing, and the person whose
- * delegated work was refused learned it only by reading the child's transcript.
+ * final deny with NOBODY having judged it. Three ways that happens, one event class ("a call was denied
+ * fail-closed because its approval could not be resolved"), one closed cause set:
+ *  · `approver_unavailable` — the approver consulted for the call (the run's own seat, or an ancestor's
+ *    frozen seat on a delegated child) answered the ROUTING question `unavailable` and no durable park
+ *    took the call afterwards (`tool_end.gate.settlement.kind:"approver_unavailable"`);
+ *  · `no_approver_wired` — no approver (or, for a question, no question face) is wired for this run, or
+ *    the seat is the deny posture string: the headless auto-deny (`settlement.kind:"no_approver"`);
+ *  · `mandate_unreconstructible` — an inherited durable-approval mandate binds the ask and THIS leg has no
+ *    park facility to honor it, so the delegated child refuses in-fold rather than let a synchronous layer
+ *    resolve what its ancestor bound to a park (an in-fold deny; no settlement rides the frame).
+ * The deny itself is older than this notice and stands unchanged (the model reads the sentence as its
+ * tool result); what was missing was any face a PERSON watching notices could see — an operator reading
+ * notices alone saw nothing, and the person whose work was refused learned it only from a transcript.
  *
- * Two deny arms compose this settlement — the marked-call intercept (an ancestor's seat answered
- * unavailable and the float found no park) and the resolver's own unavailable arm — and both reach ONE
- * exit in the gate lanes, after the park re-route has had its one attempt. That exit is the only caller of
- * this factory: one call, one notice, once per tool call.
+ * ONE exit composes it: the gate's single deny exit (`exitGate`), which reads the settlement the deny
+ * carries or the cause an in-fold arm attested, after every park re-route has had its attempt. That exit is
+ * the only caller of this factory: one call, one notice, once per tool call.
  *
  * Audience `"user"`: the refused work is the user's own (their run, or a delegation their run made), and
  * the recovery — a checkpoint store with a durable approval opt-in so such asks can wait for a person, or
@@ -22,17 +27,21 @@
  * is pure.
  */
 import type { EngineNotice } from "./engine-notice.js";
-import type { SettlementKind } from "./gate-outcome.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];
+/** Membership test for {@link AskUnresolvableCause} — the word rides a notice detail across process boundaries. */
+export declare function isAskUnresolvableCause(v: unknown): v is AskUnresolvableCause;
 /** What the gate knows at the deny exit — facts only, no words of the engine's vocabulary composed. */
 export interface AskUnresolvableFacts {
     /** The session whose call was refused — the notice's routing key, required (see module note). */
     readonly sessionId: string;
     /** The tool the ask was for (the message quotes it verbatim). */
     readonly toolName: string;
-    /** The refused call's id — the correlation key to the `tool_end` frame carrying the same settlement. */
+    /** The refused call's id — the correlation key to the `tool_end` frame carrying the same deny. */
     readonly toolCallId: string;
-    /** The settlement the deny composed — always `approver_unavailable` today; carried as a fact, not re-derived. */
-    readonly settlementKind: Extract<SettlementKind, "approver_unavailable">;
+    /** Why the ask could not be resolved — carried as a fact from the exit, not re-derived here. */
+    readonly cause: AskUnresolvableCause;
     /** Whether a durable approval park lane was ARMED for this run (`true`: the park had its one attempt and
      *  did not take the call — it declined or failed; `false`: no park lane at all, the usual shape). */
     readonly parkLaneExisted: boolean;
@@ -41,12 +50,12 @@ export interface AskUnresolvableFacts {
  * Compose the `delegation.ask_unresolvable` notice from the gate's deny-exit facts.
  *
  * @contract delegation.ask_unresolvable.single_mint — the `delegation.ask_unresolvable` notice is composed
- * by CORE from the gate's deny-exit FACTS (session, tool, call id, the composed settlement, whether a park
- * lane existed) at the ONE exit both unavailable deny arms reach; no other site spells the code or the
- * sentence, and an empty session or tool name is refused at the mint with a `TypeError` rather than
- * shaped into a notice that would route nowhere.
+ * by CORE from the gate's deny-exit FACTS (session, tool, call id, the cause, whether a park lane existed)
+ * at the ONE deny exit every unresolvable arm reaches; no other site spells the code or the sentence, and
+ * 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, settlementKind, parkLaneExisted }` — `sessionId` is lifted
- * onto the typed key by {@link import("./engine-notice.js").deliverEngineNotice}, the one throat.
+ * `detail: { sessionId, toolName, toolCallId, cause, parkLaneExisted }` — `sessionId` is lifted onto the
+ * typed key by {@link import("./engine-notice.js").deliverEngineNotice}, the one throat.
  */
 export declare function askUnresolvableNotice(facts: AskUnresolvableFacts): EngineNotice;

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

@@ -1,5 +1,15 @@
+export const ASK_UNRESOLVABLE_CAUSES = ["approver_unavailable", "no_approver_wired", "mandate_unreconstructible"];
+const ASK_UNRESOLVABLE_CAUSE_SET = new Set(ASK_UNRESOLVABLE_CAUSES);
+export function isAskUnresolvableCause(v) {
+    return ASK_UNRESOLVABLE_CAUSE_SET.has(v);
+}
+const CAUSE_CLAUSE = {
+    approver_unavailable: "the approver reported that nobody is reachable for this ask",
+    no_approver_wired: "no approver (or question face) is wired for this run — the headless posture",
+    mandate_unreconstructible: "an inherited durable-approval mandate binds this ask and this leg has no park facility to honor it",
+};
 export function askUnresolvableNotice(facts) {
-    const { sessionId, toolName, toolCallId, settlementKind, parkLaneExisted } = facts;
+    const { sessionId, toolName, toolCallId, cause, parkLaneExisted } = 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");
     }
@@ -9,17 +19,15 @@ export function askUnresolvableNotice(facts) {
     if (typeof toolCallId !== "string" || toolCallId.length === 0) {
         throw new TypeError("delegation.ask_unresolvable: toolCallId is required");
     }
-    if (settlementKind !== "approver_unavailable") {
-        throw new TypeError(`delegation.ask_unresolvable: settlementKind ${JSON.stringify(settlementKind)} is not the unavailable settlement`);
+    if (!isAskUnresolvableCause(cause)) {
+        throw new TypeError(`delegation.ask_unresolvable: cause ${JSON.stringify(cause)} is not one of ${ASK_UNRESOLVABLE_CAUSES.join("/")}`);
     }
-    const park = parkLaneExisted
-        ? "the durable approval park did not take it"
-        : "no durable approval park is armed for this run";
+    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: the approver reported that nobody is reachable for this ask and ${park} — ` +
+        message: `approval for "${toolName}" could not be resolved: ${CAUSE_CLAUSE[cause]} and ${park} — ` +
             `the call was denied fail-closed and did not run. 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, settlementKind, parkLaneExisted: parkLaneExisted === true },
+        detail: { sessionId, toolName, toolCallId, cause, parkLaneExisted: parkLaneExisted === true },
     };
 }