@sema-agent/core 5.65.0 → 7.0.0

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

@@ -11,14 +11,18 @@ function refuseLocalOwnerSync() {
 const SYNC_MAX_ATTEMPTS = 8;
 const DISCLOSED_REFUSED_TOMBSTONES = 5;
 export async function syncPermissionRules(opts) {
-    if (opts.owner !== undefined) {
-        if (opts.owner.kind === "local-owner")
+    const principal = opts.principal;
+    const owner = opts.owner;
+    const provider = opts.provider;
+    const transport = opts.transport;
+    if (owner !== undefined) {
+        if (owner.kind === "local-owner")
             refuseLocalOwnerSync();
-        if (opts.owner.principal !== opts.principal) {
-            throw new Error(`contradictory identity: principal "${escapeForDisclosure(opts.principal)}" and owner principal "${escapeForDisclosure(opts.owner.principal)}" disagree`);
+        if (owner.principal !== principal) {
+            throw new Error(`contradictory identity: principal "${escapeForDisclosure(principal)}" and owner principal "${escapeForDisclosure(owner.principal)}" disagree`);
         }
     }
-    if (typeof opts.principal !== "string" || opts.principal === "") {
+    if (typeof principal !== "string" || principal === "") {
         throw new Error("syncPermissionRules requires a verified principal — an unauthenticated deployment has no cloud bucket to sync");
     }
     const traceClock = opts.now ?? Date.now;
@@ -30,7 +34,7 @@ export async function syncPermissionRules(opts) {
             emitTrace(tracer, () => ({
                 kind: "permission.rule_sync_resurrected",
                 version: 1,
-                principal: opts.principal,
+                principal,
                 rule: r.rule,
                 scopeKind: r.scope.kind,
                 ts: traceClock(),
@@ -40,7 +44,7 @@ export async function syncPermissionRules(opts) {
             emitTrace(tracer, () => ({
                 kind: "permission.rule_sync_dropped",
                 version: 1,
-                principal: opts.principal,
+                principal,
                 rule: d.rule,
                 scopeKind: d.scope.kind,
                 reason: d.reason,
@@ -49,20 +53,20 @@ export async function syncPermissionRules(opts) {
         }
         return result;
     };
-    const store = opts.provider.forPrincipal(opts.principal);
+    const store = provider.forPrincipal(principal);
     const writer = writerOf(store);
     if (writer === undefined) {
         throw new Error("the resolved permission-rule store has no write face — a sync round cannot land through it");
     }
     const raw = await writer.readRaw();
     const request = {
-        principal: opts.principal,
+        principal,
         replica: raw.actor,
         state: { rules: raw.rules, tombstones: raw.tombstones },
         ...(raw.observedVector !== undefined ? { observedVector: raw.observedVector } : {}),
     };
-    const rawResponse = await opts.transport(PERMISSION_RULE_SYNC_PATH, request);
-    const response = parseRuleSyncResponse(rawResponse, opts.principal);
+    const rawResponse = await transport(PERMISSION_RULE_SYNC_PATH, request);
+    const response = parseRuleSyncResponse(rawResponse, principal);
     const warnings = [...response.warnings];
     const dropped = [];
     const inboundTombstones = [];
@@ -87,6 +91,9 @@ export async function syncPermissionRules(opts) {
     for (const t of response.textRefusedTombstones) {
         dropped.push({ rule: t.rule, scope: t.scope, dot: t.dot, reason: "invalid_rule_text" });
     }
+    for (const t of response.sessionScopeTombstones) {
+        dropped.push({ rule: t.rule, scope: t.scope, dot: t.dot, reason: "session_scope_not_durable" });
+    }
     if (response.textRefusedTombstones.length > 0) {
         const named = response.textRefusedTombstones
             .slice(0, DISCLOSED_REFUSED_TOMBSTONES)
@@ -127,6 +134,10 @@ export async function syncPermissionRules(opts) {
     }
     const localDots = new Set(raw.rules.flatMap((r) => r.adds.map((a) => JSON.stringify([a.dot.actor, a.dot.counter]))));
     for (const d of response.dropped) {
+        if (d.scope.kind === "session") {
+            warnings.push(`the server's dropped list names a session-scope row (${escapeForDisclosure(d.rule)}) — the durable store never holds one, so there is no local row it could mean; ignored`);
+            continue;
+        }
         if (localDots.has(JSON.stringify([d.dot.actor, d.dot.counter]))) {
             const reason = d.reason === "below_gc_frontier" ? "below_gc_frontier" : "server_rejected";
             quarantine.push({ rule: d.rule, scope: d.scope, dots: [d.dot], reason });
@@ -186,7 +197,7 @@ export async function syncPermissionRules(opts) {
         const dotKeyOf = (d) => JSON.stringify([d.actor, d.counter]);
         const preDots = new Set(current.rules.flatMap((r) => r.adds.map((a) => dotKeyOf(a.dot))));
         const newAdds = landedRaw.rules.flatMap((r) => r.adds).filter((a) => !preDots.has(dotKeyOf(a.dot))).length;
-        const tombKeyOf = (t) => JSON.stringify([t.rule, t.scope.kind === "global" ? null : t.scope.root, dotKeyOf(t.deletedBy)]);
+        const tombKeyOf = (t) => JSON.stringify([t.rule, t.scope.kind, t.scope.kind === "project" ? t.scope.root : t.scope.kind === "session" ? t.scope.sessionId : null, dotKeyOf(t.deletedBy)]);
         const preTombs = new Set(current.tombstones.map(tombKeyOf));
         const newTombstones = landedRaw.tombstones.filter((t) => !preTombs.has(tombKeyOf(t))).length;
         const landedReport = res.sync;
@@ -224,13 +235,23 @@ function pickDot(v) {
     const counter = d?.counter;
     return typeof actor === "string" && actor !== "" && typeof counter === "number" && Number.isFinite(counter) ? { actor, counter } : undefined;
 }
-function pickScope(v) {
+function pickScopeCaptured(v) {
     const s = v;
-    if (s?.kind === "global")
-        return { kind: "global" };
-    if (s?.kind === "project" && typeof s.root === "string" && s.root !== "")
-        return { kind: "project", root: s.root };
-    return undefined;
+    const kind = s?.kind;
+    if (kind === "global")
+        return { kind, scope: { kind: "global" } };
+    if (kind === "project") {
+        const root = s?.root;
+        return { kind, scope: typeof root === "string" && root !== "" ? { kind: "project", root } : undefined };
+    }
+    if (kind === "session") {
+        const sessionId = s?.sessionId;
+        return { kind, scope: typeof sessionId === "string" && sessionId !== "" ? { kind: "session", sessionId } : undefined };
+    }
+    return { kind, scope: undefined };
+}
+function pickScope(v) {
+    return pickScopeCaptured(v).scope;
 }
 function pickAdd(v) {
     const a = v;
@@ -321,9 +342,11 @@ export function parseRuleSyncResponse(raw, expectedPrincipal) {
     }
     const tombstones = [];
     const textRefusedTombstones = [];
+    const sessionScopeTombstones = [];
     for (const entry of mergedTombstones) {
         const t = entry;
-        const scope = pickScope(t?.scope);
+        const pickedScope = pickScopeCaptured(t?.scope);
+        const scope = pickedScope.scope;
         const ruleText = t?.rule;
         const deletedBy = pickDot(t?.deletedBy);
         const removedRaw = t?.removedDots;
@@ -338,6 +361,15 @@ export function parseRuleSyncResponse(raw, expectedPrincipal) {
                 removedDots.push(dot);
             }
         }
+        if (pickedScope.kind === "session") {
+            if (typeof ruleText === "string" && deletedBy !== undefined && scope !== undefined) {
+                sessionScopeTombstones.push({ rule: ruleText, scope, dot: deletedBy });
+            }
+            else {
+                warnings.push("the response carried a session-scope tombstone whose identity could not be read — dropped per-row (a session row never lands here, and nothing is withheld for it)");
+            }
+            continue;
+        }
         if (typeof ruleText !== "string" || scope === undefined || deletedBy === undefined || removedDots.length === 0) {
             tombstones.push(undefined);
             continue;
@@ -380,6 +412,7 @@ export function parseRuleSyncResponse(raw, expectedPrincipal) {
         ...(gcFrontier !== undefined ? { gcFrontier } : {}),
         dropped,
         textRefusedTombstones,
+        sessionScopeTombstones,
         warnings,
     };
 }

package/dist/core/retention-policy.d.ts

@@ -31,6 +31,15 @@ export interface RetentionPolicyKnobs {
     /** Row-count bound, whole rows (roster's write-time cap). */
     maxEntries?: number;
 }
+/**
+ * The family's typed refusal, exported so a seam whose bound has its own ADMISSIBLE RANGE refuses in
+ * the same grammar under the same code instead of minting a second one. The one in-tree case:
+ * file-history's boundary cap requires `>= 1` where the row stores accept `0` ("keep no rows" is a
+ * coherent policy for a ledger; for a history whose every commit mints a boundary it is not — the
+ * cap would reap the boundary its own commit just published), so that door cannot reuse
+ * {@link assertRetentionPolicy}'s "0 or more" wording without telling an operator something false.
+ */
+export declare function refuseRetentionPolicy(label: string, knob: string, value: unknown, requirement: string): never;
 /**
  * Refuse a malformed retention policy at the door. `undefined` on any field keeps its documented
  * meaning — that arm is simply not applied — so a deployment that sets nothing is untouched.

package/dist/core/retention-policy.js

@@ -1,8 +1,11 @@
-function invalidPolicy(label, knob, value, requirement) {
-    const e = new Error(`${label}: ${knob} must be ${requirement} (got ${String(value)}) — a retention bound that cannot be evaluated silently decides what to delete instead of bounding it`);
+export function refuseRetentionPolicy(label, knob, value, requirement) {
+    const e = new Error(`${label}: ${knob} must be ${requirement} (got ${typeof value === "string" ? JSON.stringify(value) : String(value)}) — a retention bound that cannot be evaluated silently decides what to delete instead of bounding it`);
     e.code = "config.retention_policy_invalid";
     throw e;
 }
+function invalidPolicy(label, knob, value, requirement) {
+    refuseRetentionPolicy(label, knob, value, requirement);
+}
 export function assertRetentionPolicy(label, opts) {
     if (opts === undefined)
         return;

package/dist/core/retention.d.ts

@@ -27,7 +27,12 @@ export interface RetentionPolicy {
  *  - **idempotent**: a retried invocation after a crash re-converges (already-deleted rows are
  *    counted, not errors);
  *  - **tombstoned**: deletions leave tombstones so replicas/backups converge instead of resurrecting;
- *  - **audited**: every destructive call returns a receipt the scheduler persists (append-only).
+ *  - **audited**: every destructive call is recorded append-only. The IDENTITY of that record —
+ *    which occurrence, which of the three operations, at what wall clock — belongs to the side that
+ *    WRITES the row, not to the receipt: an implementation records it in the same transaction as the
+ *    deletion (recording after the delete would leave an unwitnessed delete on a crash), and it is
+ *    the only side that knows its own op, sweep round, and policy generation. The receipt below is
+ *    therefore the CALL's three counts, deliberately not an audit row.
  */
 export interface ManagedRetentionCapability {
     /** Enumerate the retention domains (tenant/scope keys) this store holds data for. */
@@ -54,7 +59,13 @@ export interface ManagedRetentionCapability {
         cutoffMs: number;
     }): Promise<RetentionReceipt>;
 }
-/** Audit receipt of one destructive retention call (append-only material for the scheduler). */
+/**
+ * The three counts one destructive retention call produced. NOT an audit row and deliberately
+ * identity-free (see the capability's `audited` clause): a scheduler that needs to tell two
+ * same-shaped calls apart reads its store's audit records, which the implementation writes with its
+ * own occurrence id, operation, and timestamp inside the deleting transaction. Adding those here
+ * would ask a return value to know its own call context.
+ */
 export interface RetentionReceipt {
     domain: string;
     /** Rows destroyed by THIS call (idempotent retries count already-gone rows as 0, not errors). */

package/dist/core/runner/assemble-result.d.ts

@@ -100,6 +100,11 @@ export type BudgetAxis = "tokens" | "cost";
  */
 export interface ResultFlags {
     threw: unknown;
+    /** #499 — the run's ENGINE-minted identity (`Prepared.runId`), echoed verbatim on
+     *  `TaskResult.runId`. Pure pass-through on every terminal: assembly neither mints nor derives it
+     *  (a caller reaching assembly at all has completed prepare, so the value exists), and a
+     *  hand-constructed flags bag without one simply produces a result without one. */
+    runId?: string;
     /** design/99 MF-25: the EFFECTIVE (resolved) model id that served the task — echoed on `TaskResult.model`. */
     model?: string;
     /** RB-368: some spend was accounted while the serving model had NO configured price table
@@ -118,6 +123,15 @@ export interface ResultFlags {
      *  path the terminal is `completed`, and this is what tells that completion apart from a natural
      *  one — the model did not finish; the person stopped it and the run awaits their direction). */
     haltedOnUserRejection?: boolean;
+    /** design/373 (#504) — a `TaskStream.halt` (the bare user interrupt, CC Esc form) was accepted
+     *  while the run was live; echoed on `TaskResult.haltedByUser`. Pure pass-through on every
+     *  terminal (the sibling `haltedOnUserRejection` law: the fact is about the leg that ran) PLUS
+     *  one status decision it owns (slot 9.7 below): a run whose ONLY stop was this halt reads
+     *  `"completed"`, never the `!final` failure and never the aborted terminal — whether the halt
+     *  landed before the model said anything (empty result) or cut a turn whose partial text the
+     *  brain kept (that text IS the result). The person stopped the run, which is the verb working,
+     *  not a defect. A REAL abort/limit that also fired still owns the terminal above it. */
+    userHalted?: boolean;
     /** design/174 final-round: call ids of answered-but-never-collected questions, echoed on
      *  `TaskResult.strandedHumanAnswers`. Pure pass-through; empty/absent ⇒ the field is omitted. The
      *  optional `onError` alert is NOT the disclosure — this mandatory result face is. */
@@ -240,7 +254,11 @@ export declare function errorCodeOf(err: unknown): string | undefined;
  *       discriminant guarantees only one is ever set)
  *   9. `abortedLive` | stopReason aborted → `"limits.max_walltime_exceeded"` | `"limits.max_turns_exceeded"` | undefined
  *       (audit A-1: hoisted ABOVE no-final — the loop exits cleanly on abort, so `final` may be a
- *       normal message or absent; a plain user interrupt carries NO errorCode — switch on `status`)
+ *       normal message or absent; a plain user interrupt carries NO errorCode — switch on `status`),
+ *       EXCEPT when the aborted `final` is the bare halt's OWN cut artifact (`haltOwnsAbortedFinal`)
+ *   9.7 `userHalted` + (no `final` | the halt's own aborted `final`) → status `"completed"` (#504: a
+ *       bare user halt — the verb working, not a defect; below the aborts on purpose, a real
+ *       abort/limit that also fired owns the terminal and the halt rides as the pass-through seat)
  *  10. no `final`        → status `"failed"`
  *  11. stopReason error  → brain `[code]` prefix (or `"conflict"` from the storage-layer flag)
  *  12. else              → `"completed"`

package/dist/core/runner/assemble-result.js

@@ -57,12 +57,18 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     const result = text;
     let errorMessage;
     let errorCode;
+    let apiFailure;
     let blockedReason;
     let salvagedOutput;
     let checkpointToken;
     let checkpointId;
     let checkpointGate;
     let workspaceRestoreMode;
+    const haltOwnsAbortedFinal = flags.userHalted === true &&
+        final?.stopReason === "aborted" &&
+        !flags.abortedLive &&
+        flags.abortedForTimeout !== true &&
+        flags.abortedForTurns !== true;
     const isDegenerate = final?.stopReason === "error" && isDegenerateCutMessage(final);
     if (flags.outputInvalid) {
         status = "failed";
@@ -127,11 +133,14 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
         checkpointGate = flags.reviewRef.gate;
         workspaceRestoreMode = flags.reviewRef.restoreMode;
     }
-    else if (flags.abortedLive || final?.stopReason === "aborted") {
+    else if ((flags.abortedLive || final?.stopReason === "aborted") && !haltOwnsAbortedFinal) {
         status = "failed";
         errorCode = flags.abortedForTimeout ? "limits.max_walltime_exceeded" : flags.abortedForTurns ? "limits.max_turns_exceeded" : undefined;
         errorMessage = final?.errorMessage ?? (flags.abortedForTurns ? "max turns exceeded" : "run aborted");
     }
+    else if (flags.userHalted === true && (!final || haltOwnsAbortedFinal)) {
+        status = "completed";
+    }
     else if (!final) {
         status = "failed";
         errorMessage = "no assistant message produced";
@@ -139,6 +148,12 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     else if (final.stopReason === "error") {
         status = "failed";
         errorMessage = final.errorMessage ?? "model error";
+        if (final.isApiErrorMessage === true) {
+            apiFailure = {
+                ...(final.apiErrorStatus !== undefined ? { status: final.apiErrorStatus } : {}),
+                ...(final.requestId !== undefined ? { requestId: final.requestId } : {}),
+            };
+        }
         const lifted = extractErrorCode(errorMessage);
         if (lifted) {
             errorCode = lifted;
@@ -165,5 +180,5 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     void _internalCompaction;
     if (flags.unpricedSpend)
         delete publicStats.costMicroUsd;
-    return { taskId, sessionId, status, ...(flags.model !== undefined ? { model: flags.model } : {}), result: result.trim(), salvagedOutput, blockedReason, errorMessage, errorCode, ...(retryAfterMs !== undefined ? { retryAfterMs } : {}), checkpointToken, ...(checkpointId !== undefined ? { checkpointId } : {}), checkpointGate, ...(workspaceRestoreMode !== undefined ? { workspaceRestoreMode } : {}), ...(flags.rewindNotes !== undefined && flags.rewindNotes.length > 0 ? { rewindNotes: flags.rewindNotes } : {}), ...(flags.haltedOnUserRejection === true ? { haltedOnUserRejection: true } : {}), ...(flags.remoteEnvFailures !== undefined && flags.remoteEnvFailures.length > 0 ? { remoteEnvFailures: flags.remoteEnvFailures } : {}), ...(flags.strandedHumanAnswers !== undefined && flags.strandedHumanAnswers.length > 0 ? { strandedHumanAnswers: flags.strandedHumanAnswers } : {}), ...(flags.effectiveReadFace !== undefined ? { effectiveReadFace: flags.effectiveReadFace } : {}), ...(flags.effectiveReadDenyPatterns !== undefined && flags.effectiveReadDenyPatterns.length > 0 ? { effectiveReadDenyPatterns: flags.effectiveReadDenyPatterns } : {}), ...(flags.effectiveMemoryScopes !== undefined ? { effectiveMemoryScopes: flags.effectiveMemoryScopes } : {}), ...(flags.effectiveReasoning !== undefined ? { effectiveReasoning: flags.effectiveReasoning } : {}), stats: publicStats };
+    return { taskId, ...(flags.runId !== undefined ? { runId: flags.runId } : {}), sessionId, status, ...(flags.model !== undefined ? { model: flags.model } : {}), result: result.trim(), salvagedOutput, blockedReason, errorMessage, errorCode, ...(apiFailure !== undefined ? { apiFailure } : {}), ...(retryAfterMs !== undefined ? { retryAfterMs } : {}), checkpointToken, ...(checkpointId !== undefined ? { checkpointId } : {}), checkpointGate, ...(workspaceRestoreMode !== undefined ? { workspaceRestoreMode } : {}), ...(flags.rewindNotes !== undefined && flags.rewindNotes.length > 0 ? { rewindNotes: flags.rewindNotes } : {}), ...(flags.haltedOnUserRejection === true ? { haltedOnUserRejection: true } : {}), ...(flags.userHalted === true ? { haltedByUser: true } : {}), ...(flags.remoteEnvFailures !== undefined && flags.remoteEnvFailures.length > 0 ? { remoteEnvFailures: flags.remoteEnvFailures } : {}), ...(flags.strandedHumanAnswers !== undefined && flags.strandedHumanAnswers.length > 0 ? { strandedHumanAnswers: flags.strandedHumanAnswers } : {}), ...(flags.effectiveReadFace !== undefined ? { effectiveReadFace: flags.effectiveReadFace } : {}), ...(flags.effectiveReadDenyPatterns !== undefined && flags.effectiveReadDenyPatterns.length > 0 ? { effectiveReadDenyPatterns: flags.effectiveReadDenyPatterns } : {}), ...(flags.effectiveMemoryScopes !== undefined ? { effectiveMemoryScopes: flags.effectiveMemoryScopes } : {}), ...(flags.effectiveReasoning !== undefined ? { effectiveReasoning: flags.effectiveReasoning } : {}), stats: publicStats };
 }

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

@@ -29,6 +29,99 @@ import type { Prepared } from "./prepare-task.js";
  * task has no hands (no `readTaskFile` ⇒ nothing can be re-read).
  */
 export declare function buildWorkingFileAttachments(spec: TaskSpec, prepared: Prepared): MaybeCompactOptions["workingFileAttachments"];
+/**
+ * #500 — `MaybeCompactOptions.contextInstructionFiles`: the seat that delivers the deployment's own
+ * instruction-file content (the CLAUDE.md family) to the SUMMARIZER, assembled once here and spread
+ * on all three lanes. Without it the compaction boundary is the one place a long task loses the
+ * standing instructions every other turn has been reading — and it loses them exactly where the
+ * summary REPLACES the transcript that carried them, so the loss is durable.
+ *
+ * WHICH BYTES, and why the neighbours are not candidates. `Prepared.projectInstructionContent` =
+ * the RAW loader text (`ProjectMemoryLoad.content`, exactly the string prepare-task feeds
+ * `composeMemoryBlock(projectMem, "project")`), captured beside the existing `instructionSources`
+ * capture under the SAME non-blank predicate that composes the project layer:
+ *   · the assembled `memoryBlock` is NOT a candidate. It is the memory ENGINE's composed layers —
+ *     bytes the model itself authored in-band this session through the memory tools — with the
+ *     project layer appended at the tail. The seat's contract is host/systemPrompt tier and says in
+ *     terms: never from tool output, model text, or any other in-band channel. Handing
+ *     model-authored bytes an envelope whose preamble tells the summarizer they may instruct it is
+ *     the laundering shape, not a purity nit. (Mechanically moot too — `memoryBlock` is a
+ *     prepare-task local and never reaches `Prepared`.)
+ *   · the COMPOSED project block is not it either, and this one is checkable rather than a
+ *     judgement: `contextInstructionFilesSection` neutralizes the whole authority family
+ *     (ENGINE_AUTHORITY_ENVELOPE_TAGS) over its payload, and `user_memory`/`scope` ARE in that
+ *     family — so feeding a composed block would have the engine rewrite the tags of its own
+ *     composition. Raw text in, one fence at the mint.
+ *   · `prepared.instructionSources` carries path + contentHash only, by design (core never learns a
+ *     file-name policy), so it cannot serve this seat at all.
+ *
+ * PROVENANCE, stated plainly because "the host supplies it" is the easy half of the truth. On this
+ * engine the value is REPOSITORY-CONTROLLED text: the loading block one file over calls a CLAUDE.md
+ * of unknown authorship untrusted in so many words, the MAIN lane's own framing tells the model it is
+ * "repository-controlled DATA, not instructions to obey", and this seat hands the same bytes to the
+ * summarizer with instruction standing for the summarization task. Delivery THROUGH a host callback
+ * is not host AUTHORSHIP: a prior agent, or anyone who can land a commit, can write a
+ * "## Compact Instructions" section, and the mint's neutralization stops tag breakout — not a
+ * sentence asking for a fact to be left out of the summary that replaces the transcript.
+ * Why it is nevertheless this value: the seat's own contract names this path ("hosts pass the same
+ * instruction-file content their prompt assembly mounts... on the runner path"), the parity form this
+ * channel exists to reach reads the user's and the project's instruction files at every boundary with
+ * exactly this standing, and the two alternatives are worse for reasons above rather than better.
+ * The standing is also narrower than the framing gap suggests — the section's preamble scopes it to
+ * guidance about HOW to summarize and classifies the rest as background — and a deployment that does
+ * not want it has two exits that need no code: do not wire the loader, or return content it vouches
+ * for. Recorded as an open design candidate rather than built here, because it is a contract change
+ * and not a wiring one: a SEPARATE deployment-vouched summarization-instructions seat, leaving
+ * repository-derived context at data tier.
+ *
+ * RULING ① — BOTH summary forms, no per-form split. Fork eligibility is decided per pass INSIDE
+ * maybeCompact (main-model-only, recorded-request-present, not lossy), so a call site cannot say
+ * "independent form only"; the closest approximation — pass the seat only when `prepared.compModel`
+ * is set, since an independent compaction model has no main prefix to fork — leaves the hole the
+ * wrong way round: the configuration it does NOT cover (no compaction model) is precisely the one
+ * where a fork degrades mid-pass to the independent form, which would then run WITHOUT the files.
+ * Feeding both forms closes that case by construction, and the library face already handles the fork
+ * half (the section rides the APPENDED instruction message, never the cached prefix, so the fork's
+ * whole economic point is untouched).
+ *
+ * RULING ② — no new size knob. The bound is the library's own `fitContextInstructionFilesSection`
+ * (independent form: cap against the compaction model's window, disclosed elision, and a complete
+ * yield when not even the framing fits). Its three KNOWN LIMITS are accepted here KNOWINGLY, as the
+ * pre-condition of this wiring rather than something it discovered: a token-dense payload (CJK,
+ * emoji) can pass a chars-domain fit and still overflow the gateway's tokenizer; an unknown
+ * `contextWindow` leaves the section unbounded (the conversation clamp declines to guess there too);
+ * and the FORK form cannot fit at all — its bound is a prompt-too-long that degrades ONCE to the
+ * independent form, which the engine's own note records as real but NOT total (an oversize rejection
+ * the classifier cannot read as prompt-too-long returns terminally instead).
+ *
+ * HOW BIG THAT ACCEPTANCE ACTUALLY IS — measured, because the sentence above is easy to read more
+ * comfortably than it deserves. The fitted form is NOT the default path: when a fork is eligible and
+ * the model answers in its envelope, the fork IS the pass, and its section is delivered WHOLE at any
+ * size. The independent form — the only one that fits — runs when there is no fork to take or the
+ * fork's answer did not conform. Both facts are pinned in the REF-A2 suite (a 55 KB payload: whole on
+ * the fork, elided on the independent fallback). And when a limit does bite, the failure is not a
+ * quiet degradation: the section is a FIXED part of the request, the reactive retry loop may drop
+ * only CONVERSATION groups, so a request the SECTION overflowed cannot converge and the boundary
+ * fails — the task loses that compaction (or that prompt-too-long recovery, or its end-of-task
+ * summary) rather than sending a shorter one. The exposure is what the wiring widened: this was
+ * previously reachable only by hosts calling the library directly, and is now reachable by every
+ * deployment that wires `loadProjectMemory` with a large instruction file and an unknown or small
+ * window. Making the section participate in the retry loop is the structural answer; it is a change
+ * to that loop's contract, tracked at the library face, and a runner-side knob would only move the
+ * decision to a place with less information.
+ *
+ * WHAT IT COSTS, measured rather than rounded: every deployment that wires `loadProjectMemory` now
+ * sends its instruction-file content plus EXACTLY 716 chars of framing (the preamble and the fence)
+ * on EVERY summarization request, both forms, once per pass — where a real project instruction file
+ * in this family runs to tens of KB, so the payload, not the framing, is the bill. The number is
+ * pinned in the REF-A2 suite against the engine's own renderer, so a preamble edit shows up as a
+ * changed assertion rather than as prose drifting away from the code it describes.
+ * Deployments that never wired the loader pay nothing: the key is absent, not
+ * `undefined`, so their requests are byte-identical to the pre-wiring shape on the independent and
+ * UPDATE passes (the FORK form appends its ~860-char authority clause with or without the seat, and
+ * always did).
+ */
+export declare function contextInstructionFilesOption(prepared: Prepared): Partial<Pick<MaybeCompactOptions, "contextInstructionFiles">>;
 /**
  * design/169-A — the CC-form fork seam, assembled identically on all three lanes (REF-A2): the
  * summary request forks the main lane's latest real request (recorded by prepare-task's provider

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

@@ -14,6 +14,9 @@ export function buildWorkingFileAttachments(spec, prepared) {
         ...(typeof spec.compaction?.attachWorkingFiles === "object" ? spec.compaction.attachWorkingFiles : undefined),
     };
 }
+export function contextInstructionFilesOption(prepared) {
+    return prepared.projectInstructionContent !== undefined ? { contextInstructionFiles: prepared.projectInstructionContent } : {};
+}
 export function forkContextOption(prepared, disable) {
     return disable ? {} : { forkContext: prepared.lastBrainContext };
 }

package/dist/core/runner/memory-capture-optout.d.ts

@@ -0,0 +1,80 @@
+/**
+ * design/383 §3 — the session capture opt-out's ENTITLEMENT ADJUDICATOR (slice 3's core): one pure
+ * function every ingress shares — the prepare-time declaration, the resume-time standing-record
+ * re-check (§3.3), and the Runner flip verb's fresh-resolve closure — so the posture table cannot
+ * fork across call sites.
+ *
+ * The separation law (§3.3) is the module's spine: THIS adjudicator answers "may the declaration /
+ * the continued run proceed"; the one-way control-plane RECORD answers "how does this session run"
+ * (record wins for capture — nothing here ever re-enables capture for a recorded session; the
+ * governed/capture-required continuation arm refuses to RUN instead, keeping both promises: zero
+ * capture and zero out-of-policy running, availability paid).
+ *
+ * The two fault polarities, and why both are deliberate (the code-side home of the §3.1 cost
+ * table):
+ *  - `"open"` (and absent): a resolver fault ALLOWS the opt-out (+ named disclosure). Wrongly
+ *    allowing costs one uncaptured session — recoverable. Wrongly denying captures a session whose
+ *    user explicitly said no — irreversible (read, foldable into products, syncable). The
+ *    fail-safe faces the irreversible side's OPPOSITE, which is why this member is the documented
+ *    exception to the caps family's deny-on-outage degrade.
+ *  - `"governed"`: the deployment has EXPLICITLY declared the compliance side's irreversibility
+ *    (a retention-required principal acquiring an opt-out through an outage window) the heavier
+ *    one, so a fault/absent verdict refuses the run — fail-closed, the declared direction.
+ * A mutation flipping the governed fault arm to the open polarity must turn the G-姿态 escape pin
+ * red (m12).
+ */
+/** The screened posture (prepare-config-doors folds absent → `"open"`). */
+export type MemoryCapturePosture = "open" | "governed" | "capture-required";
+/** The per-principal entitlement input as RESOLVED for this adjudication:
+ *  - `value` — `RuntimeCaps.allowMemoryOptOut` when the resolver answered a boolean; `undefined`
+ *    when absent OR when the resolver faulted (the F2 fault-transit contract: a fault must never
+ *    be encoded as an explicit value);
+ *  - `faulted` — the resolve THREW / timed out / answered a non-boolean (the non-boolean case is
+ *    a fault by the member's own contract, never truthiness-read). Distinguished from a clean
+ *    `undefined` only for DISCLOSURE under `"open"` (both allow there) — under `"governed"` both
+ *    are the same refusal (verdict absent = face fault). */
+export interface CaptureEntitlementInput {
+    value: boolean | undefined;
+    faulted: boolean;
+}
+export type CaptureOptOutVerdict = {
+    allowed: true;
+    /** Present ⇔ the open-posture fault arm fired: the opt-out takes effect AND the caller owes
+     *  the named `onError({phase:"config"})` disclosure line (this string). */
+    faultDisclosure?: string;
+} | {
+    allowed: false;
+    /** Always `memory.capture_optout_denied` (terminal). The caller throws it; a DECLARATION
+     *  denial must leave zero record residue (§2.1 order invariant — adjudicate BEFORE marking). */
+    code: "memory.capture_optout_denied";
+    detail: string;
+};
+/**
+ * Adjudicate one capture opt-out ingress. `subject` names what is being adjudicated, for the
+ * refusal detail only: `"declaration"` (a `capture:"off"` spelling / the flip verb) or
+ * `"standing-record"` (a resumed session whose one-way record stands — §3.3: under
+ * governed/capture-required the question is whether the run may CONTINUE; the record's zero-capture
+ * promise is not on the table).
+ */
+export declare function adjudicateCaptureOptOut(input: {
+    posture: MemoryCapturePosture;
+    entitlement: CaptureEntitlementInput;
+    subject: "declaration" | "standing-record";
+}): CaptureOptOutVerdict;
+/** The typed terminal refusal builder (one spelling for every ingress). */
+export declare function captureOptOutDeniedError(detail: string): Error & {
+    code: string;
+};
+/** The typed could-not-record refusal (§2.8 — never a success notice's sibling; the caller mints
+ *  {@link import("../memory-engine/engine.js").memoryCaptureOptOutUnpersistedNotice} beside it).
+ *
+ *  `ingress` is REQUIRED (internal builder, both call sites in prepare-memory state it): the two
+ *  arms' throws settle different things and the message must say which. The declaration arm's throw
+ *  is whitelisted out of prepare-memory's fail-open catch and refuses the RUN; the host flip verb's
+ *  throw rejects only the verb promise — `captureOptedOut` is assigned below it — so the run
+ *  continues with capture still ON. One sentence for both said "refusing to run", which was false
+ *  in the direction that matters: it told the caller the session had stopped capturing when it had
+ *  not. */
+export declare function captureOptOutUnpersistedError(sessionId: string, ingress: "declaration" | "flip-verb"): Error & {
+    code: string;
+};

package/dist/core/runner/memory-capture-optout.js

@@ -0,0 +1,53 @@
+export function adjudicateCaptureOptOut(input) {
+    const { posture, entitlement, subject } = input;
+    const what = subject === "standing-record" ? "continuing a session whose one-way capture opt-out record stands" : "the session memory-capture opt-out declaration";
+    if (posture === "capture-required") {
+        return {
+            allowed: false,
+            code: "memory.capture_optout_denied",
+            detail: `${what} is refused: this deployment declares memoryCapturePolicy "capture-required" (forced retention, resolver-independent). ` +
+                (subject === "standing-record"
+                    ? `The standing record keeps its zero-capture promise — the session is refused rather than run out of policy; start a new session without the opt-out.`
+                    : `Remove the memory.capture declaration and resubmit.`),
+        };
+    }
+    if (posture === "governed") {
+        if (entitlement.value === true)
+            return { allowed: true };
+        return {
+            allowed: false,
+            code: "memory.capture_optout_denied",
+            detail: entitlement.value === false
+                ? `${what} is refused: the entitlement resolver answered allowMemoryOptOut=false for this principal (governed posture — the deployment requires capture for it).`
+                : `${what} is refused: memoryCapturePolicy "governed" requires an explicit per-principal allowMemoryOptOut verdict and none was resolvable (${entitlement.faulted ? "resolver fault" : "verdict absent"}) — fail-closed by the deployment's own declaration (a retention-required principal must not acquire an opt-out through an outage window).`,
+        };
+    }
+    if (entitlement.value === false) {
+        return {
+            allowed: false,
+            code: "memory.capture_optout_denied",
+            detail: `${what} is refused: the entitlement resolver answered allowMemoryOptOut=false for this principal.`,
+        };
+    }
+    if (entitlement.faulted) {
+        return {
+            allowed: true,
+            faultDisclosure: `the runtime-caps resolve faulted while adjudicating a memory-capture opt-out; under the "open" posture the opt-out takes effect anyway ` +
+                `(privacy-side irreversibility wins the fault arm — an explicit allowMemoryOptOut=false is the only denial). Repair the resolver if denial was intended.`,
+        };
+    }
+    return { allowed: true };
+}
+export function captureOptOutDeniedError(detail) {
+    const e = new Error(`memory capture opt-out denied: ${detail}`);
+    e.code = "memory.capture_optout_denied";
+    return e;
+}
+export function captureOptOutUnpersistedError(sessionId, ingress) {
+    const e = new Error(`memory capture opt-out could not be durably recorded for session ${sessionId} (control-plane write failed) — ` +
+        (ingress === "declaration"
+            ? `refusing to run under an opt-out that would silently stop holding at the next resume. Nothing ran and nothing was captured.`
+            : `the opt-out request is REJECTED and not applied: the run continues with memory capture still ON. Nothing was recorded, so an identical retry fails the same way.`));
+    e.code = "memory.capture_optout_unpersisted";
+    return e;
+}

package/dist/core/runner/prepare-config-doors.d.ts

@@ -196,6 +196,11 @@ export interface PrepareConfigDoorsResult {
      *  the synchronous pre-await stretch, screened (#123), absent folded to the `"carry"` default.
      *  The memory phase constructs every engine with THIS value — never a live deps re-read. */
     memoryProvenance: "off" | "carry";
+    /** owned — the NORMALIZED memory-capture posture (design/383 §3.1): the deps seat read ONCE,
+     *  screened (#123 — a bad value refuses, never folds), absent folded to `"open"`. The capture
+     *  opt-out adjudicator consumes THIS value on every leg (declaration, resume record re-check,
+     *  and the flip verb's frozen closure) — never a live deps re-read. */
+    memoryCapturePolicy: "open" | "governed" | "capture-required";
     /** owned — validated deployment governance windows (undefined = ungoverned). */
     usageWindows: readonly UsageWindow[] | undefined;
     /** owned, out-param cell — created EMPTY here; the brain-call wiring later installs into

package/dist/core/runner/prepare-config-doors.js

@@ -225,6 +225,21 @@ export function prepareConfigDoors(input) {
         throw e;
     }
     const memoryProvenance = memoryProvenanceRaw === "off" ? "off" : "carry";
+    const memoryCapturePolicyRaw = deps.memoryCapturePolicy;
+    if (memoryCapturePolicyRaw !== undefined && memoryCapturePolicyRaw !== "open" && memoryCapturePolicyRaw !== "governed" && memoryCapturePolicyRaw !== "capture-required") {
+        const got = typeof memoryCapturePolicyRaw === "string"
+            ? JSON.stringify(memoryCapturePolicyRaw.length > 64 ? `${memoryCapturePolicyRaw.slice(0, 64)}…` : memoryCapturePolicyRaw)
+            : memoryCapturePolicyRaw === null
+                ? "null"
+                : Array.isArray(memoryCapturePolicyRaw)
+                    ? "an array"
+                    : typeof memoryCapturePolicyRaw;
+        const e = new Error(`RunnerDeps.memoryCapturePolicy must be "open", "governed" or "capture-required" when present (got ${got}) — ` +
+            `an unevaluable capture posture is refused loudly, never folded to any posture (the fault arms differ per posture, so a guess would pick a polarity nobody configured).`);
+        e.code = "config.memory_capture_policy";
+        throw e;
+    }
+    const memoryCapturePolicy = memoryCapturePolicyRaw === "governed" ? "governed" : memoryCapturePolicyRaw === "capture-required" ? "capture-required" : "open";
     if (spec.resumeAtMode !== undefined) {
         if (spec.resumeAt === undefined) {
             const e = new Error(`resumeAtMode "${spec.resumeAtMode}" requires resumeAt (there is no branch target to position against)`);
@@ -420,6 +435,7 @@ export function prepareConfigDoors(input) {
         modelGate,
         memoryDelegationEvidence,
         memoryProvenance,
+        memoryCapturePolicy,
         usageWindows,
         brainCallGuardrailRef,
         brainCallGuardrailMs,