@sema-agent/core 7.52.0 → 7.54.0

package/dist/core/read-only-shell.js

@@ -1,5 +1,5 @@
 import { posix } from "node:path";
-import { readShellCommand } from "./shell-lexer.js";
+import { lexedWordOf, readShellCommand } from "./shell-run-candidates.js";
 import { descriptorsOfPlan, newLineDescriptors, standardDeviceUnrebound } from "../tools/fs/shell-read-device.js";
 import { planShellReads } from "../tools/fs/shell-read-plan.js";
 import { writesOnlyStandardDevices } from "../tools/fs/shell-read-write-targets.js";
@@ -33,8 +33,7 @@ const TABLE_ROWS = Object.entries(READ_ONLY_COMMAND_TABLE)
     .map(([key, row]) => ({ words: key.split(" "), row }))
     .sort((a, b) => b.words.length - a.words.length);
 const READING_REDIRECTS = new Set(["<", "<<", "<<-", "<&", "<<<"]);
-const LITERAL_ASSIGNMENT = /^([A-Za-z_][A-Za-z0-9_]*)\+?=(?:"[^"$`\\]*"|'[^']*'|[A-Za-z0-9_./:+-]*)$/;
-const ASSIGNMENT_NAME = /^([A-Za-z_][A-Za-z0-9_]*)(?:\[[^\]]*\])?\+?=/;
+const BARE_VALUE_CHARACTERS = /^[A-Za-z0-9_./:+-]*$/;
 const FLAG_WORD = /^-[a-zA-Z0-9_-]/;
 const NUMBER_LITERAL = /^[-+]?(0[xX][0-9a-fA-F]+|[0-9]+#[0-9a-zA-Z]+|[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)$/;
 const PRINTF_LENGTH = "[lLhqjzZt]*";
@@ -90,20 +89,42 @@ export function readOnlyLineObjection(command, cwd) {
     return lineStructureObjection(shape) ?? (changesDirectoryBeforeGit(shape, cwd) ? CD_GIT_REASON : undefined);
 }
 function expansionKind(w) {
+    const lexed = lexedWordOf(w);
+    if (lexed !== undefined && (lexed.unresolved !== undefined || lexed.quotedSpans.some((s) => s.by === "$'")))
+        return "variable";
     if (w.expands === false)
         return "none";
-    if (/[$`]|[<>]\(/.test(w.raw))
+    if (lexed === undefined)
+        return "variable";
+    const computed = (e) => VALUE_EXPANSIONS.has(e.kind) || e.inner?.some(computed) === true;
+    if (lexed.expansions.some((p) => p.expansion !== undefined && computed(p.expansion)))
         return "variable";
     if (w.expands === "many")
         return "glob";
     return "none";
 }
+const VALUE_EXPANSIONS = new Set(["parameter", "command", "process", "arithmetic"]);
 function leadingAssignmentCount(argv) {
     let k = 0;
-    while (k < argv.length && ASSIGNMENT_NAME.test(argv[k].raw))
+    while (k < argv.length && lexedWordOf(argv[k])?.assignment?.bare === true)
         k++;
     return k;
 }
+function literalAssignmentValue(a) {
+    if (a.subscript !== undefined || a.form !== "scalar" || a.value.unresolved !== undefined || a.value.expansions.length > 0)
+        return false;
+    const [only, ...rest] = a.value.pieces;
+    if (only === undefined)
+        return true;
+    if (rest.length > 0 || only.literal === undefined)
+        return false;
+    if (only.quotedBy === undefined)
+        return BARE_VALUE_CHARACTERS.test(only.literal);
+    const oneRegion = a.value.raw.length === only.literal.length + 2;
+    if (only.quotedBy === "'")
+        return oneRegion;
+    return only.quotedBy === '"' && oneRegion && !/[$`\\]/.test(only.literal);
+}
 function peelBuiltinPrefix(words) {
     let t = words;
     for (;;) {
@@ -142,11 +163,11 @@ function segmentVerdict(seg, line, bindings) {
     }
     const k = leadingAssignmentCount(seg.argv);
     for (const w of seg.argv.slice(0, k)) {
-        const m = LITERAL_ASSIGNMENT.exec(w.raw);
-        if (m === null)
+        const a = lexedWordOf(w).assignment;
+        if (!literalAssignmentValue(a))
             return NOT(`the assignment \`${w.raw}\` is not a literal value`);
-        if (!ENV_NAMES.has(m[1]))
-            return NOT(`the environment variable \`${m[1]}\` can alter what a program does`);
+        if (!ENV_NAMES.has(a.name))
+            return NOT(`the environment variable \`${a.name}\` can alter what a program does`);
     }
     const run = seg.argv.slice(k);
     if (run.length === 0)

package/dist/core/remote-env.d.ts

@@ -66,6 +66,19 @@ export interface WorkspaceHandle {
      */
     deviceId?: string;
 }
+/** The one list of what a {@link WorkspaceHandle} is: every member the interface declares. */
+export declare const WORKSPACE_HANDLE_MEMBERS: ReadonlyArray<keyof WorkspaceHandle>;
+/**
+ * A frozen copy of `handle` holding exactly the declared members it carries as strings: shallow-frozen, which is deep here
+ * because every member is a string (a decoration or a function member of the source never reaches the copy), and no
+ * structured-clone step to fail on an exotic value. Each member is read the way the engine's own handle comparison reads it.
+ *
+ * ONE copy per live handle: a second call for the same object answers the copy the first call made (the members are read
+ * once), so every place the engine hands a checkpointed handle to the outside — the resume preflight's facts, the env
+ * factory's {@link ExecutionEnvFactoryContext.resumeWorkspace}, the restore's {@link VmLifecycleOptions.priorHandle} —
+ * delivers the same object, not three renderings of one fact.
+ */
+export declare function frozenHandleCopy(handle: WorkspaceHandle): Readonly<WorkspaceHandle>;
 /**
  * A reference to a secret injected at {@link RemoteExecutionEnv.connect}/{@link RemoteExecutionEnv.postResumeInit}
  * time (design/48 §5 gap 7) — never baked into the image. The control plane resolves {@link ref} to a value out of
@@ -114,8 +127,12 @@ export interface VmLifecycleOptions {
      * handle (never echo `priorHandle.mountPath` unhonored) — the engine compares the two and surfaces a
      * divergence observation. Absent on non-resume ops and from pre-1.360 engines (adapters treat absence
      * as the legacy current-config behavior).
+     *
+     * A frozen copy holding exactly the declared members ({@link WORKSPACE_HANDLE_MEMBERS}) the checkpoint row carries
+     * as strings — the SAME object the env factory's {@link ExecutionEnvFactoryContext.resumeWorkspace} was, for the
+     * same row — not the stored row's own object: writing to it throws, and a decoration on the stored handle is absent.
      */
-    priorHandle?: WorkspaceHandle;
+    priorHandle?: Readonly<WorkspaceHandle>;
 }
 /**
  * One chunk streamed from {@link RemoteExecutionEnv.execStream} (design/48 §5 gap 3, council BUG#3). A run is a
@@ -494,6 +511,29 @@ export interface ExecutionEnvFactoryContext {
      * already shares the parent env (and its cwd).
      */
     parentCwd?: string;
+    /**
+     * design/380 O1 delivery fence — the workspace a DURABLE RESUME leg is rebuilding: a frozen copy of the
+     * {@link WorkspaceHandle} the checkpoint row recorded at suspend, holding exactly the members a handle declares
+     * ({@link WORKSPACE_HANDLE_MEMBERS}) that the row carries as strings. Present ONLY on that leg — the key is
+     * absent (not an `undefined` value) on every fresh run, and on a resume whose row recorded no workspace
+     * handle. Mutating the copy reaches nothing the engine reads.
+     *
+     * A factory bound to a target (the device lane) **MUST** mint the env on the device
+     * `resumeWorkspace.deviceId` names and, when it cannot (offline, busy, the placement moved to another
+     * device), **THROW** a typed refusal. It **MUST NOT** connect some other device and leave the engine to
+     * notice, and it **MUST NOT** look the current binding up afresh from {@link placementRootSessionId} for
+     * this leg. A row recorded without `deviceId` (a non-device lane, or a row older than the field) states no
+     * device to honor; the factory then follows its ordinary routing.
+     *
+     * The minted env's `workspaceHandle()` **MUST** report the device its connection actually reached; it is
+     * never copied from `resumeWorkspace`. The engine's comparison of that report against the row (`provider`
+     * equal; `deviceId` equal whenever the row carries one) stays as the receipt check and TRUSTS the report: a
+     * factory that connected elsewhere and reports so is refused (`resume.env_failed`), only after the wrong
+     * connection was made, but one that echoes the fence while connecting elsewhere defeats its own protection
+     * and passes. The fence moves no refusal earlier than it was: it runs after the claim, so what a deployment
+     * can still catch BEFORE the claim is `RunnerDeps.resumePreflight` alone.
+     */
+    resumeWorkspace?: Readonly<WorkspaceHandle>;
 }
 /**
  * A **trusted control-plane** factory that mints a per-task {@link ExecutionEnv} (design/48 §5 answers core

package/dist/core/remote-env.js

@@ -1,3 +1,21 @@
+const WORKSPACE_HANDLE_MEMBER_TABLE = { sandboxId: 1, provider: 1, mountPath: 1, snapshotId: 1, sessionToken: 1, restoreMode: 1, deviceId: 1 };
+export const WORKSPACE_HANDLE_MEMBERS = Object.keys(WORKSPACE_HANDLE_MEMBER_TABLE);
+const FROZEN_COPY_OF = new WeakMap();
+export function frozenHandleCopy(handle) {
+    const known = FROZEN_COPY_OF.get(handle);
+    if (known !== undefined)
+        return known;
+    const copy = {};
+    for (const member of WORKSPACE_HANDLE_MEMBERS) {
+        const value = handle[member];
+        if (typeof value === "string")
+            copy[member] = value;
+    }
+    const frozen = Object.freeze(copy);
+    if (typeof handle === "object" && handle !== null)
+        FROZEN_COPY_OF.set(handle, frozen);
+    return frozen;
+}
 export const RETRYABLE_REMOTE_ERROR_CODES = [
     "auth_transient",
     "connect_failed",

package/dist/core/resume-startup-cause.d.ts

@@ -23,6 +23,7 @@
  *    unsafe payload, an input the constraints refuse): correct the decision and resubmit.
  */
 import type { AssertAllKeysHandled } from "./ask-origin.js";
+import type { TerminalFailureDetail } from "./terminal-cause.js";
 /**
  * design/80 D-1: why a consumed checkpoint was {@link import("./checkpoint-store.js").CheckpointStore.reopen | reopened}
  * (resolved → pending). The reason drives re-resume validation (§3 invariant #1): an `env_failed` reopen is a SYSTEM
@@ -51,6 +52,23 @@ export type ResumeStartupCause = (typeof RESUME_STARTUP_CAUSES)[number];
 /** The cause a resume failure's code names; `undefined` when the code is absent or the table does not
  *  name it. Every `config.*` code is a configuration door's refusal. */
 export declare function resumeStartupCauseOf(code: string | undefined): ResumeStartupCause | undefined;
+/**
+ * The members of a resume refusal's `detail` the parked-resume receipt carries beside its `cause` — the three a
+ * {@link import("./checkpoint-store.js").CheckpointError} states where its `code` alone does not say which input or which arm refused:
+ * `code` (on `checkpoint.config_refused`: prepare's own code, the word a fresh run of the same bad config reports), `field` (which
+ * input carries the refusal) and `reason` (which arm fired). Their words are those families' own; the receipt adds no word of its own.
+ */
+export declare const RESUME_REFUSAL_MEMBERS: readonly ["code", "field", "reason"];
+/** {@link RESUME_REFUSAL_MEMBERS} as the receipt carries them: each a string, each present only when the failure stated it. */
+export type ResumeRefusalDetail = {
+    readonly [K in (typeof RESUME_REFUSAL_MEMBERS)[number]]?: string;
+};
+/**
+ * The refusal members a failed resume stated, read from the failure's coded account ({@link TerminalFailureDetail}, `kind: "coded"`:
+ * the `detail` its throw site stated) — never from its sentence. `undefined` when the failure carries no coded account or none of
+ * the three members is a string in it.
+ */
+export declare function resumeRefusalDetailOf(account: TerminalFailureDetail | undefined): ResumeRefusalDetail | undefined;
 declare const REOPEN_REASON_OF_CAUSE: {
     readonly environment: "env_failed";
     readonly session_gone: "env_failed";

package/dist/core/resume-startup-cause.js

@@ -21,6 +21,18 @@ export function resumeStartupCauseOf(code) {
         return undefined;
     return CAUSE_OF_CODE.get(code) ?? (code.startsWith("config.") ? "configuration" : undefined);
 }
+export const RESUME_REFUSAL_MEMBERS = Object.freeze(["code", "field", "reason"]);
+export function resumeRefusalDetailOf(account) {
+    if (account === undefined || account.kind !== "coded")
+        return undefined;
+    const out = {};
+    for (const member of RESUME_REFUSAL_MEMBERS) {
+        const value = Object.hasOwn(account.detail, member) ? account.detail[member] : undefined;
+        if (typeof value === "string")
+            out[member] = value;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 const REOPEN_REASON_OF_CAUSE = {
     environment: "env_failed",
     session_gone: "env_failed",

package/dist/core/retention.js

@@ -1,3 +1,4 @@
+import { describeRejectedValue } from "./tool-search-setting.js";
 export const RETENTION_CASCADE_DOMAINS = Object.freeze(["checkpoints", "session-trees", "orphan-tool-results"]);
 export const RETENTION_CASCADE_EXEMPT = Object.freeze(["session-pollution", "session-capture-optout", "lineage.json"]);
 function codedError(code, message) {
@@ -7,8 +8,12 @@ function codedError(code, message) {
 }
 export function assertRetentionCapability(input) {
     const { policy, locked, stores } = input;
+    const declared = policy;
+    if (declared !== undefined && (typeof declared !== "object" || declared === null || Array.isArray(declared))) {
+        throw codedError("config.retention_policy", `retentionPolicy must be an object carrying maxAgeDays (got ${declared === null ? "null" : Array.isArray(declared) ? "an array" : typeof declared}).`);
+    }
     if (policy !== undefined && (!Number.isFinite(policy.maxAgeDays) || policy.maxAgeDays < 0)) {
-        throw codedError("config.retention_policy", `retentionPolicy.maxAgeDays must be a finite non-negative number of days (got ${String(policy.maxAgeDays)}).`);
+        throw codedError("config.retention_policy", `retentionPolicy.maxAgeDays must be a finite non-negative number of days (got ${describeRejectedValue(policy.maxAgeDays)}).`);
     }
     const declaredRetention = (name, store) => {
         const r = store.retention;
@@ -19,7 +24,7 @@ export function assertRetentionCapability(input) {
         throw codedError("config.retention_capability", `store "${name}" declares an unparseable retention value ${JSON.stringify(r)} — expected "managed" or "none".`);
     };
     const declarations = stores
-        .filter((s) => s.store !== undefined)
+        .filter((s) => s.store !== undefined && s.store !== null)
         .map(({ name, store }) => ({ name, retention: declaredRetention(name, store) }));
     if (!locked || policy === undefined)
         return;

package/dist/core/retired-keys.d.ts

@@ -46,7 +46,13 @@ export declare const RETIRED_SHELL_READ_BOUNDARY_KEYS: Readonly<Record<string, s
  *  decision that carries one is denied in the engine's own words, never read without it: the type retires a member only where
  *  a decision is a literal in an annotated position, and a `check` whose return type is inferred still compiles with it. */
 export declare const RETIRED_DECISION_MEMBERS: Readonly<Record<string, string>>;
-/** The `ToolPolicy` door ({@link RETIRED_TOOL_POLICY_KEYS}); `undefined` is no policy. */
-export declare function assertNoRetiredToolPolicyKeys(policy: object | undefined): void;
+/**
+ * The `ToolPolicy` door — every policy the engine installs passes it (a task's or deployment's seat, a combined member, an inherited
+ * constraint): `undefined` (or `null`, the seat's other absence spelling) is no policy; a value that is not an object whose `check`
+ * is a function is no policy either, and refuses by name (`config.invalid_argument`, `detail.field: "ToolPolicy"`) — a policy the
+ * engine cannot call is never installed as if it were absent, which would run the leg with nothing the deployment meant to apply;
+ * a retired member refuses by name ({@link RETIRED_TOOL_POLICY_KEYS}).
+ */
+export declare function assertNoRetiredToolPolicyKeys(policy: unknown): void;
 /** The `ShellReadBoundary` door ({@link RETIRED_SHELL_READ_BOUNDARY_KEYS}). */
 export declare function assertNoRetiredShellReadBoundaryKeys(boundary: object): void;

package/dist/core/retired-keys.js

@@ -45,8 +45,19 @@ export const RETIRED_DECISION_MEMBERS = Object.freeze({
     guard: 'write `guards: ["<word>"]` instead (the same five words, as a list: one ask may stand on several integrity guards)',
 });
 export function assertNoRetiredToolPolicyKeys(policy) {
-    if (policy !== undefined)
+    if (policy === undefined || policy === null)
+        return;
+    const isRecord = typeof policy === "object" && !Array.isArray(policy);
+    if (isRecord)
         assertNoRetiredKeys(policy, RETIRED_TOOL_POLICY_KEYS, "ToolPolicy");
+    const check = isRecord ? policy.check : undefined;
+    if (typeof check !== "function") {
+        const got = typeof policy !== "object" ? typeof policy : Array.isArray(policy) ? "an array" : `an object whose check is ${check === null ? "null" : typeof check}`;
+        const e = new Error(`ToolPolicy must be an object whose \`check\` is a function (got ${got}) — a policy the engine cannot call is refused rather than run as no policy; omit the seat for none.`);
+        e.code = "config.invalid_argument";
+        e.detail = { field: "ToolPolicy" };
+        throw e;
+    }
 }
 export function assertNoRetiredShellReadBoundaryKeys(boundary) {
     assertNoRetiredKeys(boundary, RETIRED_SHELL_READ_BOUNDARY_KEYS, "ShellReadBoundary");

package/dist/core/roles.js

@@ -1,11 +1,29 @@
 import { selectModel } from "./select-model.js";
 import { MODEL_ROLES } from "./types.js";
 export { MODEL_ROLES } from "./types.js";
+function catalogModel(ref, models) {
+    const m = models != null && (typeof models === "object" || typeof models === "function") && Object.hasOwn(models, ref) ? models[ref] : undefined;
+    return m || undefined;
+}
+function modelBindingRefusal(seat, reason, message) {
+    const e = new Error(message);
+    e.code = "config.unknown_role";
+    e.detail = { field: seat, reason };
+    return e;
+}
+function bindingShown(value) {
+    if (typeof value === "string")
+        return JSON.stringify(value.length > 80 ? `${value.slice(0, 80)}…` : value);
+    return value === null ? "null" : Array.isArray(value) ? "a list" : `a ${typeof value}`;
+}
+function unknownModelRefRefusal(ref, seat) {
+    return modelBindingRefusal(seat, "unknown_model_ref", `Unknown model ref ${bindingShown(ref)} in ${seat}. Provide it in RunnerDeps.models or pass a Model object.`);
+}
 export function resolveModel(ref, models) {
     if (typeof ref !== "string") {
         return ref;
     }
-    const m = models !== undefined && Object.hasOwn(models, ref) ? models[ref] : undefined;
+    const m = catalogModel(ref, models);
     if (!m) {
         throw new Error(`Unknown model ref "${ref}". Provide it in RunnerDeps.models or pass a Model object.`);
     }
@@ -33,7 +51,19 @@ export function expandTiers(models, tiers) {
     out[TIER_ALIAS_VIA] = aliasVia;
     const bound = (name) => {
         const b = Object.hasOwn(tiers, name) ? tiers[name] : undefined;
-        return b === undefined ? undefined : resolveModel(b, models);
+        if (b === undefined)
+            return undefined;
+        const seat = `tiers.${name}`;
+        if (typeof b === "string") {
+            const held = catalogModel(b, models);
+            if (held === undefined)
+                throw unknownModelRefRefusal(b, seat);
+            return held;
+        }
+        if (typeof b !== "object" || b === null || Array.isArray(b)) {
+            throw modelBindingRefusal(seat, "not_a_model_ref", `${seat} is ${bindingShown(b)}, not a model reference — a tier binds a catalog model name or a Model object.`);
+        }
+        return b;
     };
     const ownKey = (k) => models !== undefined && Object.hasOwn(models, k) && Boolean(models[k]);
     const landing = (t, self) => {
@@ -131,13 +161,16 @@ const FALLBACK = {
     classifier: ["summarize", "default"],
     consolidate: ["summarize"],
 };
-function specParts(s) {
+function specParts(s, seat = "a role seat") {
     if (s == null) {
         return {};
     }
     if (typeof s === "string") {
         return { model: s };
     }
+    if (typeof s !== "object" && typeof s !== "function") {
+        throw modelBindingRefusal(seat, "not_a_model_ref", `${seat} is ${bindingShown(s)}, not a model reference — a role binds a catalog model name, a Model object or a { model, select, thinking, systemPrompt } record.`);
+    }
     if ("id" in s && "api" in s) {
         return { model: s };
     }
@@ -191,12 +224,17 @@ function mergeRoles(base, over) {
     }
     return out;
 }
-function partsModel(parts, models) {
+function partsModel(parts, models, seat = "a role seat") {
     if (parts.model) {
         return resolveModel(parts.model, models);
     }
     if (parts.select) {
-        return selectModel(models ?? {}, parts.select);
+        const needs = parts.select.needs;
+        if (needs != null && !Array.isArray(needs)) {
+            throw modelBindingRefusal(`${seat}.select`, "not_a_model_ref", `${seat}.select.needs is ${bindingShown(needs)}, not a list of capabilities (vision / reasoning).`);
+        }
+        const held = models != null && typeof models === "object" ? Object.values(models).filter(Boolean) : [];
+        return selectModel(held, parts.select);
     }
     return undefined;
 }
@@ -204,7 +242,7 @@ export function resolveTaskModel(spec, deps) {
     const start = spec.modelRole ?? "default";
     assertKnownRole(start, "modelRole");
     if (spec.model) {
-        const startParts = specParts(mergeRoles(deps.roles, spec.roles)[start]);
+        const startParts = specParts(mergeRoles(deps.roles, spec.roles)[start], `roles.${start}`);
         return {
             model: resolveModel(spec.model, deps.models),
             modelRef: spec.model,
@@ -213,10 +251,10 @@ export function resolveTaskModel(spec, deps) {
         };
     }
     const merged = mergeRoles(deps.roles, spec.roles);
-    const startSystemPrompt = specParts(merged[start]).systemPrompt;
+    const startSystemPrompt = specParts(merged[start], `roles.${start}`).systemPrompt;
     for (const role of [start, ...FALLBACK[start]]) {
-        const parts = specParts(merged[role]);
-        const fromParts = partsModel(parts, deps.models);
+        const parts = specParts(merged[role], `roles.${role}`);
+        const fromParts = partsModel(parts, deps.models, `roles.${role}`);
         const model = fromParts ?? roleTierModel(role, deps.models);
         if (model) {
             const modelRef = fromParts !== undefined ? (parts.model ?? model) : (ROLE_TIER_DEFAULTS[role] ?? model);
@@ -227,5 +265,17 @@ export function resolveTaskModel(spec, deps) {
 }
 export function roleModelIfSet(role, spec, deps) {
     const merged = mergeRoles(deps.roles, spec.roles);
-    return partsModel(specParts(merged[role]), deps.models) ?? roleTierModel(role, deps.models);
+    const seat = `roles.${role}`;
+    const parts = specParts(merged[role], seat);
+    const named = parts.model;
+    if (named) {
+        if (typeof named === "string") {
+            if (catalogModel(named, deps.models) === undefined)
+                throw unknownModelRefRefusal(named, seat);
+        }
+        else if (typeof named !== "object" || Array.isArray(named)) {
+            throw modelBindingRefusal(seat, "not_a_model_ref", `${seat}.model is ${bindingShown(named)}, not a model reference — a role binds a catalog model name or a Model object.`);
+        }
+    }
+    return partsModel(parts, deps.models, seat) ?? roleTierModel(role, deps.models);
 }

package/dist/core/rule-lane-reads.js

@@ -65,7 +65,7 @@ export function normalizeOrgGateVerdict(answer, unreadable) {
     if ((behavior !== "deny" && behavior !== "ask") || typeof rule !== "string")
         return clean({ status: "unavailable", disclosures: [unreadable] });
     const reason = ownDataValue(verdict, "unreadable");
-    const unreadableCell = behavior === "ask" && typeof reason === "string" ? { unreadable: reason } : {};
+    const unreadableCell = typeof reason === "string" ? { unreadable: reason } : {};
     return clean({ status: "available", verdict: clean({ behavior: behavior, rule, ...unreadableCell }), ...revisionCell });
 }
 function copiedDenial(raw, ruleTexts) {

package/dist/core/runner/approval-feedback.d.ts

@@ -0,0 +1,46 @@
+/**
+ * What the approving person wrote on the card ({@link ResumeOutcome} `policy_ask` `allow` `feedback`) — the one place that
+ * says what counts as written, which decide may carry it, and how it joins the resume continuation.
+ *
+ * ONE READING of "did the person write anything" ({@link writtenFeedback}): the text with the whitespace the card's input does
+ * not keep removed, or nothing when that leaves nothing. The pre-CAS checks and the continuation both ask it, so they cannot
+ * disagree about a blank value. (A deny's `reason` keeps its own rule, `decidersNote`: only `""` is blank there.)
+ *
+ * The words ride the resume continuation user message — the first message after the batch's tool results, once the batch's
+ * unanswered siblings have settled — as a user-lane range of their own: outside every engine segment, so a derived view reads
+ * them as user speech; verbatim, no fence, no wrapper sentence, no length bound. They are owed with the rest of the
+ * continuation: when the batch parks again before the prompt lands they ride the new row as its last parked steer.
+ */
+import { type PendingSteerEntry, type ResumeOutcome } from "../checkpoint-store.js";
+type PolicyAsk = Extract<ResumeOutcome, {
+    gate: "policy_ask";
+}>;
+/** The words as the model is to read them, or `undefined` when nothing was written (absent, empty, whitespace-only). */
+export declare function writtenFeedback(feedback: string | undefined): string | undefined;
+/**
+ * Pre-CAS: a WRITTEN feedback is the allow arm's, a person's, and free of the `<system-reminder>` tag (opening or closing — the one
+ * judge `sanitizeUntrustedText`, the same rule a deny's `reason` is held to, applied here by the same call). Each is refused
+ * (`checkpoint.invalid_outcome`, the row stays pending for a well-formed decide) rather than dropped or delivered as something it
+ * is not: a deny's words are `reason`, and a machine's text must never reach the model as the user's. The twin is the captured
+ * plain data (its text already held to the string domain by the capture), never the caller's object.
+ */
+export declare function refuseUnfitFeedback(twin: PolicyAsk): void;
+/** The words this resume is to deliver: a person's `allow` carrying a written feedback (the pre-CAS checks have run), else `undefined`. */
+export declare function approvalWordsOf(outcome: ResumeOutcome): string | undefined;
+/**
+ * The continuation with the words as its last range. The separator glue before them is engine bytes (its own segment), so the
+ * stored message's user-lane range is exactly the words. Appends to `engineSegments` in place; the caller owns both.
+ */
+export declare function withApprovalWords(continuation: string, engineSegments: Array<{
+    start: number;
+    end: number;
+}>, words: string): string;
+/**
+ * The words as the continuation's owed content: the last parked steer, an untrusted one (the carrier that exists for an owed instruction).
+ * The frame is remembered by identity ({@link isApprovalWordsFrame}) — never by a member, which the steer store would refuse as an unknown
+ * key — so the owed account can count it as what it is (`detail.kind: "approval_feedback"`) and tell a recoverable retry from a loss.
+ */
+export declare function owedApprovalWords(words: string | undefined, inputId: string): Array<Omit<PendingSteerEntry, "seq">>;
+/** Whether `frame` is one {@link owedApprovalWords} minted. */
+export declare function isApprovalWordsFrame(frame: object): boolean;
+export {};

package/dist/core/runner/approval-feedback.js

@@ -0,0 +1,41 @@
+import { CheckpointError } from "../checkpoint-store.js";
+import { sanitizeUntrustedText, sentinelTagRefusal } from "../untrusted-text.js";
+export function writtenFeedback(feedback) {
+    const trimmed = feedback?.trim();
+    return trimmed === undefined || trimmed === "" ? undefined : trimmed;
+}
+export function refuseUnfitFeedback(twin) {
+    const words = writtenFeedback(twin.feedback);
+    if (words === undefined)
+        return;
+    if (twin.decision !== "allow") {
+        throw new CheckpointError("checkpoint.invalid_outcome", "resume carried `feedback` on a `deny` — feedback is the approving person's words on an `allow` (a denial's words are `reason`); refusing rather than dropping it silently, the checkpoint stays pending");
+    }
+    const byPerson = twin.hostDecision.decidedBy === "person";
+    if (!byPerson) {
+        throw new CheckpointError("checkpoint.invalid_outcome", `resume carried \`feedback\` on a decide made by "${twin.hostDecision.decidedBy}" — feedback is delivered to the model as the user's own words, which only a person's decide can be; refusing rather than attributing a machine's text to the user, the checkpoint stays pending`);
+    }
+    if (sanitizeUntrustedText(words) !== words) {
+        throw new CheckpointError("checkpoint.invalid_outcome", sentinelTagRefusal("resume allow feedback"));
+    }
+}
+export function approvalWordsOf(outcome) {
+    return outcome.gate === "policy_ask" && outcome.decision === "allow" ? writtenFeedback(outcome.feedback) : undefined;
+}
+export function withApprovalWords(continuation, engineSegments, words) {
+    const glueStart = continuation.length;
+    const withGlue = `${continuation}\n\n`;
+    engineSegments.push({ start: glueStart, end: withGlue.length });
+    return withGlue + words;
+}
+const APPROVAL_WORDS_FRAMES = new WeakSet();
+export function owedApprovalWords(words, inputId) {
+    if (words === undefined)
+        return [];
+    const frame = { text: words, trusted: false, inputId };
+    APPROVAL_WORDS_FRAMES.add(frame);
+    return [frame];
+}
+export function isApprovalWordsFrame(frame) {
+    return APPROVAL_WORDS_FRAMES.has(frame);
+}

package/dist/core/runner/compaction-call-options.d.ts

@@ -23,13 +23,13 @@ import { type CompactionSettings } from "../../internal/harness.js";
  * because reading it at the moment of the pass — not at prepare — is the whole of what it states.
  */
 /**
- * Opt-in working-file attachments (LONGRUN-2 / CC 198 post-compact restore parity).
+ * The post-compaction restore (LONGRUN-2; the reference's post-compact file restore, cli296.js:249523 `attachments`).
  *
  * CC parity: post-compact file re-read is DEFAULT ON (CC hard-codes it;
  * LONGRUN-2 measured ≈2.3 extra read round-trips per compaction without it). `false` opts out; an
  * object customizes caps. Selection set = most recently READ (CC readFileState semantics) with a
- * modified-files fallback inside maybeCompact. Returns `undefined` when attachments are off or the
- * task has no hands (no `readTaskFile` ⇒ nothing can be re-read).
+ * modified-files fallback inside maybeCompact. Returns `undefined` when the restore is off or the
+ * task has no hands (no `compactionRestore` ⇒ nothing can be re-read).
  */
 export declare function buildWorkingFileAttachments(spec: TaskSpec, prepared: Prepared): MaybeCompactOptions["workingFileAttachments"];
 /**

package/dist/core/runner/compaction-call-options.js

@@ -3,10 +3,10 @@ import { buildToolResultRef, OFFLOAD_TOOL_NAME, PERSISTED_OUTPUT_PREFIX, toolRes
 import { compactionEnabled, contextOverlayFor } from "../context-settings.js";
 import { DEFAULT_COMPACTION_SETTINGS } from "../../internal/harness.js";
 export function buildWorkingFileAttachments(spec, prepared) {
-    if (spec.compaction?.attachWorkingFiles === false || !prepared.readTaskFile)
+    if (spec.compaction?.attachWorkingFiles === false || !prepared.compactionRestore)
         return undefined;
     return {
-        readFile: prepared.readTaskFile,
+        ...prepared.compactionRestore,
         ...(prepared.recentlyReadFiles ? { recentlyReadFiles: prepared.recentlyReadFiles } : {}),
         ...(prepared.normalizeAttachmentPath ? { normalizePath: prepared.normalizeAttachmentPath } : {}),
         ...(prepared.isDedupStubResult ? { isDedupStubResult: prepared.isDedupStubResult } : {}),