@sema-agent/core 7.15.0 → 7.17.0

package/dist/core/tool-policy.js

@@ -2,14 +2,14 @@ import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { brandPolicyAskClass } from "./ask-class.js";
 import { sanitizeAutoModeArmingRecipe } from "./auto-mode-arming.js";
-import { join, normalize as normalizePath, posix as posixPath, sep, win32 as winPath } from "node:path";
+import { join, normalize as normalizePath, sep } from "node:path";
 import { BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName } from "../tools/fs/index.js";
 import { protectivePathTargetOf } from "./tool-registry.js";
 import { boundInputHashOf } from "./canonical-json.js";
 import { delimitUntrusted, inlineUntrusted, REVIEWER_NOTE_MAX_BODY } from "./untrusted-text.js";
 import { isNamespacedCoveringRuleName, namespacedRuleNameCovers, parsePermissionRule } from "./permission-rules.js";
 import { protocolOf } from "./protocol-table.js";
-import { isAbsolutePathForm, isWinFormPath, writeTargetPath } from "../tools/fs/safety.js";
+import { isAbsoluteForFamily, isAbsolutePathForm, joinForFamily, normalizeAbsPathLexically, pathFamilyOf, writeTargetPath } from "../tools/fs/safety.js";
 const DECISION_REASONS = ["rule", "mode", "hook", "safety", "classifier", "persisted_rule", "sandbox", "org_rule", "org_unavailable", "read_only"];
 const DECISION_REASON_SET = new Set(DECISION_REASONS);
 function settledByNobody(kind) {
@@ -32,6 +32,9 @@ function transferEngineSettlement(from, to) {
     const c = CLASSIFIER_DENY_CAUSES_SEAT.get(from);
     if (c !== undefined)
         CLASSIFIER_DENY_CAUSES_SEAT.set(to, c);
+    const u = ASK_UNRESOLVABLE_CAUSES_SEAT.get(from);
+    if (u !== undefined)
+        ASK_UNRESOLVABLE_CAUSES_SEAT.set(to, u);
 }
 export function carryEngineAttestations(from, to) {
     transferEngineSettlement(from, to);
@@ -56,6 +59,19 @@ export function classifierDenyCauseOf(d, call) {
         return undefined;
     return v.cause;
 }
+const ASK_UNRESOLVABLE_CAUSES_SEAT = new WeakMap();
+export function attestAskUnresolvableCause(d, cause, call) {
+    ASK_UNRESOLVABLE_CAUSES_SEAT.set(d, { cause, toolCallId: call.toolCallId, toolName: call.toolName });
+    return d;
+}
+export function askUnresolvableCauseOf(d, call) {
+    if (typeof d !== "object" || d === null)
+        return undefined;
+    const v = ASK_UNRESOLVABLE_CAUSES_SEAT.get(d);
+    if (v === undefined || v.toolCallId !== call.toolCallId || v.toolName !== call.toolName)
+        return undefined;
+    return v.cause;
+}
 export function engineSettlementOf(d, call) {
     if (typeof d !== "object" || d === null)
         return undefined;
@@ -807,9 +823,8 @@ export function createTranscriptIntegrityPolicy(opts) {
     const shellTools = canonicalToolNameSet(opts?.tools);
     const dirSegs = dirs.map((d) => pathSegments(d).map(foldPathCase));
     const inProtectedDir = (p, liveCwd) => {
-        const rawRelative = !isAbsolutePathForm(p);
-        const joinInFamily = (base, rel) => isWinFormPath(base) ? winPath.join(base, rel) : posixPath.join(base, rel);
-        const abs = liveCwd !== undefined && rawRelative ? lexicalPath(joinInFamily(liveCwd, p), home) : lexicalPath(p, home);
+        const rawRelative = liveCwd === undefined ? !isAbsolutePathForm(p) : !isAbsoluteForFamily(pathFamilyOf({ root: liveCwd }), p);
+        const abs = liveCwd !== undefined && rawRelative ? lexicalPath(normalizeAbsPathLexically(joinForFamily(pathFamilyOf({ root: liveCwd }), liveCwd, p)), home) : lexicalPath(p, home);
         const segs = pathSegments(abs).map(foldPathCase);
         if (isAbsolutePathForm(abs) && dirSegs.some((d) => d.length <= segs.length && d.every((s, i) => s === segs[i])))
             return true;
@@ -891,6 +906,14 @@ export function askApproverIdentity(onAsk) {
 export function isLiveApproverSeat(onAsk) {
     return typeof onAsk === "function";
 }
+export const DURABLE_MANDATE_SOURCES = ["force_durable_gate", "durable_approval"];
+export function durableMandateSourceOf(args) {
+    if (args.forceDurableGate)
+        return "force_durable_gate";
+    if (args.durableApprovalDeclared && !isLiveApproverSeat(args.onAsk))
+        return "durable_approval";
+    return undefined;
+}
 export function tryCloneArgs(v) {
     try {
         const value = structuredClone(v);

package/dist/core/tool-result-budget.d.ts

@@ -35,7 +35,7 @@ export interface AggregateBudgetOptions {
         sizeChars: number;
         storeFallback: boolean;
     }) => void;
-    /** RB-142: fired once per batch that is STILL over budget after both passes — i.e. the cap did what it
+    /** Fired once per batch that is STILL over budget after both passes — i.e. the cap did what it
      *  could and the request is going out oversized anyway. Reachable when a batch holds more results than
      *  the budget can hold even at the minimum preview size (a compact preview has a floor, and N of them
      *  cannot be smaller than N × that floor). Before this existed the shortfall was entirely silent, so a

package/dist/core/tool-result-store.d.ts

@@ -25,7 +25,7 @@ export interface ToolResultStore {
      * deterministic ref, so `put` for an already-stored ref MUST be a no-op — re-writing would risk a
      * non-identical preview and break the prompt cache). A durable backend treats `ref` as the primary key
      * and should validate/sanitize it (it is composed from sessionId+toolCallId, not raw model input, but a
-     * durable store still owns key hygiene for its storage layer). RB-266: the floor of that hygiene is
+     * durable store still owns key hygiene for its storage layer). The floor of that hygiene is
      * NOT per-backend — every implementation rejects the unsafe ref set via {@link assertSafeToolResultRef}
      * (a volatile backend silently accepting what a durable one rejects is the drift this closes).
      *
@@ -139,7 +139,7 @@ export interface ToolResultDeletionReport {
  * the read face authorizes by COMPARING fields it already knows; `taskId` is present when the write site
  * has one (it is a narrowing of the session, never a substitute for it).
  *
- * #167 (namespace rule): a stamped `taskId` must name a coordinate the read face's CALLER presents —
+ * A stamped `taskId` must name a coordinate the read face's CALLER presents —
  * the host's own task/run id — never an engine-internal registry handle id. A handle id lives in a
  * namespace only the engine's in-memory registry can resolve, so an owner stamped with one compares
  * unequal to every caller coordinate forever: the entry becomes readable by NOBODY across the wire
@@ -181,7 +181,7 @@ export declare function assertToolResultProvenanceMatch(ref: string, stored: Too
  *  round-tripping through a durable backend (NULL column, missing JSON key) compares equal. */
 export declare function normalizeToolResultProvenance(p: ToolResultProvenance): ToolResultProvenance;
 /**
- * RB-266 — the ref-safety half of the {@link ToolResultStore} contract, shared by every backend.
+ * The ref-safety half of the {@link ToolResultStore} contract, shared by every backend.
  *
  * Why it is central and not per-backend: the file backend has always rejected these refs (its path
  * component guard, `stores/file/fs-atomic.ts:48`), while the in-memory backend accepted them
@@ -207,7 +207,7 @@ export declare function normalizeToolResultProvenance(p: ToolResultProvenance):
  */
 export declare function assertSafeToolResultRef(ref: string): void;
 /**
- * RB-273 — the SINGLE mint point for a tool-result `ref`. Three call sites compose the same
+ * The SINGLE mint point for a tool-result `ref`. Three call sites compose the same
  * `tr_<sessionId>~<toolCallId>` string (`withToolResultOffload` here, the aggregate budget's preview
  * pass, and the runner's clear-with-offload persist); this is that string's one definition.
  *
@@ -320,7 +320,7 @@ export declare class InMemoryToolResultStore implements ToolResultStore {
     private readonly opts?;
     /** put/get only — no scheduled deletion contract: honestly `"none"` (retention.ts). */
     readonly retention: "none";
-    /** #119: the entry is content AND owner as ONE value — the write-once election that decides the
+    /** The entry is content AND owner as ONE value — the write-once election that decides the
      *  content decides the owner in the same step (no window where an entry exists ownerless). */
     private readonly map;
     private totalChars;
@@ -328,7 +328,7 @@ export declare class InMemoryToolResultStore implements ToolResultStore {
         maxTotalChars?: number;
     } | undefined);
     put(ref: string, content: string, provenance?: ToolResultProvenance): void;
-    /** #119 — the owner recorded at the winning write; `undefined` for unknown AND for unowned entries,
+    /** The owner recorded at the winning write; `undefined` for unknown AND for unowned entries,
      *  which a read face treats identically (fail-closed). */
     ownerOf(ref: string): ToolResultProvenance | undefined;
     /** Erase this session's entries, selected on the owner recorded at the winning write (the interface
@@ -370,7 +370,7 @@ export declare class ScopedToolResultStore implements ToolResultStore {
     readonly volatileBacking: boolean;
     constructor(inner: ToolResultStore, scope: string);
     /** Length-prefixed namespace — unambiguous for any scope string (no delimiter-injection ambiguity).
-     *  RB-266: the scope segment is ENCODED (injective, and its output charset carries no path separator
+     *  The scope segment is ENCODED (injective, and its output charset carries no path separator
      *  or control character), so a deployment whose trust scope contains one cannot compose a key the
      *  inner store must reject — the ref-safety rule then applies to the caller's ref alone. */
     private key;
@@ -379,7 +379,7 @@ export declare class ScopedToolResultStore implements ToolResultStore {
         offset?: number;
         limit?: number;
     }): Promise<ToolResultSlice | undefined> | ToolResultSlice | undefined;
-    /** #119 — same namespacing as {@link get}. `undefined` when the inner store predates the operation
+    /** Same namespacing as {@link get}. `undefined` when the inner store predates the operation
      *  (an unowned answer, which the read face reads fail-closed — never a fabricated owner). */
     ownerOf(ref: string): Promise<ToolResultProvenance | undefined> | ToolResultProvenance | undefined;
     /** THIS task's offload count only — the D-2 gate's per-task semantics (see class doc). */
@@ -390,10 +390,10 @@ export declare function isVolatileOffloadStore(store: ToolResultStore): boolean;
 /** Reserved name of the injected large-result reader (design/108 PascalCase: `read_tool_result`→`ReadToolResult`). */
 export declare const OFFLOAD_TOOL_NAME = "ReadToolResult";
 /**
- * RB-469-d — the runner's clear-with-offload persist, as ONE construction point (the closure used to
+ * The runner's clear-with-offload persist, as ONE construction point (the closure used to
  * live inline in prepare-task). Fire-and-forget by design (the caller returns the ref synchronously).
  *
- * #167 (A-025.17) — a failed put REPORTS the loss, it never writes under the ref. The previous arm
+ * A failed put REPORTS the loss, it never writes under the ref. The previous arm
  * wrote a lost-marker row under the SAME ref "so the page-back face reports the true cause", and that
  * one write carried two defects:
  *   - **revival**: the put and a session purge can race. When the put loses, the marker write lands
@@ -450,7 +450,7 @@ export declare const DEFAULT_TOOL_RESULT_THRESHOLD_CHARS = 20000;
  *  the per-message aggregate budget (design/64 §17.2) produces the SAME preview format (deterministic →
  *  byte-identical across queries → prompt-cache safe).
  *
- *  #115 (2026-08-09) — the truncation line states WHERE the rest is, not what anyone can do with it.
+ *  The truncation line states WHERE the rest is, not what anyone can do with it.
  *  "read more" alone reads as a promise that the full output is retrievable, and the model relays that
  *  promise to the person it is talking to; what is actually guaranteed is narrower and exactly two
  *  things: the text is retained in this run's tool-result store, and THIS chain can page it back. A

package/dist/core/tool-spec.d.ts

@@ -48,7 +48,7 @@ export interface ReversibilityVerdict {
      *  a malformed value costs the DISCLOSURE only, never the ask. */
     cause?: import("./checkpoint-store.js").ProbeCause;
     /**
-     * #502 (additive) — this demotion is STRUCTURAL, not the probe hesitating: the call crosses a
+     * This demotion is STRUCTURAL, not the probe hesitating: the call crosses a
      * boundary the deployment declared, so a persisted allow rule must not retire the resulting ask.
      * The gate folds it into the #144 mandate family ("allow rules silence the CLASSIFIER's questions,
      * never a MANDATED one") beside an operator `shellGate:"always"` and the tool's own
@@ -385,7 +385,7 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
      */
     defer?: boolean;
     /**
-     * RB-400-a — inline-keep override, judged FIRST in the deferral chain (CC 220 counterpart:
+     * Inline-keep override, judged FIRST in the deferral chain (CC 220 counterpart:
      * `alwaysLoad`, declared per MCP tool via `_meta["anthropic/alwaysLoad"]`, whose `isDeferredTool`
      * checks it before every deferral arm): `true` pins this tool's full schema inline in every
      * request — it is never deferred, regardless of its own {@link defer}, {@link TaskSpec.deferTools},
@@ -493,7 +493,7 @@ export type ToolReturn = string | {
     /** Hint the agent to stop after this tool batch. */
     terminate?: boolean;
     /**
-     * RB-211 (root-cause widening): a `ToolSpec.execute` can RETURN a failure
+     * A `ToolSpec.execute` can RETURN a failure
      * receipt instead of throwing (teaching errors that carry structured `details`, e.g. an
      * unrecoverable-but-informative rejection). Before this field existed, `ToolReturn` had NO
      * isError channel at all — `defineTool`'s wrapper builds a fresh `{content,details,terminate}`
@@ -872,21 +872,15 @@ export interface ToolExecuteContext {
      */
     interactiveTools?: false;
     /**
-     * RB-220 — read-only mirror of {@link "./types.js".TaskSpec.oneShot} (same trust tier/seat as
+     * Read-only mirror of {@link "./types.js".TaskSpec.oneShot} (same trust tier/seat as
      * `principal`): this RUN has no later turn for an async background notification to land in (a
      * headless `-p` process exits once the turn ends). A delegation tool (`createSubagentTool`) reads
      * it to branch its background-launch RECEIPT toward an active block-wait instruction instead of
-     * "end your turn and wait" — mirrors {@link import("../orchestration/run-workflow-tool.js").RunWorkflowToolDeps.oneShot}'s
-     * guidance-text branch for `run_workflow`. Undefined when the tool runs outside a Runner task.
+     * "end your turn and wait" — the Workflow tool branches its launch receipt the same way off the seat it is
+     * mounted with (`RunWorkflowToolDeps.parentSpecSeat.oneShot`). The CHILDREN's copy rides {@link parentSpecSeat}
+     * (only `true` travels there). Undefined when the tool runs outside a Runner task.
      */
     oneShot?: boolean;
-    /**
-     * design/112 C1/C5 — read-only SNAPSHOT of the parent task's client-supplied USER facts (timeZone/userEmail),
-     * inherited verbatim down the delegation tree like `principal`, so a subagent/fork child's
-     * `# Environment` block localizes "today" to the SAME user zone (not the container's UTC) and names the same
-     * user. Runner-filled (NOT a tool argument). Undefined when the task carries no clientContext.
-     */
-    clientContext?: TaskSpec["clientContext"];
     /**  — the parent's tool-face controls ({@link TaskSpec.excludeTools} /
      *  {@link TaskSpec.deferTools}), inherited down the delegation tree like `principal` (Runner-filled,
      *  read-only): a scenario-wide roster must not be escapable by delegating to a child that remounts
@@ -911,30 +905,32 @@ export interface ToolExecuteContext {
      *  tool-face controls (Runner-filled): a classic-profile parent's children speak classic too
      *  unless the child spec says otherwise (child spec wins — profile is presentation, not policy). */
     promptProfile?: "simple" | "classic";
-    /** the parent's declared extra file-tool roots ({@link TaskSpec.additionalDirectories}),
-     *  inherited down the delegation tree (Runner-filled, copy-at-spawn): a deployment that widened the
-     *  fs fence (e.g. the scratchpad host lane) widened it for the TASK, and a delegated child doing the
-     *  same work hit `path_not_in_root` on the very directory the parent could write. Same trust tier as
-     *  the spec field (deployment declaration, never a model argument). */
-    additionalDirectories?: readonly string[];
-    /** The read-only half of the same seat ({@link TaskSpec.additionalReadDirectories}), inherited by
-     *  the same rule (Runner-filled, copy-at-spawn): a child doing the parent's work needs the same
-     *  read whitelist, and MUST NOT have it silently widened into a write grant in transit. */
-    additionalReadDirectories?: readonly string[];
-    /** the parent's environment facts ({@link TaskSpec.envFacts}), inherited down the
-     *  delegation tree (Runner-filled, copy-at-spawn): the sandbox binding (profile/egress/scratchpad)
-     *  is a DEPLOYMENT property, not a per-task one — a child in the same sandbox needs the same facts
-     *  (its env block renders the scratchpad section; its root fence admits the scratchpad dir). */
-    envFacts?: TaskSpec["envFacts"];
-    /**
-     * The parent task's DECLARED {@link TaskSpec.memoryPersistenceCapable} — present ONLY when the spec
-     * set it (an inferred run's ctx gains no key), Runner-filled on the same trusted seat as
-     * {@link principal}: never a model/tool argument. A delegation tool (`createSubagentTool`) forwards
-     * it into every child spec it builds so the deployment's persistence statement survives delegation:
-     * `false` is a floor a chosen agent definition cannot loosen (the read-only-memory disclosure must
-     * hold tree-wide when the deployment says nothing durable is reachable), `true` is a default a
-     * definition may narrow back to `false`. Absent ⇒ nothing is forwarded and each child's own roster
-     * inference decides, exactly as before the seat existed.
+    /**
+     * The parent SPEC seat this run hands its children ({@link import("./parent-spec-seat.js").ParentSpecSeat}):
+     * `principal`, `oneShot` (only `true`), `clientContext` (the user's TZ/email facts), `onQuestion` (the FROZEN
+     * question face — `AskUserQuestion` mounts on it), `additionalDirectories` / `additionalReadDirectories` (the
+     * fs-fence widening; the read-only half stays read-only in transit), `envFacts` (the sandbox facts), and the
+     * DECLARED `memoryPersistenceCapable`. Runner-filled, read-only, NEVER a model/tool argument; minted ONCE per
+     * prepare from the run's rebound spec + frozen question face (arrays and the facts object frozen copies). ABSENT
+     * when the tool runs outside a Runner task.
+     *
+     * A delegation tool applies it onto every child spec it builds with `applyParentSpecSeat` — the ONE law both
+     * delegation lanes (Task and Workflow) share: a value the child spec already carries WINS (an agent definition's
+     * own declaration, a deployment baseline, a trusted script), the seat FILLS an unset one, and the two REMOVAL
+     * values (`oneShot: true`, `memoryPersistenceCapable: false`) land unconditionally. A deployment that widened the
+     * fs fence widened it for the TASK, a per-request question face is the child's face too, a one-shot process is
+     * one-shot for the whole tree — none of that stops at one level.
+     */
+    parentSpecSeat?: import("./parent-spec-seat.js").ParentSpecSeat;
+    /** This run's per-request question face was STRIPPED by the engine (`RunInternals.questionFaceStripped` — the leg outlives
+     *  the request that spawned it), Runner-filled read-only. A delegation tool forwards it onto every descendant's internals:
+     *  the descendants are faceless by the same engine act, so the posture door's exemption travels with them. */
+    questionFaceStripped?: true;
+    /**
+     * The parent task's DECLARED {@link TaskSpec.memoryPersistenceCapable} as THIS run's own fact — present ONLY when
+     * the spec set it (an inferred run's ctx gains no key), Runner-filled on the same trusted seat as {@link principal}:
+     * never a model/tool argument. Read by the revival spawner as the waking run's own clamp (a declared `false` forces
+     * the read-only-memory disclosure onto the cycle it wakes). The CHILDREN's copy rides {@link parentSpecSeat}.
      */
     memoryPersistenceCapable?: boolean;
     /**
@@ -954,7 +950,7 @@ export interface ToolExecuteContext {
      */
     memoryCaptureOptedOut?: boolean | Promise<boolean>;
     /**
-     * design/383 §2.5 (rescan post-6.0.0-RC) — the floor seat's THIRD state: TRUE ⇔ the spawning
+     * design/383 §2.5 — the floor seat's THIRD state: TRUE ⇔ the spawning
      * session's capture opt-out state is INDETERMINATE at the moment a delegation tool reads this
      * seat (its capture record store is faulting, and no genuine record is known in-process). The
      * delegation lanes forward it into the child's trusted internals as the floor's indeterminate

package/dist/core/tools.d.ts

@@ -44,7 +44,7 @@ export declare function stampDefineToolBrand<T extends object>(tool: T, rebind:
  */
 export declare function rebindDefineToolCtx(product: AgentTool, enrich: ToolCtxEnricher): AgentTool;
 /**
- * RB-409 — a per-call ctx builder a MOUNT hands to {@link defineTool}.
+ * A per-call ctx builder a MOUNT hands to {@link defineTool}.
  *
  * Why the seat exists: the adapter below feeds the inner `ToolSpec.execute` a `{toolCallId, signal}`
  * ctx, because `AgentTool.execute(toolCallId, rawParams, signal, onUpdate)` — the contract every
@@ -72,7 +72,7 @@ export type ToolCtxEnricher = (base: ToolExecuteContext) => ToolExecuteContext;
  * typing accepts without needing the name.
  */
 export interface DefineToolOptions {
-    /** RB-409 — see {@link ToolCtxEnricher}. Absent ⇒ the inner spec sees exactly the pre-RB-409
+    /** See {@link ToolCtxEnricher}. Absent ⇒ the inner spec sees exactly the pre-RB-409
      *  `{toolCallId, signal}` ctx, so every mount that does not opt in stays byte-identical. */
     enrichCtx?: ToolCtxEnricher;
 }

package/dist/core/trace.d.ts

@@ -58,7 +58,7 @@ export type TraceEvent = {
     kind: "task.start";
     version: 1;
     taskId: string;
-    /** #499 (additive) — the ENGINE-minted identity of THIS run (`TaskResult.runId`). `taskId` is
+    /** The ENGINE-minted identity of THIS run (`TaskResult.runId`). `taskId` is
      *  `spec.taskId ?? sessionId`, so two runs of one session that declare no host task id emit two
      *  task.start frames under ONE id and a consumer pairing start↔end has no way to say which end
      *  closes which start. Present on every `task.start` (the frame is emitted after prepare, which
@@ -264,7 +264,7 @@ export type TraceEvent = {
     kind: "task.end";
     version: 1;
     taskId: string;
-    /** #499 (additive) — the run this terminal closes; pairs with the `task.start` frame's `runId`
+    /** The run this terminal closes; pairs with the `task.start` frame's `runId`
      *  (see that field for why `taskId` cannot carry the pairing, and for the ASYMMETRY: this frame
      *  is also emitted on the prepare-throw backstop, where no `task.start` exists — it still names
      *  its run, because the id is minted at prepare's first statement and prepare-time disclosures
@@ -290,7 +290,7 @@ export type TraceEvent = {
      *  loop breathes, so lateness this size means the environment starved the process (run89: an
      *  abandoned compile group froze the loop 646s; the 1200s hard abort landed 683s late). */
     timerLatenessMs?: number;
-    /** RB-20 (TB b-form): the run was stopped by the SYNCHRONOUS turn-boundary walltime
+    /** The run was stopped by the SYNCHRONOUS turn-boundary walltime
      *  backstop, not the hard-abort timer — i.e. the deadline had passed but the setTimeout leg
      *  had not fired yet (starved event loop). Pairs with `timerLatenessMs` for attribution. */
     walltimeSyncBackstop?: boolean;
@@ -308,7 +308,7 @@ export type TraceEvent = {
     model: string;
     provider?: string;
     /**
-     * RB-410 — 1-based index of the turn this provider call served, same numbering as `turn.end` and as
+     * 1-based index of the turn this provider call served, same numbering as `turn.end` and as
      * `tool.call.turn`. Lets a bridge put a `chat` span and the `execute_tool` spans of the tools that
      * call requested under one parent without re-deriving turn boundaries from event order.
      *
@@ -316,10 +316,10 @@ export type TraceEvent = {
      * is not a loop turn, so any number here would be a different measurement wearing the same name.
      */
     turn?: number;
-    /** RB-457-a: normalized prompt tokens that MISSED the cache (Anthropic-protocol `input_tokens`
+    /** Normalized prompt tokens that MISSED the cache (Anthropic-protocol `input_tokens`
      *  shape) — disjoint from `cacheRead`/`cacheWrite`. Carried the cache-inclusive total up to 2.13.x. */
     promptTokens: number;
-    /** RB-457-a: the cache-INCLUSIVE prompt total for this call (`promptTokens + cacheRead +
+    /** The cache-INCLUSIVE prompt total for this call (`promptTokens + cacheRead +
      *  cacheWrite`) — the figure `costMicroUsd` is computed from. */
     totalInputTokens: number;
     completionTokens: number;
@@ -349,7 +349,7 @@ export type TraceEvent = {
     taskId: string;
     name: string;
     /**
-     * RB-410 — the resolved call's id: the SAME value the wire's `tool_start`/`tool_end` `TaskEvent`
+     * The resolved call's id: the SAME value the wire's `tool_start`/`tool_end` `TaskEvent`
      * carries for this call. OTel GenAI names it `gen_ai.tool.call.id` on the `execute_tool` span.
      *
      * Why it matters: without it the trace face and the event face could only be paired by tool NAME
@@ -358,7 +358,7 @@ export type TraceEvent = {
      */
     toolCallId?: string;
     /**
-     * RB-410 — 1-based index of the turn this call ran in, on the same numbering `turn.end` reports
+     * 1-based index of the turn this call ran in, on the same numbering `turn.end` reports
      * (a `tool.call` is emitted BEFORE the `turn.end` that closes its turn, so the two agree without
      * look-ahead). No GenAI attribute corresponds; it is the PARENT-span correlation key a bridge
      * needs to nest an `execute_tool` span under the `chat` call that requested the tool.
@@ -427,7 +427,7 @@ export type TraceEvent = {
     ts: number;
 } | {
     /**
-     * #619 — the READ-ONLY reader cleared a shell call, so no person and no classifier was asked: the
+     * The READ-ONLY reader cleared a shell call, so no person and no classifier was asked: the
      * allow layer's second attribution channel beside `permission.persisted_rule_allowed`. `command` is
      * the FINAL command the gate judged (a policy rewrite included) — model-authored text, carried
      * verbatim as the audit fact this frame exists for (a consumer rendering it applies its own
@@ -802,12 +802,9 @@ export type TraceEvent = {
      *  = the proactive request-build pass (anchored estimate crossed the edit budget),
      *  `"refusal"` = the MC-R rejection-recovery arm (provider said input-too-long), `"blocking"`
      *  = the slice-3 guard-chain arm A (the machine's one pre-guard shot when the frontier pass
-     *  is off, `microCompact.machine: "off"`). SCOPE (X1): emitted only by the cc machine — the
-     *  `"frontier"` arm requires `microCompact.machine: "cc"` (the default since the slice-3
-     *  flip), the `"refusal"` arm requires `microCompact.clearOnRejection` (also default-on);
-     *  the legacy OPT-OUT machine clears silently exactly as pre-374 (its clears are ledger-less
-     *  and re-fire per request, so a frame there would re-count the same occurrences and break
-     *  this frame's cardinality clause). Cardinality: exactly ONE frame per firing pass — a retry
+     *  is off, `microCompact.machine: "off"`). The `"frontier"` arm requires
+     *  `microCompact.machine: "cc"` (the default), the `"refusal"` arm requires
+     *  `microCompact.clearOnRejection` (also default-on). Cardinality: exactly ONE frame per firing pass — a retry
      *  chain re-sending an already-cleared view emits none. A `"refusal"` frame also marks one
      *  attempt of the shared prompt-too-long recovery budget spent (the MC-R arm's retry rides
      *  the same per-chain account the forced-compaction arm draws on — the knob doc on

package/dist/core/untrusted-text.d.ts

@@ -394,7 +394,7 @@ export declare function defuseControlChars(text: string): string;
  * Defense-in-depth, NOT a guarantee (same posture as the rest of this module).
  */
 export declare function inlineUntrusted(text: string, maxLen?: number): string;
-/** backlog #239: the per-ENTRY ceiling inside a `ProbeCause` operand family (checkpoint-store's
+/** The per-ENTRY ceiling inside a `ProbeCause` operand family (checkpoint-store's
  *  structured probe account), sized like the descriptor's own `touchedPaths` entries (the same thing
  *  on the same card). Per entry, not per cause: that is the whole point of the structured shape —
  *  one pathological path costs only itself, where a single joined string let it consume every other

package/dist/core/wiring-manifest.d.ts

@@ -46,7 +46,8 @@ export type AskEffective = "human_reachable" | "auto_allow" | "auto_deny" | "par
  * The content-question channel, three-valued (design/173 §8.2 — a derived enum, not a bare
  * boolean): `"wired"` (a resolved `onQuestion` face exists), `"absent"` (none), or
  * `"stripped_bg_lane"` — the ENGINE deliberately stripped the spawn turn's per-request face from a
- * long-lived background/retained leg (correct design, not a configuration lie; the flag is minted
+ * leg that outlives the request: a session-scoped background/retained leg, or an agent the Workflow tool
+ * spawned (submit-and-return) — correct design, not a configuration lie; the flag is minted
  * ONLY by the engine's strip sites, pair-produced with the strip itself — never inferred from spec
  * shape).
  */
@@ -58,7 +59,7 @@ export type SeamProvenance = "spec" | "deps";
 /** Machine-readable reason codes for a park lane that is not (or not provably) effective. */
 export type ParkLaneReason = "no_checkpoint_store" | "no_durable_approval_opt_in" | "no_force_durable_gate" | "no_armed_safety_vocabulary" | "await_runtime_caps" | "await_tool_vocabulary";
 /**
- * #529 — the closed set of auto-mode ARMING outcomes a leg's manifest reports
+ * The closed set of auto-mode ARMING outcomes a leg's manifest reports
  * ({@link WiringManifest.autoMode}). Minted from the arming predicate's own three-arm read, as the
  * FIRST failing arm in predicate order:
  *  - `no_intent`      — no `TaskSpec.autoModeRequested` seat and no intent inherited on the chain /
@@ -244,7 +245,7 @@ export interface WiringManifest {
         restore: string;
     };
     /**
-     * #529 — EFFECTIVE half only, and ALWAYS present on an engine-minted effective manifest (unlike
+     * EFFECTIVE half only, and ALWAYS present on an engine-minted effective manifest (unlike
      * `modelGate`, which is present only when a trim happened: auto mode has an answer on every leg,
      * so absence here means an older mint or an external derivation, never "not applicable"). The
      * per-leg READ face of the auto-mode arming decision: `armed` ⇔ `reason === "armed"` (the

package/dist/core/workflow-journal-store.d.ts

@@ -15,7 +15,7 @@ export type WorkflowJournalEntry = {
     callKey: string;
     result?: never;
     /**
-     * #642 — the ordinal's leg is PARKED at a durable approval gate: the child's own paused `TaskResult`
+     * The ordinal's leg is PARKED at a durable approval gate: the child's own paused `TaskResult`
      * (its `terminal` carries the checkpoint token + gate, its `sessionId` the pinned session). A resume
      * reaching this ordinal with a matching call key does NOT run the call live (the parked child's
      * session is pinned under a pending checkpoint; a fresh spawn would duplicate it) — it drives the
@@ -73,7 +73,7 @@ export interface WorkflowJournalStore {
      *  line teaches only the TaskOutput route (which is always live). Engine-facing string, never parsed. */
     locator?(runId: string, scope: string): string | undefined;
     /**
-     * RB-242 (ruled 2026-07-30) — ADMISSION for a resume, so two concurrent
+     * ADMISSION for a resume, so two concurrent
      * `resumeFromRunId` legs off ONE source run cannot fork its execution.
      *
      * Why a store seam at all: the engine's own mutex is in-process only (`startWorkflow` refuses a duplicate
@@ -84,7 +84,7 @@ export interface WorkflowJournalStore {
      * shared durable layer, i.e. here.
      *
      * OPTIONAL, and absence is a first-class state: a store that does NOT implement this has NO STORE-LEVEL lease
-     * semantics. RB-367 (dual-process probe): a store without the hook is no longer completely
+     * semantics. A store without the hook is no longer completely
      * unguarded, though — `runWorkflow`'s engine falls back to a process-local admission table for exactly this
      * shape, so a same-process double `resumeFromRunId` off one source is still refused even against a store
      * that never implements this member. That fallback cannot see a SECOND process, which is the one thing a
@@ -132,7 +132,7 @@ export interface WorkflowJournalStore {
         holder?: string;
     }>;
     /**
-     * RB-242 — release the claim {@link resumeClaim} granted to `newRunId` on `(sourceRunId, scope)`.
+     * Release the claim {@link resumeClaim} granted to `newRunId` on `(sourceRunId, scope)`.
      * Called by the engine at the resuming run's TERMINAL boundary (in a `finally`, so abort/error/abandon are
      * covered), and ONLY when the matching claim was actually granted.
      *
@@ -143,7 +143,7 @@ export interface WorkflowJournalStore {
      * A throw here is swallowed by the engine — a release failure must never replace the run's real outcome, and
      * the store's TTL is the standing backstop for the row it left behind.
      *
-     * RB-355: the engine's terminal boundary now BOUNDS this call (and its wait on
+     * The engine's terminal boundary now BOUNDS this call (and its wait on
      * the {@link resumeClaim} verdict) by a timeout — a store that hangs would otherwise keep the run's `done`
      * promise pending forever, after the outcome is already decided. A release that outlives that bound is
      * treated exactly like one that throws: swallowed, with the TTL as the backstop. Implementations should not
@@ -158,7 +158,7 @@ export declare const MAX_JOURNAL_RESULT_BYTES: number;
 /** True when a serialized journal result is too large to store (UTF-8 byte length over {@link MAX_JOURNAL_RESULT_BYTES}). */
 export declare function oversizeJournalResult(serialized: string): boolean;
 export declare function callKeyOrdinal(callKey: string): number;
-/** RB-243: the errorCode a journal OVERSIZE TOMBSTONE carries — the resume path recognizes it to
+/** The errorCode a journal OVERSIZE TOMBSTONE carries — the resume path recognizes it to
  *  say WHY an ordinal never replays. `failed` + this code lands on the T2A-4 no-replay arm, so replay
  *  behavior is identical to the entry simply being absent (the pre-tombstone shape). */
 export declare const JOURNAL_OVERSIZE_ERROR_CODE = "workflow.journal_oversize";
@@ -192,7 +192,7 @@ export declare class WorkflowJournalOversizeError extends Error {
  * answer is the rule, the engine's tombstone the one place that pre-empts it.
  */
 export declare function assertJournalEntryFits(entry: WorkflowJournalEntry): void;
-/** RB-243: mint the tiny FAILED entry the ENGINE journals in place of an oversize result. The
+/** Mint the tiny FAILED entry the ENGINE journals in place of an oversize result. The
  *  tombstone is minted in the engine, NOT in a store — a store REFUSES an oversize entry
  *  ({@link assertJournalEntryFits}) and never invents one; the engine measures the durable copy first, so
  *  the store sees the tombstone, not the payload. Never copies `result.result`/`structuredOutput` (the
@@ -200,7 +200,7 @@ export declare function assertJournalEntryFits(entry: WorkflowJournalEntry): voi
  *  and the paid spend. Its own serialization is a few hundred bytes — always under the cap (pinned). */
 export declare function journalOversizeTombstone(result: TaskResult, bytes: number): TaskResult;
 /**
- * RB-367 (dual-process probe, core-side judgment) — the TTL a resume claim {@link
+ * The TTL a resume claim {@link
  * InMemoryWorkflowJournalStore} grants survives WITHOUT an engine release: the backstop for an engine that
  * abandoned a granted claim without ever reaching the terminal `finally` that releases it (a bug, not the
  * normal path — the normal path releases promptly). Same VALUE as the file store's `RESUME_CLAIM_TTL_MS`
@@ -214,7 +214,7 @@ export declare const IN_MEMORY_RESUME_CLAIM_TTL_MS: number;
  *  service's Postgres store (SVC-2). Records each run's `scope` and enforces it on load (CORE-9 audit BLOCKER:
  *  a cross-scope resumeFromRunId resolves to an empty journal — no cross-tenant disclosure).
  *
- *  RB-367: also carries a REAL {@link WorkflowJournalStore.resumeClaim}/{@link
+ *  Also carries a REAL {@link WorkflowJournalStore.resumeClaim}/{@link
  *  WorkflowJournalStore.releaseResumeClaim} implementation (this store used to be the canonical example of a
  *  store WITHOUT the seam — its own header said so). Left unimplemented, the DEFAULT deployment (no
  *  `journalStore` supplied, or this store supplied explicitly) had NO protection against two same-process
@@ -231,7 +231,7 @@ export declare class InMemoryWorkflowJournalStore implements WorkflowJournalStor
      *  collide across the boundary between the two fields. */
     private readonly resumeClaims;
     private claimsForScope;
-    /** RB-367 — contract parity with the file store: keyed by `(sourceRunId, scope)`; idempotent re-grant to the
+    /** Contract parity with the file store: keyed by `(sourceRunId, scope)`; idempotent re-grant to the
      *  SAME holder; an unexpired claim held by someone else refuses (naming the holder); an expired or absent
      *  claim is free to take. Acquisition is a single synchronous Map read-then-write with no `await` between
      *  the check and the publish — there is no window (matching the atomicity RB-354 requires of a durable
@@ -240,7 +240,7 @@ export declare class InMemoryWorkflowJournalStore implements WorkflowJournalStor
         granted: boolean;
         holder?: string;
     }>;
-    /** RB-367 — release ONLY a claim `newRunId` still holds (a missing/foreign/already-taken-over claim is a
+    /** Release ONLY a claim `newRunId` still holds (a missing/foreign/already-taken-over claim is a
      *  no-op, never an error — matches the file store's contract). */
     releaseResumeClaim(input: ResumeClaimArgs): Promise<void>;
     load(runId: string, scope: string): Promise<WorkflowJournalEntry[]>;

package/dist/engine/execution-env/node-execution-env.d.ts

@@ -79,8 +79,9 @@ export declare function openSpoolPair(base: string): {
 };
 export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCapability, SchedulerCapability {
     cwd: string;
-    /** #644 — this adapter runs on the engine host, so the host's home IS the environment's (`ExecutionEnv.homeDir`). */
-    readonly homeDir: string;
+    /** `ExecutionEnv.homeDir` = the `HOME` the shell child receives (its `~`/`$HOME`/`${HOME}` all expand to it), read LIVE off the same `shellEnv`-over-`inheritEnv` merge each exec gets; ABSENT when the
+     *  child gets none (an allowlist that withholds it: `~` then falls back to passwd while `$HOME` is empty — two values, no single home, home-relative operands stay fail-closed). Residual: a per-exec `env.HOME` override. */
+    get homeDir(): string | undefined;
     private shellPath?;
     private shellEnv?;
     private inheritEnv;

package/dist/engine/execution-env/node-execution-env.js

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { closeSync, constants, createReadStream, mkdtempSync, openSync, readSync, statSync, truncateSync, unlinkSync } from "node:fs";
 import { access, appendFile, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, realpath, rename, rm, unlink, writeFile, } from "node:fs/promises";
-import { homedir, tmpdir } from "node:os";
+import { tmpdir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { ExecutionError, err, FileError, ok, toError, } from "../harness/types.js";
@@ -284,7 +284,9 @@ export function openSpoolPair(base) {
 }
 export class NodeExecutionEnv {
     cwd;
-    homeDir = homedir();
+    get homeDir() {
+        return getShellEnv(this.inheritEnv, this.shellEnv, undefined, () => { }).HOME;
+    }
     shellPath;
     shellEnv;
     inheritEnv;