@sema-agent/core 7.53.0 → 7.54.0

package/dist/core/permission-rule-session.js

@@ -1,10 +1,10 @@
-import { readRowBehavior } from "./permission-rule-model.js";
+import { readRowBehavior, RULE_ADD_ORIGINS } from "./permission-rule-model.js";
 import { isValidConsentScope, normalizePersistedRule } from "./permission-rule-store.js";
 function isValidOverlayAdd(add) {
     const a = add;
     if (typeof a?.dot?.actor !== "string" || a.dot.actor === "" || typeof a.dot.counter !== "number" || !Number.isFinite(a.dot.counter))
         return false;
-    if (a.origin !== "user" && a.origin !== "imported-cc" && a.origin !== "starter")
+    if (!RULE_ADD_ORIGINS.some((word) => a.origin === word))
         return false;
     return typeof a.createdAt === "string";
 }

package/dist/core/permission-rule-store.d.ts

@@ -45,6 +45,7 @@ import type { PersistedRule, RuleAdd, RuleDot, RuleScope, RuleTombstone } from "
 import { type RuleBehavior } from "./permission-rule-model.js";
 import type { RuleSyncDropReason, RuleQuarantineReason } from "./governance-codes.js";
 import type { StoreDurability, StoreFidelity } from "./checkpoint-store.js";
+import type { AssertAllKeysHandled } from "./ask-origin.js";
 /** One store read: the rules as persisted, their tombstones, and the revision they were read at. */
 export interface StoredRules {
     /** Rules with their FULL add sets — tombstoned dots already removed by the backend on read. */
@@ -92,6 +93,13 @@ export type RuleOwner = {
 } | {
     kind: "local-owner";
 };
+/** The owner discriminants as a value: the `kind` words of {@link RuleOwner}, both directions fenced at compile time
+ *  ({@link RuleOwnerKindsCoverEveryArm} / {@link RuleOwnerArmsCoverEveryKind}). */
+export declare const RULE_OWNER_KINDS: readonly ["principal", "local-owner"];
+/** Compile fence: an arm whose `kind` is not in {@link RULE_OWNER_KINDS} turns the argument into that word. */
+export type RuleOwnerKindsCoverEveryArm = AssertAllKeysHandled<Exclude<RuleOwner["kind"], (typeof RULE_OWNER_KINDS)[number]>>;
+/** Compile fence, the other direction: a word in {@link RULE_OWNER_KINDS} that no arm carries. */
+export type RuleOwnerArmsCoverEveryKind = AssertAllKeysHandled<Exclude<(typeof RULE_OWNER_KINDS)[number], RuleOwner["kind"]>>;
 /** Do two owners name the same bucket? */
 export declare function sameRuleOwner(a: RuleOwner, b: RuleOwner): boolean;
 /** Resolves one owner's durable partition. `undefined` ⇒ a partition that reports zero rules. This is

package/dist/core/permission-rule-store.js

@@ -3,6 +3,7 @@ import { canonicalize } from "./canonical-json.js";
 import { escapeForDisclosure, isRuleBehavior, isRuleLive, parseRuleText } from "./permission-rule-model.js";
 import { thrownText } from "./thrown-value.js";
 import { validatePath } from "./effective-path-target.js";
+export const RULE_OWNER_KINDS = Object.freeze(["principal", "local-owner"]);
 export function sameRuleOwner(a, b) {
     return a.kind === "principal" ? b.kind === "principal" && a.principal === b.principal : b.kind === "local-owner";
 }

package/dist/core/permission-rule-sync.js

@@ -1,4 +1,4 @@
-import { escapeForDisclosure, isRuleBehavior, parseRuleText } from "./permission-rule-model.js";
+import { escapeForDisclosure, isRuleBehavior, parseRuleText, RULE_ADD_ORIGINS } from "./permission-rule-model.js";
 import { applyTombstones, errText, isProjectScopeRoot, joinFrontiers, joinRuleStates, normalizePersistedRule, readRuleWriteOutcome, ruleSyncVector, sameRuleIdentity, screenRuleSyncState, writerOf, } from "./permission-rule-store.js";
 import { emitTrace } from "./trace.js";
 export const PERMISSION_RULE_SYNC_PATH = "/v1/permission-rules/sync";
@@ -273,6 +273,7 @@ function pickScopeCaptured(v) {
 function pickScope(v) {
     return pickScopeCaptured(v).scope;
 }
+const isRuleAddOrigin = (v) => RULE_ADD_ORIGINS.some((word) => v === word);
 function pickAdd(v) {
     const a = v;
     const dot = pickDot(a?.dot);
@@ -280,7 +281,7 @@ function pickAdd(v) {
     const createdAt = a?.createdAt;
     if (dot === undefined)
         return undefined;
-    if (origin !== "user" && origin !== "imported-cc" && origin !== "starter")
+    if (!isRuleAddOrigin(origin))
         return undefined;
     if (typeof createdAt !== "string")
         return undefined;

package/dist/core/read-only-shell.d.ts

@@ -1,4 +1,4 @@
-import { type ShellCommandShape } from "./shell-lexer.js";
+import { type ShellCommandShape } from "./shell-run-candidates.js";
 import { type LineDescriptors } from "../tools/fs/shell-read-device.js";
 /** The reader's answer: read-only, or not — with the first reason the reading stopped on (a sentence a
  *  trace or a card can show; never adjudication input). */

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/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 } : {}),

package/dist/core/runner/contracts.d.ts

@@ -234,7 +234,7 @@ export interface FrameReceipt {
     text: string;
     /** Which frame this receipt settles. A boundary collector must not render a listing whose receipt is
      *  still pending (the frame is queued, not yet in the transcript). */
-    source: "git_status" | "agent_listing" | "skills_listing" | "date_change" | "output_style";
+    source: "git_status" | "agent_listing" | "skills_listing" | "date_change" | "output_style" | "approval_feedback";
     /** Runs inside the `message_end` walk (synchronous, never awaited): advances the run-local record
      *  and parks any session write for the next serialization point. */
     commit: (entryId: string) => void;
@@ -396,17 +396,15 @@ export interface Prepared {
     effectiveReadFace?: ContainmentFace;
     /** owned — the same observation on the WRITE seat (`TaskResult.effectiveWriteFace`). */
     effectiveWriteFace?: ContainmentFace;
-    /** The normalized deny ADDITIONS in force (deployment ∪ task ∪ checkpoint seed; built-ins
-     *  excluded), echoed on `TaskResult.effectiveReadDenyPatterns`. Present iff non-empty; a defensive
-     *  copy (the wide-scope working array stays the engine's own). */
+    /** The normalized deny ADDITIONS in force (deployment ∪ task ∪ checkpoint seed; built-ins excluded), echoed on
+     *  `TaskResult.effectiveReadDenyPatterns`. Present iff non-empty; a defensive copy (the working array stays the engine's). */
     effectiveReadDenyPatterns?: readonly import("../../tools/fs/read-deny.js").NormalizedReadDenyEntry[];
     /** The memory-visibility observation prepareMemory minted (echoed on
      *  `TaskResult.effectiveMemoryScopes`). Always present on a completed prepare (the memory-less
      *  states are their own values); the seat is optional only so a Prepared shape without the phase
      *  cannot fabricate one. */
     effectiveMemoryScopes?: import("../types.js").EffectiveMemoryScopes;
-    /** The per-task logical cwd ref when a real shell is mounted (else undefined). The Runner
-     *  reads `cwdRef.current` after each tool to detect a `cd` move and emit `workspace_changed`. */
+    /** The per-task logical cwd ref when a real shell is mounted (else undefined); read after each tool for `workspace_changed`. */
     cwdRef?: CwdRef;
     /** The root the hand tools resolve root-relative spellings against (present with hands; read-only hands included). */
     handsRoot?: string;
@@ -478,6 +476,11 @@ export interface Prepared {
      *  admission died with that leg, so the resumed bytes are judged (and admitted for their pre-spawn re-establishment)
      *  on THIS leg — a deny row found now vetoes, an operator's edit is judged on the `rejudge` seat. */
     shellReadCheck?: import("../../tools/fs/shell-read-check.js").ShellReadCheck;
+    crossBoundary?: {
+        readonly check: import("../cross-boundary-taint.js").CrossBoundaryCheck | undefined;
+        settle(): Promise<void>;
+        storeWaits(): number;
+    };
     /** The ORG adjudication face, re-resolved on a durable RESUME before an approved
      *  pending call executes. The resume path bypasses the harness gate by design (a human already
      *  adjudicated the checkpointed call), which is exactly where org policy skew is most likely: the
@@ -1004,56 +1007,42 @@ export interface Prepared {
      *  calls themselves never pass through the recorded seam (they ride the separate compaction-brain
      *  wrapper), so the snapshot is never polluted by a summary request. */
     lastBrainContext: () => CompactionForkContext | undefined;
-    /** Narrow workspace reader for compaction working-file attachments (LONGRUN-2): reads a task file
-     *  via the SAME env the hands ran against (so remote/k8s/E2B tasks read the container's tree, not
-     *  the control plane's). Present only when the hands are enabled — without an env there is no
-     *  workspace to re-read. null = unreadable (deleted/binary/transport error); callers skip it.
-     *  `{ withheld }` = the target matches the sensitive-path read deny list — the
-     *  attachment is deliberately withheld and the consumer must SAY so (an annotation, never a silent
-     *  skip: a silently missing attachment reads as "file gone", which is a different fact). */
-    readTaskFile?: (path: string) => Promise<string | null | {
-        withheld: {
-            pattern: string;
-        };
-    }>;
+    /** The post-compaction restore (`MaybeCompactOptions.workingFileAttachments.restore`): re-reads the candidates through
+     *  the leg's one file reader under the run's synthetic-Read judge — the user attachment's own path read — deduplicated
+     *  against the read state the summary leaves, and mints their attachment frames (`readCompactionRestore`); a file it
+     *  does not deliver — or whose frame the transcript does not take — is reported (`onError` phase `degraded`,
+     *  classification `attachment-read`). Present only with hands. */
+    compactionRestore?: Required<Pick<NonNullable<import("../auto-compaction.js").MaybeCompactOptions["workingFileAttachments"]>, "restore" | "undelivered">>;
     /** CC post-compact restore parity (2026-07-03): the task's READ files, most recent
-     *  first (from the hands' readFileState `lastReadAt` stamps). The compaction working-file
-     *  attachment prefers this over the modified set — CC restores what the model RECENTLY READ,
-     *  including untouched reference files. Present only with hands (same gate as readTaskFile).
-     *  Seeded entries are excluded — their content lives in the system-prompt lane, which
-     *  compaction never touches, so re-attaching them into the summary would be a duplicate. */
+     *  first (from the hands' readFileState `lastReadAt` stamps). The restore prefers this over the modified set — CC
+     *  restores what the model RECENTLY READ, including untouched reference files. Present only with hands.
+     *  Seeded entries are excluded — their content lives in the system-prompt lane, which compaction never touches. */
     recentlyReadFiles?: () => string[];
     /** Canonicalizes a raw (often relative, model-typed) path the
-     *  SAME way the hands toolkit does (`resolveKey` against the same containment root `readTaskFile`
-     *  uses), so `maybeCompact`'s kept-tail/instruction-source exclusions compare paths in the SAME
+     *  SAME way the hands toolkit does (`resolveKey` against the hands' containment root), so `maybeCompact`'s
+     *  kept-tail/instruction-source exclusions compare paths in the SAME
      *  coordinate `recentlyReadFiles()` already uses — without this a plain string match silently never
-     *  fires for the common relative-vs-canonical case. Present only with hands (same gate as
-     *  readTaskFile); absent there is no containment root to resolve against, and every path source is
-     *  already in the same raw coordinate anyway. */
+     *  fires for the common relative-vs-canonical case. Present only with hands; absent there is no
+     *  containment root to resolve against, and every path source is already in the same raw coordinate anyway. */
     normalizeAttachmentPath?: (raw: string) => Promise<string>;
     /** Recognizes the hands Read tool's own dedup-stub markers
      *  ({@link isReadDedupStubResult}), so `maybeCompact`'s kept-tail scan can tell a SUBSTANTIVE Read
      *  result from a stub hit whose original full transmission may already be summarized away. Present
-     *  only with hands (same gate as readTaskFile). */
+     *  only with hands. */
     isDedupStubResult?: (resultText: string) => boolean;
     /** Wired to `MaybeCompactOptions.onApplied` by every compaction lane (CC 220 clears readFileState at its
-     *  compaction landing site, @388663). Drops the non-seeded read-state entries
-     *  (the summary just replaced the Read results the dedup stubs point at) and re-registers the files
-     *  that were re-attached WHOLE. Present only with hands (same gate as readTaskFile).
-     *  `preserveReadState` carries the kept-tail-visible files that were
-     *  deliberately skipped for re-attachment — their existing entry must survive the clear too (same
-     *  reasoning as a seeded entry: the model's view of the file did not change).
+     *  compaction landing site, @388663). Drops every read-state entry the summary took out of view
+     *  (`readFileStateAfterSummary`); the restored files then re-register through their frames' own commits. Present
+     *  only with hands. `preserveReadState` carries the files the context the summary leaves still shows — their
+     *  existing entry survives the clear (the model's view of the file did not change).
      *
      *  SCOPE — read "every compaction lane" as exactly that and no wider. The request-layer
      *  stale-result pass takes a Read body off the wire with no compaction at all, and retires its own
      *  entries at its own landing site (`prepare-context-lane.ts`'s `landStaleResultClears`) through the
-     *  SAME function this seat calls, on its `tool-results-cleared` arm: ONE retirement mechanism, two
-     *  ways for content to leave. Taken as a claim about every SHRINK mechanism this sentence was true
+     *  SAME function this seat calls, on its `transmissions-gone` arm (the guard trim's dropped tool results and attachment frames too):
+     *  ONE retirement mechanism, several ways for content to leave. Taken as a claim about every SHRINK mechanism this sentence was true
      *  of the lanes it named and silently false of the one it did not. */
-    onCompactionApplied?: (attachedComplete: ReadonlyArray<{
-        path: string;
-        content: string;
-    }>, preserveReadState?: ReadonlyArray<string>) => void;
+    onCompactionApplied?: (preserveReadState: ReadonlyArray<string>) => void;
     /** The live diagnostics lane (present only when the gate passed — manager w/ registry +
      *  write hands + not opted out). `registry` is drained by runtask at turn boundaries; `nudge` is
      *  called (fire-and-forget) after each successful edit/write so the language server re-analyzes. */
@@ -1725,6 +1714,9 @@ export interface RunInternals {
         };
         contentSafety: import("../memory-engine/delegation-provenance.js").DelegationContentSafety;
     };
+    /** The run TREE's cross-boundary token — the tree's ONE state is reached from it by the engine alone: the spawning leg hands its
+     *  own down (the delegation and workflow lanes), so a bit any leg sets is read by every other at its next judgment; a root leg mints one. */
+    crossBoundaryTree?: import("../cross-boundary-taint.js").CrossBoundaryTreeToken;
     /**
      * The SESSION-scoped org-admission freeze for a SAME-SESSION continuation
      * that is NOT a checkpoint resume: a retained background child revived through the in-process resume