@sema-agent/core 7.54.1 → 7.56.0

package/dist/core/wiring-manifest.js

@@ -150,11 +150,16 @@ function readHandsFact(fact) {
     }
     return mounted ? { mounted } : { mounted, reason };
 }
-function readFileHistoryFact(word) {
-    if (word !== "on" && word !== "disabled")
-        throw new Error(`the file-history wiring fact ${JSON.stringify(word)} is not one of on|disabled`);
+function readWordFact(word, words, label) {
+    if (!words.includes(word))
+        throw new Error(`the ${label} wiring fact ${JSON.stringify(word)} is not one of ${words.join("|")}`);
     return word;
 }
+function readSessionRulesFact(fact) {
+    if (typeof fact !== "boolean")
+        throw new Error(`the session-rules wiring fact ${JSON.stringify(fact)} is not a boolean`);
+    return { childrenReadLive: fact };
+}
 export function deriveWiringManifest(facts) {
     if (facts.half === "static" && facts.leg !== undefined) {
         throw new Error("a static wiring manifest has no leg — leg identity is an effective-half fact");
@@ -219,14 +224,18 @@ export function deriveWiringManifest(facts) {
             ? { readDeny: { builtinTiers: [...facts.readDenyBuiltinTiersActive] } }
             : {}),
         ...(facts.half === "effective" && facts.autoConsolidationOnRecommendation === true ? { autoConsolidation: { onRecommendation: true } } : {}),
-        ...(facts.half === "effective" && facts.fileHistory !== undefined ? { fileHistory: readFileHistoryFact(facts.fileHistory) } : {}),
+        ...(facts.half === "effective" && facts.fileHistory !== undefined ? { fileHistory: readWordFact(facts.fileHistory, ["on", "disabled"], "file-history") } : {}),
+        ...(facts.half === "effective" && facts.projectMemory !== undefined ? { projectMemory: readWordFact(facts.projectMemory, ["on", "disabled", "absent"], "project-memory") } : {}),
+        ...(facts.half === "effective" && facts.sessionRulesChildrenReadLive !== undefined ? { sessionRules: readSessionRulesFact(facts.sessionRulesChildrenReadLive) } : {}),
+        ...(facts.half === "effective" && facts.advisor !== undefined ? { advisor: { ...facts.advisor, ...(facts.advisor.hold !== undefined ? { hold: { ...facts.advisor.hold } } : {}) } } : {}),
+        ...(facts.half === "effective" && facts.hostFloor !== undefined ? { hostFloor: { onlyMode: facts.hostFloor.onlyMode, denyCount: facts.hostFloor.denyCount, onlyCount: facts.hostFloor.onlyCount } } : {}),
         ...(facts.half === "effective" && facts.teamRole !== undefined ? { teamRole: facts.teamRole } : {}),
         ...(facts.half === "effective" && facts.peerPresence !== undefined && (facts.peerPresence.agent !== undefined || facts.peerPresence.intent !== undefined)
             ? { peerPresence: { ...(facts.peerPresence.agent !== undefined ? { agent: facts.peerPresence.agent } : {}), ...(facts.peerPresence.intent !== undefined ? { intent: facts.peerPresence.intent } : {}) } }
             : {}),
     };
     if (facts.half === "effective") {
-        const { leg: _leg, mcp: _mcp, tools: _tools, lsp: _lsp, mods: _mods, teamRole: _teamRole, peerPresence: _peerPresence, fileHistory: _fileHistory, permissionMode: _permissionMode, ...assembly } = manifest;
+        const { leg: _leg, mcp: _mcp, tools: _tools, lsp: _lsp, mods: _mods, teamRole: _teamRole, peerPresence: _peerPresence, fileHistory: _fileHistory, projectMemory: _projectMemory, permissionMode: _permissionMode, sessionRules: _sessionRules, advisor: _advisor, ...assembly } = manifest;
         const { provenance: _askSeat, ...askForHash } = assembly.ask;
         const { provenance: _questionSeat, ...questionForHash } = assembly.question;
         manifest.configFingerprint = createHash("sha256")

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

@@ -1,4 +1,5 @@
 import type { TaskResult } from "./types.js";
+import { type CorruptBodyForm } from "./store-contracts/read-back-shape-contract.js";
 /**
  * design/97 CORE-7 — one recorded `ctx.agent` result in a workflow's RESUME journal. Unlike the observation-only
  * {@link WorkflowRunStore} (best-effort, swallowed on throw), the journal is LOAD-BEARING: a resume replays the
@@ -30,6 +31,67 @@ export type WorkflowJournalEntry = {
         }>;
     };
 };
+/** What {@link readWorkflowJournalEntry} answers: the entry, or the corrupt form the row takes plus a clause
+ *  naming what is wrong with it (worded to follow "journal entry #N"; it quotes no stored value). */
+export type WorkflowJournalEntryReading = {
+    entry: WorkflowJournalEntry;
+} | {
+    corrupt: CorruptBodyForm;
+    why: string;
+};
+/**
+ * The ONE reading of a journal row read back from a store: which arm it is, and whether the arm carries what a
+ * resume reads from it — an object result, or a paused terminal with its checkpoint token (the payload's other
+ * members, `sessionId` / `gate` / `stats` among them, are not judged here). `raw` is the DECODED LOGICAL ROW — an object carrying
+ * `callKey` and exactly one of `result` / `parked`; how a backend encodes that row on its medium (a JSONL
+ * line with its own `scope` / `ordinal` members, a SQL column holding an envelope) is the backend's format
+ * and is decoded before this is asked. Members other than those three are not read and are not carried into
+ * the entry, which is minted fresh from them.
+ *
+ * Corrupt, by form:
+ *  - `not-an-object` — the row is not an object;
+ *  - `missing-required` — no `callKey`; neither arm; a parked arm whose result carries no `terminal`, or
+ *    whose paused terminal carries no `token`;
+ *  - `wrong-type` — a non-string `callKey`; BOTH arms (the union admits one); a `result` that is not an
+ *    object; a `parked` that is not an object; a parked arm whose terminal is not `paused`, or whose token
+ *    is not a non-empty string.
+ *
+ * The parked arm's paused terminal and its checkpoint token are judged here because the type requires them
+ * and the arm is load-bearing: a row that says it parked but holds no paused result with a token can neither
+ * be driven nor be replayed as a finished call, and answering it as either would let a resume run that
+ * ordinal again beside the child pinned under its pending checkpoint. Whether a COMPLETED result carries a
+ * terminal cause the engine can replay is the resume's own admission (a journal written before
+ * `TaskResult.terminal` is incompatible, not damaged).
+ */
+export declare function readWorkflowJournalEntry(raw: unknown): WorkflowJournalEntryReading;
+/**
+ * Clamp an externally-supplied run identifier before it lands in a persisted field or an error message:
+ * `resumeFromRunId` is LLM-controlled text and a resume claim's `holder` is store-supplied, so neither may
+ * carry control characters / unbounded length into a record a human or a model reads.
+ */
+export declare function clampRunIdText(raw: string): string;
+/** The code of {@link WorkflowJournalIncompatibleError} — the word the journal store kit asserts on a refused `load`. */
+export declare const JOURNAL_INCOMPATIBLE_ERROR_CODE = "workflow.journal_incompatible";
+/** A resume journal entry the resume cannot admit is INCOMPATIBLE, and the resume is refused before any work is
+ *  dispatched: a row whose result carries no terminal cause (a journal written before `TaskResult.terminal`), or
+ *  a row {@link readWorkflowJournalEntry} reads as corrupt — refused by the engine's admission, or by a store's
+ *  own `load` (the journal store kit holds a backend's refused `load` to this code). The alternative (letting the
+ *  entry diverge into a live re-run) would execute the already-completed prefix again, side effects included.
+ *
+ *  `entry` is the row as read: when the journal reader finds it corrupt, the message carries that reader's clause
+ *  (fixed text that quotes no stored value), so no caller-supplied text reaches it; absent, or a row the reader
+ *  admits, the clause is the missing terminal cause. A backend whose own medium holds a line that is not one of the
+ *  run's records refuses with {@link WorkflowJournalIncompatibleError.ledgerLine}. `ordinal` is `-1` when the refusal
+ *  names no entry ordinal: a row with no readable call key, or a ledger line. The run id is clamped here. */
+export declare class WorkflowJournalIncompatibleError extends Error {
+    readonly ordinal: number;
+    readonly code = "workflow.journal_incompatible";
+    readonly fromRunId: string;
+    constructor(fromRunId: string, ordinal: number, entry?: unknown);
+    /** The refusal for line `line` (1-based) of a backend's ledger that is not one of the run's records, judged `form`
+     *  by the backend's line reader: dropping it would leave whatever it held looking never journaled. */
+    static ledgerLine(fromRunId: string, line: number, form: CorruptBodyForm): WorkflowJournalIncompatibleError;
+}
 /** REF-D5: the resume-claim key triple — ONE shape for the interface pair and every implementation
  *  (it was re-inlined seven times; a key-field rename must red every leg at once). */
 export interface ResumeClaimArgs {

package/dist/core/workflow-journal-store.js

@@ -1,4 +1,72 @@
 import { terminalProjection } from "./runner/terminal-projection.js";
+import { CORRUPT_BODY_FORMS } from "./store-contracts/read-back-shape-contract.js";
+const isRecordShaped = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const ownMember = (o, key) => (Object.hasOwn(o, key) ? o[key] : undefined);
+export function readWorkflowJournalEntry(raw) {
+    if (!isRecordShaped(raw))
+        return { corrupt: "not-an-object", why: "is not a journal entry (not an object)" };
+    const callKey = ownMember(raw, "callKey");
+    if (callKey === undefined)
+        return { corrupt: "missing-required", why: "carries no call key" };
+    if (typeof callKey !== "string")
+        return { corrupt: "wrong-type", why: "has a call key that is not a string" };
+    const result = ownMember(raw, "result");
+    const parked = ownMember(raw, "parked");
+    if (result === undefined && parked === undefined)
+        return { corrupt: "missing-required", why: "carries neither a result nor a parked arm" };
+    if (result !== undefined && parked !== undefined)
+        return { corrupt: "wrong-type", why: "carries both a result and a parked arm" };
+    if (parked === undefined) {
+        if (!isRecordShaped(result))
+            return { corrupt: "wrong-type", why: "has a result that is not an object" };
+        return { entry: { callKey, result: result } };
+    }
+    if (!isRecordShaped(parked))
+        return { corrupt: "wrong-type", why: "is recorded as parked but its parked arm is not an object" };
+    const terminal = ownMember(parked, "terminal");
+    if (terminal === undefined)
+        return { corrupt: "missing-required", why: "is recorded as parked but its parked result carries no terminal" };
+    if (!isRecordShaped(terminal) || ownMember(terminal, "kind") !== "paused") {
+        return { corrupt: "wrong-type", why: "is recorded as parked but its terminal is not a paused one" };
+    }
+    const token = ownMember(terminal, "token");
+    if (token === undefined)
+        return { corrupt: "missing-required", why: "is recorded as parked but its paused terminal carries no checkpoint token" };
+    if (typeof token !== "string" || token.length === 0)
+        return { corrupt: "wrong-type", why: "is recorded as parked but its paused terminal carries no checkpoint token" };
+    return { entry: { callKey, parked: parked } };
+}
+export function clampRunIdText(raw) {
+    return raw.replace(/[^A-Za-z0-9_.:-]/g, "").slice(0, 64);
+}
+export const JOURNAL_INCOMPATIBLE_ERROR_CODE = "workflow.journal_incompatible";
+export class WorkflowJournalIncompatibleError extends Error {
+    ordinal;
+    code = JOURNAL_INCOMPATIBLE_ERROR_CODE;
+    fromRunId;
+    constructor(fromRunId, ordinal, entry) {
+        const runIdText = clampRunIdText(fromRunId);
+        super(`workflow run "${runIdText}": ${refusedSubjectOf(ordinal, entry)} — this journal cannot be resumed. ${REPAIR_COST}`);
+        this.ordinal = ordinal;
+        this.fromRunId = runIdText;
+        this.name = "WorkflowJournalIncompatibleError";
+    }
+    static ledgerLine(fromRunId, line, form) {
+        return new WorkflowJournalIncompatibleError(fromRunId, -1, { [LEDGER_LINE]: { line, form } });
+    }
+}
+const REPAIR_COST = "Deleting what is damaged does not repair it (whatever goes missing runs again, live); restoring it needs a copy of the ledger kept outside the engine; a fresh run executes every step again, side effects included.";
+const LEDGER_LINE = Symbol("ledgerLine");
+function refusedSubjectOf(ordinal, entry) {
+    const at = isRecordShaped(entry) ? entry[LEDGER_LINE] : undefined;
+    if (at !== undefined) {
+        const line = Number.isSafeInteger(at.line) && at.line > 0 ? at.line : "?";
+        const form = CORRUPT_BODY_FORMS.includes(at.form) ? at.form : "unreadable";
+        return `ledger line ${String(line)} is not one of the run's records (${String(form)})`;
+    }
+    const read = entry === undefined ? undefined : readWorkflowJournalEntry(entry);
+    return `journal entry #${ordinal} ${read !== undefined && "corrupt" in read ? read.why : "carries no terminal cause (a journal written before TaskResult.terminal, or a malformed entry)"}`;
+}
 export const MAX_JOURNAL_RESULT_BYTES = 5 * 1024 * 1024;
 export function oversizeJournalResult(serialized) {
     return Buffer.byteLength(serialized, "utf8") > MAX_JOURNAL_RESULT_BYTES;
@@ -34,7 +102,7 @@ export function journalOversizeTombstone(result, bytes) {
         taskId: result.taskId,
         sessionId: result.sessionId,
         terminal: { kind: "failed", code: JOURNAL_OVERSIZE_ERROR_CODE, message },
-        result: message,
+        result: message, resultEntryIds: [],
         stats: result.stats,
     };
 }
@@ -80,7 +148,15 @@ export class InMemoryWorkflowJournalStore {
         const rec = this.runs.get(runId);
         if (!rec || rec.scope !== scope)
             return [];
-        return [...rec.byOrdinal.entries()].sort((a, b) => a[0] - b[0]).map(([, e]) => snapshot(e));
+        const out = [];
+        for (const [ordinal, e] of [...rec.byOrdinal.entries()].sort((a, b) => a[0] - b[0])) {
+            const row = snapshot(e);
+            const read = readWorkflowJournalEntry(row);
+            if ("corrupt" in read)
+                throw new WorkflowJournalIncompatibleError(runId, ordinal, row);
+            out.push(read.entry);
+        }
+        return out;
     }
     async append(runId, scope, entry) {
         assertJournalEntryFits(entry);

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

@@ -46,6 +46,12 @@ export interface WorkflowRunSummary {
     description?: string;
     /** Lifecycle status ({@link WorkflowRun.status}): running / completed / failed. */
     status: WorkflowRunStatus;
+    /** `true` while the run is still `running` AND at least one leg is parked at an approval gate — somebody is being
+     *  waited on while `status` still says `running` ({@link runParkedOf}). ABSENT otherwise, never `false`: a run
+     *  that has since suspended on the park reads `failed` + `errorCode: "workflow.agent_parked"` (that code is its
+     *  "awaiting approval" word; a consumer shows both arms the same way), and a settled record never carries it.
+     *  DERIVED from the agent rows on every projection — not stored on the run, so no second copy to drift. */
+    parked?: true;
     /** The MACHINE code of the failure that ended the run ({@link WorkflowRun.errorCode}) — the same word,
      *  in the same vocabulary, that the full run carries; never re-derived and never a second taxonomy.
      *  The fourth member of the same family as {@link agentFailures} / {@link budgetOvershoot} /

package/dist/core/workflow-run-store.js

@@ -1,3 +1,4 @@
+import { runParkedOf } from "../orchestration/workflow-types.js";
 import { assertRetentionPolicy } from "./retention-policy.js";
 export function summarizeWorkflowRun(run) {
     const latestPhase = run.phases.at(-1);
@@ -8,6 +9,7 @@ export function summarizeWorkflowRun(run) {
         ...(run.name !== undefined ? { name: run.name } : {}),
         ...(run.description !== undefined ? { description: run.description } : {}),
         status: run.status,
+        ...(runParkedOf(run) ? { parked: true } : {}),
         ...(run.errorCode !== undefined ? { errorCode: run.errorCode } : {}),
         ...(run.agentFailures !== undefined ? { agentFailures: run.agentFailures } : {}),
         ...(run.budgetOvershoot !== undefined ? { budgetOvershoot: { ...run.budgetOvershoot } } : {}),

package/dist/engine/compaction/compaction.d.ts

@@ -17,7 +17,7 @@ export interface CompactionDetails {
      */
     modifiedFilesByRecency?: string[];
     /**
-     * Invoked-skill retention area (CC 2.1.207 parity): the skills invoked in the COMPACTED range
+     * Invoked-skill retention area: the skills invoked in the COMPACTED range
      * (merged over the previous compaction's retained set), most recent invocation first, already
      * budgeted (per-skill truncation marker + total-area skip semantics — see compaction/utils.ts).
      * Rendered onto the compaction summary message by `buildSessionContext`; kept OUT of the summary
@@ -131,7 +131,7 @@ export declare const DEFAULT_CLAMP_TOLERANCE = 0.1;
  * [new user]`, and a within-turn boundary keeps `[emitting assistant][its tool results]` because
  * a trailing tool-result batch pulls the floor back to its call site.
  *
- * That is the CC posture, arrived at through a different knob. CC 2.1.223's LOCAL threshold
+ * That is the CC posture, arrived at through a different knob. the reference's LOCAL threshold
  * compaction always routes to the reactive pipeline (`y9s` :432704 — the `GNo` full-compaction
  * branch with `messagesToKeep: []` :431788 is reached only for a remote/in-process runner, and a
  * `source:"auto"` window makes the local threshold not fire at all, `hky` :432687 / `aYe` :242816).
@@ -159,7 +159,7 @@ export declare const DEFAULT_COMPACTION_SETTINGS: CompactionSettings;
  * never split (estimate vs cut-point vs defense); per-model override via `Model.charsPerToken`.
  *
  * 4 → 3 (design/374 slice 4, ruled 2026-08-28) — this is a RE-ANCHORING, not a divergence.
- * CC's coefficient is a two-branch function, not a constant: `sf(model)` (cli250.js, `Z6` table) is
+ * CC's coefficient is a two-branch function, not a constant: `sf(model)` is
  *   `Z6.has(family) ? 4 : 3`
  * where `Z6` lists exactly the OLD families (claude-3.x, opus-4-0/4-1/4-5/4-6, sonnet-4-0/4-5/4-6,
  * haiku-4-5). **3 is CC's DEFAULT branch; 4 is the whitelist hit** — and CC's own current generation
@@ -189,7 +189,7 @@ export declare function calculateContextTokens(usage: Usage): number;
  *
  * design/123 D1 stale-anchor note (fable-m2, same-family point): this scans RAW session entries, so
  * unlike `buildSessionContext` (which shallow-strips the usage of kept-tail assistants replayed
- * across a compaction boundary — the anchor "naturally disappears", CC 198 parity) it CAN still see
+ * across a compaction boundary — the anchor "naturally disappears") it CAN still see
  * a pre-compaction anchor. Any consumer using this across a compaction boundary must treat such an
  * anchor as STALE: it reflects the pre-compaction request and overestimates the post-compaction
  * context. (Currently exported with no in-repo production consumer.)
@@ -265,7 +265,7 @@ export declare const SUMMARIZATION_SYSTEM_PROMPT = "You are a context summarizat
  */
 export declare function contextInstructionFilesSection(contextInstructionFiles?: string): string;
 /**
- * design/169-A (CC 220 :516490-516516 / :387325-387336) — the CC-form FORK context for a summary
+ * design/169-A — the CC-form FORK context for a summary
  * request: the main lane's latest REAL request. When present (and the summary model IS the main
  * model), the summary request is the main conversation itself — same `systemPrompt` bytes, same
  * message-list byte PREFIX, same tools — plus ONE appended user-role instruction message. The
@@ -310,7 +310,7 @@ export declare function extractForkSummaryEnvelope(text: string): string | undef
  *  messages above, un-serialized) + the fork-only instruction-file authority clause (see
  *  {@link FORK_CONTEXT_INSTRUCTION_AUTHORITY}) + the fork-only summary envelope (see
  *  {@link FORK_SUMMARY_ENVELOPE_DEMAND}; the independent form keeps its envelope-free contract).
- *  Instructions inject in the same CC-verbatim shape as the independent form so every channel keeps
+ *  Instructions inject in the same shape as the independent form so every channel keeps
  *  one injection grammar. */
 export declare function forkSummarizationInstruction(customInstructions?: string, contextInstructionFiles?: string): string;
 /**
@@ -327,7 +327,7 @@ export declare function forkSummarizationInstruction(customInstructions?: string
  *   base      = settings.summaryOutputBudgetTokens ?? settings.reserveTokens  (explicit knob wins)
  *   effective = min(base, summary model's max output)                          (never budget output
  *                                                                               the model can't emit)
- * CC contrast (2.1.207): CC's summary output cap is purely model-derived (its summary call runs at
+ * Contrast: the reference's summary output cap is purely model-derived (its summary call runs at
  * the model's max output) and fully separate from the trigger deduction — the `min(model.maxTokens,…)`
  * leg IS that posture. The base deliberately stays reserve-derived rather than jumping to the raw
  * model max: sema (unlike CC) clamps the summarization INPUT pre-send, and the clamp budgets
@@ -396,7 +396,7 @@ export interface SummarizationClampDryRun {
  * "prior summary + new increment", not the original history.
  */
 export declare function dryRunSummarizationClamp(preparation: CompactionPreparation, model: Model, customInstructions?: string, charsPerToken?: number): SummarizationClampDryRun;
-/** CC 198 jNl — verbatim marker inserted where the oldest conversation groups were dropped. */
+/** The marker inserted where the oldest conversation groups were dropped. */
 export declare const COMPACTION_PTL_RETRY_MARKER = "[earlier conversation truncated for compaction retry]";
 /** Generate or update a conversation summary for compaction.
  *  `summaryBudgetTokens` — the OUTPUT budget base (history leg = 0.8× it). Callers going through
@@ -488,6 +488,6 @@ export declare function compact(preparation: CompactionPreparation, model: Model
  *  the main model; an independent compaction model has no main prefix to share. */
 forkContext?: CompactionForkContext): Promise<Result<CompactionResult, CompactionError>>;
 /** The prefix leg's base prompt, with the caller's instructions injected in the SAME shape the
- *  history leg uses (`\n\nAdditional Instructions:\n${…}`, CC 198 verbatim). Single source so the
+ *  history leg uses (`\n\nAdditional Instructions:\n${…}`). Single source so the
  *  dry-run clamp charges exactly what the real call sends. */
 export declare function turnPrefixSummarizationPrompt(customInstructions?: string): string;

package/dist/engine/compaction/compaction.js

@@ -7,6 +7,7 @@ import { budgetInvokedSkillsRetention, computeFileLists, createFileOps, extractF
 import { ENGINE_AUTHORITY_ENVELOPE_TAGS, sanitizeUntrustedText } from "../../core/untrusted-text.js";
 import { sliceHeadSafe } from "../../core/surrogate-safe-slice.js";
 import { thrownText } from "../../core/thrown-value.js";
+import { capabilityHeld } from "../../brain/model-capability.js";
 function safeJsonStringify(value) {
     try {
         return JSON.stringify(value) ?? "undefined";
@@ -576,7 +577,7 @@ First, inside an <analysis>...</analysis> block, note what is new since the prev
 Keep each section concise. Preserve exact file paths, function names, and error messages.`;
 function createSummarizationOptions(model, maxTokens, apiKey, headers, signal, thinkingLevel) {
     const options = { maxTokens, signal, apiKey, headers };
-    if (model.reasoning && thinkingLevel) {
+    if (capabilityHeld(model, "reasoning") && thinkingLevel) {
         options.reasoning = thinkingLevel;
     }
     return options;
@@ -868,7 +869,7 @@ async function summarizeWithLengthRecovery(label, model, context, baseMaxTokens,
         ? Math.max(baseMaxTokens, model.contextWindow - estimateSummarizationInputTokens(context, cpt) - SUMMARY_WINDOW_MARGIN)
         : Number.POSITIVE_INFINITY;
     const cap = Math.min(modelCap, windowCap);
-    let maxTokens = Math.min(cap, model.reasoning ? Math.max(baseMaxTokens, SUMMARY_REASONING_FLOOR) : baseMaxTokens);
+    let maxTokens = Math.min(cap, capabilityHeld(model, "reasoning") ? Math.max(baseMaxTokens, SUMMARY_REASONING_FLOOR) : baseMaxTokens);
     for (let attempt = 0;; attempt++) {
         const canEscalate = attempt < SUMMARY_MAX_ESCALATIONS && maxTokens < cap;
         const response = await completeSummarization(model, context, createSummarizationOptions(model, maxTokens, apiKey, headers, signal, thinkingLevel), streamFn, runtime);

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

@@ -88,9 +88,13 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
     /** `ExecutionEnv.cdPath` = the `CDPATH` the shell child receives, read LIVE off the same merge each exec gets (never the
      *  engine process's own environment): its entries, `[]` when the child gets none. Residual: a per-exec `env.CDPATH`. */
     get cdPath(): readonly string[];
-    /** The environment the next shell child would receive, for a READ (the scrub seat is a no-op: a read reports nothing).
-     *  `undefined` when no child would be spawned at all — the policy is refused against the own credentials declared
-     *  since construction, and every spawn throws that reason — so a reader sees "the child gets none", never a throw. */
+    /** `ExecutionEnv.withheldEnv` = what the same merge withholds from the shell child (an entry `shellEnv` re-supplies is
+     *  no loss), read LIVE; `[]` when no child would be spawned at all. Residual: a per-exec `env` re-supplying one. */
+    get withheldEnv(): readonly SecretEnvFinding[];
+    /** The environment the next shell child would receive, for a READ (the scrub seat is the reader's collector or a
+     *  no-op: a read announces nothing). `undefined` when no child would be spawned at all — the policy is refused against
+     *  the own credentials declared since construction, and every spawn throws that reason — so a reader sees "the child
+     *  gets none", never a throw. */
     private childEnvForRead;
     private shellPath?;
     private shellEnv?;
@@ -101,8 +105,12 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
     private readonly retainBackgroundProcesses;
     private readonly onSecretEnvScrub?;
     private readonly onNotice?;
-    /** design/128 T1-1: lazily-created env-owned spool dir (mkdtemp under os tmp — unpredictable, never the cwd). */
+    /** design/128 T1-1: the env-owned spool dir (mkdtemp under os tmp — unpredictable, never the cwd). It exists only while
+     *  {@link spoolPairs} is non-empty: the last pair's release removes it, the next mint makes a fresh one. */
     private bgSpoolDir?;
+    /** The `outPath` of every spool pair this env minted and has not released — the one fact the dir's lifetime reads. A
+     *  retain-lane bg pair is never released (its files outlive the run by design), so it keeps the dir. */
+    private readonly spoolPairs;
     readonly backgroundCapabilities: BackgroundShellCapability["backgroundCapabilities"];
     constructor(options: {
         cwd: string;
@@ -127,7 +135,8 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
          * env lane; `TaskSpec.retainBackgroundProcesses` is the task lane, without this spooling guarantee on
          * every platform — docs/background-process-lifetime.md). The 2h bg-timeout reaper and `killBackground` still work
          * while the host lives; after host exit, cleanup is the deployment's responsibility (e.g. the TB
-         * container teardown). v1 covers processes spawned via `execBackground` only (a detach-adopted
+         * container teardown) — the retained shells' spool files, and the dir holding them, are never released
+         * by the env (every other spool pair is, and the dir goes with the last one). v1 covers processes spawned via `execBackground` only (a detach-adopted
          * foreground exec keeps pipe stdio — best-effort survival). Incompatible with durable-suspend
          * deployments (their pre-suspend dispose becomes a no-op too — do not combine).
          */
@@ -157,8 +166,8 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
         abortSignal?: AbortSignal;
     }): Promise<Result<string[], FileError>>;
     readBinaryFile(path: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
-    /** RB-221: whole-file replace via same-directory staging + fsync + rename (CC 2.1.220 `Q5`,
-     *  (pretty220.js:60808, historical; not relocated in 250 — see cc-250 anchors)). The former single-step `writeFile` was an in-place O_TRUNC: an abort mid-write
+    /** RB-221: whole-file replace via same-directory staging + fsync + rename.
+     *  The former single-step `writeFile` was an in-place O_TRUNC: an abort mid-write
      *  (Esc during a large Write — ctx.signal reaches here directly), ENOSPC, or a crash left the target as
      *  a torn prefix of the NEW content with the original unrecoverable. Post-fix contract: the target is
      *  either fully old or fully new; `aborted` means it was never touched. Known semantic change (same as
@@ -251,10 +260,19 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
      *  the file), while poll slicing keeps using the logical stream totalBytes; the two advance in
      *  lockstep here but are NOT interchangeable after a rotation. */
     private syncSpool;
+    /** The one seat that opens a spool pair (foreground exec and background spawn alike), inside the env's spool dir: made on
+     *  the first mint after the dir was last removed, so a command never runs against a dir an idle reap or a temp cleaner took. */
+    private mintSpoolPair;
+    /** The one seat that gives a spool pair back: unlinks both files (a descendant still writing keeps its fd into the unlinked
+     *  inode — no EPIPE), forgets the pair, and removes the dir once no pair is left in it. Idempotent. */
+    private releaseSpoolPair;
+    /** Removes the spool dir (and whatever a failed unlink stranded in it) when no pair of this env lives in it. A retain-lane
+     *  bg pair is never released, so it keeps its dir; the rest is gone with its last pair. Best-effort, never throws. */
+    private reapSpoolDirIfIdle;
     /** +: reclaim an EPHEMERAL spool (detach-adopted, or any non-retain bg
      *  spawn — the whole unix bg lane is spool-backed now) — fold the final residue into the tails,
      *  unlink both files, and drop the spool reference (later syncs become no-ops). Idempotent;
-     *  never touches design/128 retain-lane spools (no `ephemeral` flag). A still-writing detached
+     *  never touches the spool of a design/128 retain-lane shell that has a process (no `ephemeral` flag). A still-writing detached
      *  descendant keeps its fd into the unlinked inode (RB-26 posture — no EPIPE, auto-reclaim at
      *  its exit). */
     private reclaimEphemeralSpool;

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

@@ -1,6 +1,6 @@
 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 { closeSync, constants, createReadStream, mkdtempSync, openSync, readSync, rmSync, statSync, truncateSync, unlinkSync } from "node:fs";
 import { access, appendFile, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, rename, rm, stat, unlink, writeFile, } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
@@ -116,6 +116,10 @@ function toFileError(error, path) {
                 return new FileError("not_directory", message, path, cause);
             case "EISDIR":
                 return new FileError("is_directory", message, path, cause);
+            case "ENAMETOOLONG":
+                if (path !== undefined && path.split(/[\\/]/).some((part) => Buffer.byteLength(part, "utf8") > 255))
+                    return new FileError("name_too_long", message, path, cause);
+                break;
             case "EINVAL":
                 return new FileError("invalid", message, path, cause);
             default:
@@ -321,10 +325,15 @@ export class NodeExecutionEnv {
         const value = this.childEnvForRead()?.CDPATH;
         return value === undefined || value === "" ? [] : value.split(":");
     }
-    childEnvForRead() {
+    get withheldEnv() {
+        let withheld = [];
+        this.childEnvForRead((f) => (withheld = f));
+        return withheld;
+    }
+    childEnvForRead(collect = () => { }) {
         if (inheritEnvPolicyProblem(this.inheritEnv) !== undefined)
             return undefined;
-        return getShellEnv(this.inheritEnv, this.shellEnv, undefined, () => { });
+        return getShellEnv(this.inheritEnv, this.shellEnv, undefined, collect);
     }
     shellPath;
     shellEnv;
@@ -336,6 +345,7 @@ export class NodeExecutionEnv {
     onSecretEnvScrub;
     onNotice;
     bgSpoolDir;
+    spoolPairs = new Set();
     backgroundCapabilities;
     constructor(options) {
         this.cwd = options.cwd;
@@ -465,13 +475,7 @@ export class NodeExecutionEnv {
                 if (spoolPumpRef.current)
                     clearInterval(spoolPumpRef.current);
                 if (execSpoolRef.current && !(result.ok && result.value.detached !== undefined)) {
-                    for (const path of [execSpoolRef.current.outPath, execSpoolRef.current.errPath]) {
-                        try {
-                            unlinkSync(path);
-                        }
-                        catch {
-                        }
-                    }
+                    this.releaseSpoolPair(execSpoolRef.current);
                     execSpoolRef.current = undefined;
                 }
                 resolvePromise(result);
@@ -479,9 +483,7 @@ export class NodeExecutionEnv {
             let execSpoolFds;
             if (process.platform !== "win32") {
                 try {
-                    if (!this.bgSpoolDir)
-                        this.bgSpoolDir = mkdtempSync(join(tmpdir(), "sema-bg-"));
-                    const pair = openSpoolPair(join(this.bgSpoolDir, `fg_${randomUUID()}`));
+                    const pair = this.mintSpoolPair(`fg_${randomUUID()}`);
                     execSpoolRef.current = { outPath: pair.outPath, errPath: pair.errPath };
                     execSpoolFds = pair.fds;
                 }
@@ -1309,9 +1311,7 @@ export class NodeExecutionEnv {
         let spoolFds;
         if (this.retainBackgroundProcesses || process.platform !== "win32") {
             try {
-                if (!this.bgSpoolDir)
-                    this.bgSpoolDir = mkdtempSync(join(tmpdir(), "sema-bg-"));
-                const pair = openSpoolPair(join(this.bgSpoolDir, `bg_${this.bgCounter + 1}_${randomUUID()}`));
+                const pair = this.mintSpoolPair(`bg_${this.bgCounter + 1}_${randomUUID()}`);
                 spool = {
                     outPath: pair.outPath,
                     errPath: pair.errPath,
@@ -1345,6 +1345,8 @@ export class NodeExecutionEnv {
                     }
                 }
             }
+            if (spool)
+                this.releaseSpoolPair(spool);
             const cause = toError(error);
             return err(new BackgroundShellError("spawn_failed", cause.message, cause));
         }
@@ -1533,23 +1535,51 @@ export class NodeExecutionEnv {
             }
         }
     }
+    mintSpoolPair(name) {
+        this.bgSpoolDir ??= mkdtempSync(join(tmpdir(), "sema-bg-"));
+        try {
+            const pair = openSpoolPair(join(this.bgSpoolDir, name));
+            this.spoolPairs.add(pair.outPath);
+            return pair;
+        }
+        catch (error) {
+            this.reapSpoolDirIfIdle();
+            throw error;
+        }
+    }
+    releaseSpoolPair(pair) {
+        for (const path of [pair.outPath, pair.errPath]) {
+            try {
+                unlinkSync(path);
+            }
+            catch {
+            }
+        }
+        this.spoolPairs.delete(pair.outPath);
+        this.reapSpoolDirIfIdle();
+    }
+    reapSpoolDirIfIdle() {
+        const dir = this.bgSpoolDir;
+        if (dir === undefined || this.spoolPairs.size > 0)
+            return;
+        this.bgSpoolDir = undefined;
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+        }
+    }
     reclaimEphemeralSpool(entry) {
         if (entry.spoolPump !== undefined) {
             clearInterval(entry.spoolPump);
             entry.spoolPump = undefined;
         }
         const spool = entry.spool;
-        if (!spool?.ephemeral)
+        if (!spool || (!spool.ephemeral && entry.child.pid !== undefined))
             return;
         this.syncSpool(entry);
         entry.spool = undefined;
-        for (const path of [spool.outPath, spool.errPath]) {
-            try {
-                unlinkSync(path);
-            }
-            catch {
-            }
-        }
+        this.releaseSpoolPair(spool);
     }
     async disposeBackgroundShells(opts) {
         if (this.retainBackgroundProcesses)