@sema-agent/core 5.22.0 → 5.23.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 5.23.0 — 2026-08-10
+
+No BREAKING changes.
+
+### Added
+
+- **design/183 adoption protocol, core file half.** Root adoption marker + six-phase
+  `adoptLocalDataRoot` state machine + `readAdoptionStatus` standing introspection + config account
+  (witness/ack) + quarantine listing; 23 new exports. The I6 boot gate is a new refusal surface: every
+  file-store constructor under a root whose `adoption.json` marker is IN FLIGHT throws
+  `AdoptionError("adoption_in_flight")` (corrupt marker: `adoption_marker_corrupt`, fail-closed).
+  Roots without a marker are untouched. The terminal report carries `notMigratedByDesign` — the
+  machine-readable closed set of assets ruled to stay local, sharded per migration form.
+- **design/182 org layer wired into the decision chain** (org-governed deployments only): org deny
+  blocks on both the main gate and the durable-resume leg; an unavailable org snapshot past
+  `ORG_ADJUDICATION_TIMEOUT_MS` (15s, mandatory at both call sites) downgrades every terminal allow
+  to a human ask, fail-closed. Closed-set additions consumers should re-pin: `DecisionReason`
+  +`org_rule`/`org_unavailable`; `PermissionDeniedSource` +`org`; `TraceEvent`
+  +`rule_sync_resurrected`/`rule_sync_dropped`/`org_snapshot_unavailable`.
+- `AskOutcome` terminal arms accept an optional `settledBy` (host self-report; `allow` × `"timeout"`
+  is loudly refused); `GoalResult.budgetCause` names which ceiling ended a budget run;
+  `NON_GOVERNANCE_MEMORY_CODES` +3 members (`memory.challenge_ledger_oversize`,
+  `memory.control_plane_rebuilt`, `memory.control_plane_not_corrupt`);
+  `MemoryEngine.rebuildCorruptControlPlaneLedger` (host-only, refuses a healthy ledger, quarantines
+  corrupt bytes) and `CHALLENGE_LEDGER_MAX_EVENTS` disclosure threshold.
+
+### Fixed / narrowed
+
+- **#109**: separated option values (`head -c 5`, `cut -f 1`, `grep -A 3 pat`, …) are no longer
+  counted as file operands by the read-only shell classifier — fileless forms of these commands now
+  ask instead of auto-passing.
+- **#110**: a checkpoint `put` that errors but whose row is durably present (read-back claims it)
+  suspends instead of running on; `put`+`get` both failing aborts the run fail-closed.
+- **#114**: `settledBy:"timeout"` documented promise narrowed to the two core-managed wait windows.
+- **#115**: the offload truncation notice states where the remainder IS instead of implying any
+  caller can fetch it.
+- Consent-record ids and the in-memory CRDT actor default now take real entropy (`randomBytes`);
+  format is opaque, do not parse.
+
+### Tooling
+
+- New `gate:error-surface` (four invariants over model-visible error minting: no `.stack`,
+  >400-char templates ledgered, uncapped-arm ratchet, verbatim-guidance dedup) wired into CI.
+- The environment-knob surface (25 names) is under an exhaustive AST-driven liveness registry;
+  `docs/CONFIG-CATALOG-GUIDE.md` gained the environment-knobs chapter (two comment-only pseudo-knobs
+  called out: `MAX_TOOL_CONCURRENCY`, `APPROVAL_TTL_MS` — setting them has no effect).
+
 ## 5.22.0 — 2026-08-09
 
 ### BREAKING

package/dist/agents/subagent.js

@@ -1,6 +1,7 @@
 import { Type } from "typebox";
 import { isAbsolute } from "node:path";
 import { withDelegationProvenance } from "../core/tool-policy.js";
+import { isHighSurrogate, isLowSurrogate } from "../core/surrogate-safe-slice.js";
 import { newDelegationProvenanceAggregate, reduceDelegationAttestation } from "../core/memory-engine/delegation-provenance.js";
 import { resolveModel, resolveModelDisplayLabel } from "../core/roles.js";
 import { OUTPUT_TOOL_NAME, REPORT_BLOCKED_TOOL_NAME } from "../core/runner/synthetic-tools.js";
@@ -65,8 +66,8 @@ function defuseGapMarkers(slice) {
     return slice.replace(/\[…/g, `${REVIEW_MARKER_SCAR}…`);
 }
 function surrogateSafeSlice(text, from, width, anchorEnd = false) {
-    const isLow = (i) => text.charCodeAt(i) >= 0xdc00 && text.charCodeAt(i) <= 0xdfff;
-    const isHigh = (i) => text.charCodeAt(i) >= 0xd800 && text.charCodeAt(i) <= 0xdbff;
+    const isLow = (i) => isLowSurrogate(text.charCodeAt(i));
+    const isHigh = (i) => isHighSurrogate(text.charCodeAt(i));
     let start = from;
     if (start > 0 && start < text.length && isLow(start) && isHigh(start - 1))
         start--;

package/dist/core/governance-codes.js

@@ -17,6 +17,9 @@ export const NON_GOVERNANCE_MEMORY_CODES = new Set([
     "memory.challenge_sweep_failed",
     "memory.lineage_settle_failed",
     "memory.challenge_ledger_corrupt",
+    "memory.challenge_ledger_oversize",
+    "memory.control_plane_rebuilt",
+    "memory.control_plane_not_corrupt",
 ]);
 export function governanceRetryClass(code) {
     if (Object.prototype.hasOwnProperty.call(GOVERNANCE_CODES, code)) {

package/dist/core/hooks.d.ts

@@ -161,8 +161,13 @@ export interface Hooks {
  *  - `"shellGate"` — same tighten-deny, but the tool's irreversibility tier was installed by the COARSE
  *    `TaskSpec.shellGate` doctrine (design/80 D-E), not an explicit per-tool mark.
  *  - `"planMode"` — the design/108 plan-mode write-deny short-circuit (a read-only fidelity gate).
+ *  - `"org"` (design/182 §7) — the ORG layer: an organization deny rule, or the fail-closed tighten an
+ *    org-governed deployment applies while it cannot adjudicate against a snapshot (that tighten's ask
+ *    then resolving to deny). Its own word rather than `"policy"` because the authority is the ORG's
+ *    published snapshot, not this deployment's `ToolPolicy` — an operator reading "policy" on a call
+ *    their own policy allowed would be looking in the wrong place.
  */
-export type PermissionDeniedSource = "policy" | "hook" | "safety" | "shellGate" | "planMode" | "classifier";
+export type PermissionDeniedSource = "policy" | "hook" | "safety" | "shellGate" | "planMode" | "classifier" | "org";
 /** The payload a {@link Hooks.permissionDenied} callback observes (CC-exact fields + `source`). */
 export interface PermissionDeniedPayload {
     toolName: string;
@@ -520,6 +525,26 @@ export interface ParkAttemptFailed {
     /** Why the park could not be minted — a sentence, already worded for a reader. */
     parkFailed: string;
 }
+/**
+ * design/182 §7 — what the ORG layer answers for ONE call (see `ToolGateInput.orgRules`).
+ *
+ * The two arms are distinguished by `status`, NEVER by the absence of a verdict: "the org published no
+ * rule for this call" and "this deployment cannot see the org's rules" are opposite facts, and reading
+ * an empty answer as the first one is exactly the governance fail-open the availability contract exists
+ * to prevent.
+ */
+export type OrgGateVerdict = {
+    status: "available";
+    /** The org rule that speaks for this call, if any. Deny outranks ask; there is no allow bucket. */
+    verdict?: {
+        behavior: "deny" | "ask";
+        rule: string;
+    };
+} | {
+    status: "unavailable";
+    /** The overlay's own disclosure lines (engine/deployment-authored), for the operator channel. */
+    disclosures: readonly string[];
+};
 /** Inputs to the two-phase tool gate. `adjudicate`/`resolveAsk` are pre-bound to the task abort signal. */
 export interface ToolGateInput {
     /** RB-473 batch 2b — bounded disclosure for a HOST callback that throws inside this gate call's
@@ -713,6 +738,42 @@ export interface ToolGateInput {
             rule: string;
         }) => void;
     };
+    /**
+     * design/182 §7 — the ORG layer. Present ONLY when the deployment DECLARED org governance (the
+     * overlay constructor is the boot gate: a governed declaration with no snapshot provider refuses to
+     * boot). Absent ⇒ the whole step does not exist and the decision path is byte-identical.
+     *
+     * The org layer is the outermost TIGHTENING authority, so it runs after every fold and every engine
+     * tighten and before the ask-resolution chain — "org deny > org ask (non-dismissable) > personal
+     * allow rule > bare ask". It never loosens: there is structurally no org allow bucket.
+     *
+     * The `unavailable` arm is the load-bearing one. An org-governed deployment that cannot reach a
+     * snapshot fails the WHOLE decision boundary closed — every terminal allow (a deployment-policy
+     * allow and the no-policy default allow included) becomes an ask carrying
+     * `decisionReason: "org_unavailable"` AND `requiresRealApproval: true`, and both ask→allow seams (the
+     * personal-rule lane and the auto-mode classifier) are disarmed. Tightening only the two seams was
+     * refuted during design: a call that is ALREADY allow never passes through either seam, so it would
+     * have sailed past the org deny that could not be read. The `requiresRealApproval` bit closes the
+     * third loosening path — a blanket `onAsk: "allow"` would otherwise clear the synthetic ask.
+     */
+    orgRules?: {
+        /** Adjudicate this call against the current org overlay. MUST NOT throw — a throw is read as
+         *  `unavailable` (fail-closed), never as "no org rule spoke". */
+        adjudicate: (req: ToolCallRequest) => Promise<OrgGateVerdict>;
+        /** True iff the reserved question-tool NAME on this leg resolves to the ENGINE's own content-ask
+         *  tool. It is the exemption's real predicate: the name alone is not, because a caller may mount
+         *  its own tool under that name when the first-party one is not mounted, and such a tool has
+         *  arbitrary side effects (codex review, confirmed MED). Absent ⇒ `false` ⇒ the call is governed
+         *  like any other, which is the fail-closed default. */
+        contentAskToolMounted?: boolean;
+        /** Disclosure sink for the unavailable arm (trace `permission.org_snapshot_unavailable`). Never
+         *  affects the outcome. */
+        onUnavailable?: (info: {
+            toolName: string;
+            toolCallId: string;
+            message: string;
+        }) => void;
+    };
     /**
      * F-012 L2 — the SANDBOX ADMISSION leg. Present ONLY when the runner armed the mode: the execution
      * env DECLARES isolation (`RemoteExecutionEnv.capabilities.isolation === true` — a Runner-resolved

package/dist/core/hooks.js

@@ -3,6 +3,7 @@ import { brandPolicyAskClass } from "./ask-class.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "./ask-question.js";
 import { createSafeNotifier } from "./safe-notify.js";
+import { ORG_ADJUDICATION_TIMEOUT_MS, ORG_RULE_DECISION_REASON, ORG_UNAVAILABLE_DECISION_REASON, settleOrgVerdictWithin } from "./permission-rule-org.js";
 export function cloneObserverInput(input) {
     try {
         return structuredClone(input);
@@ -246,12 +247,73 @@ export async function runToolGate(input) {
             denySource = input.shellGated === true ? "shellGate" : "safety";
         }
     }
+    let orgRealApprovalRequired = false;
+    let orgTightenCount = 0;
+    const applyOrgLayer = async (current, args) => {
+        if (input.orgRules === undefined)
+            return current;
+        if (toolName === ASK_USER_QUESTION_TOOL_NAME && input.orgRules.contentAskToolMounted === true)
+            return current;
+        let decided = current;
+        const answer = await settleOrgVerdictWithin(input.orgRules
+            .adjudicate({ toolName, args, toolCallId })
+            .catch((err) => ({
+            status: "unavailable",
+            disclosures: [`the org adjudication face threw: ${err instanceof Error ? err.message : String(err)}`],
+        })), {
+            status: "unavailable",
+            disclosures: [`the org adjudication face did not answer within ${ORG_ADJUDICATION_TIMEOUT_MS}ms (or the task ended first)`],
+        }, { ...(input.abortSignal !== undefined ? { signal: input.abortSignal } : {}), timeoutMs: ORG_ADJUDICATION_TIMEOUT_MS });
+        if (answer.status === "unavailable") {
+            orgRealApprovalRequired = true;
+            await notifier.notifyAsync(() => input.orgRules?.onUnavailable?.({ toolName, toolCallId, message: answer.disclosures.join("; ") }), "toolGate.orgSnapshotUnavailable");
+            if (decided.action === "allow") {
+                decided = {
+                    action: "ask",
+                    message: `tool "${toolName}" needs approval: this deployment is org-governed and cannot currently adjudicate ` +
+                        `against an organization policy snapshot — every allow tightens to a real approval until it can`,
+                    decisionReason: ORG_UNAVAILABLE_DECISION_REASON,
+                    requiresRealApproval: true,
+                };
+                orgTightenCount += 1;
+                denySource = "org";
+            }
+            else if (decided.action === "ask" && decided.requiresRealApproval !== true) {
+                decided = { ...decided, requiresRealApproval: true };
+                orgTightenCount += 1;
+            }
+            return decided;
+        }
+        if (answer.verdict === undefined)
+            return decided;
+        const { behavior, rule } = answer.verdict;
+        if (behavior === "deny") {
+            orgTightenCount += 1;
+            denySource = "org";
+            return { action: "deny", message: `an organization policy rule (${rule}) denies this call`, decisionReason: ORG_RULE_DECISION_REASON };
+        }
+        if (decided.action === "deny")
+            return decided;
+        orgTightenCount += 1;
+        denySource = "org";
+        orgRealApprovalRequired = true;
+        return decided.action === "ask"
+            ? { ...decided, requiresRealApproval: true }
+            : {
+                action: "ask",
+                message: `an organization policy rule (${rule}) requires approval for this call`,
+                decisionReason: ORG_RULE_DECISION_REASON,
+                requiresRealApproval: true,
+            };
+    };
+    decision = await applyOrgLayer(decision, policyRewrite !== undefined ? policyRewrite : currentInput);
     if (decision.action === "ask") {
         if (policyRewrite !== undefined) {
             currentInput = policyRewrite;
             req.args = policyRewrite;
         }
         if (input.persistedRules &&
+            !orgRealApprovalRequired &&
             decision.action === "ask" &&
             decision.requiresRealApproval !== true &&
             decision.decisionReason !== "hook" &&
@@ -269,6 +331,7 @@ export async function runToolGate(input) {
             }
         }
         if (input.autoMode &&
+            !orgRealApprovalRequired &&
             decision.action === "ask" &&
             req.toolName !== ASK_USER_QUESTION_TOOL_NAME &&
             input.isMarkedUnresolvable?.(input.event.toolCallId) !== true) {
@@ -418,23 +481,34 @@ export async function runToolGate(input) {
                                 editArgs = hr.updatedInput;
                         }
                     }
-                    if (!adjudicate)
+                    if (!adjudicate && input.orgRules === undefined)
                         break;
-                    let recheck;
-                    try {
-                        recheck = await adjudicate({ toolName, args: editArgs, toolCallId });
-                    }
-                    catch (err) {
-                        recheck = {
-                            action: "deny",
-                            message: `policy re-check of the approved edit for "${toolName}" errored: ${err instanceof Error ? err.message : String(err)}`,
-                        };
+                    let recheck = { action: "allow" };
+                    if (adjudicate) {
+                        try {
+                            recheck = await adjudicate({ toolName, args: editArgs, toolCallId });
+                        }
+                        catch (err) {
+                            recheck = {
+                                action: "deny",
+                                message: `policy re-check of the approved edit for "${toolName}" errored: ${err instanceof Error ? err.message : String(err)}`,
+                            };
+                        }
                     }
                     if (recheck.action === "deny") {
                         editDenied = recheck;
                         denySource = "policy";
                         break;
                     }
+                    if (recheck.updatedInput !== undefined)
+                        editArgs = recheck.updatedInput;
+                    const orgTightensBefore = orgTightenCount;
+                    recheck = await applyOrgLayer(recheck, editArgs);
+                    const orgRaisedThisRound = orgTightenCount > orgTightensBefore;
+                    if (recheck.action === "deny") {
+                        editDenied = recheck;
+                        break;
+                    }
                     if (recheck.action === "allow") {
                         if (recheck.updatedInput !== undefined)
                             editArgs = recheck.updatedInput;
@@ -445,11 +519,15 @@ export async function runToolGate(input) {
                     const rr = await resolveAsk(recheck, { toolName, args: editArgs, toolCallId });
                     if (rr.action !== "allow") {
                         editDenied = rr;
-                        denySource = "policy";
+                        if (!orgRaisedThisRound)
+                            denySource = "policy";
                         break;
                     }
-                    if (rr.updatedInput === undefined)
+                    if (rr.updatedInput === undefined) {
+                        if (rr.presentedInput !== undefined)
+                            editArgs = rr.presentedInput;
                         break;
+                    }
                     editArgs = rr.updatedInput;
                 }
                 decision = editDenied ?? { ...decision, updatedInput: editArgs };

package/dist/core/memory-engine/engine.d.ts

@@ -1,4 +1,4 @@
-import { type ChallengeAssignment, type ChallengeEvent, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, type MemoryPartitionIncidentSink, type RetrievedAccountRow, type SessionPollutionRecord } from "./layout.js";
+import { type ChallengeAssignment, type ChallengeEvent, type ControlPlaneRebuildReceipt, type StrictControlPlaneLedger, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, type MemoryPartitionIncidentSink, type RetrievedAccountRow, type SessionPollutionRecord } from "./layout.js";
 import type { HarvestReport, MemoryAnnouncement, MemoryBackend, MemorySessionHandle, ScanFinding } from "./types.js";
 /**
  * The CC `# Memory` instruction section — VERBATIM from the live capture
@@ -220,6 +220,33 @@ export declare class MemoryEngine {
      *  generation only — the announcement is a model-visible face, so no name/description/free reason
      *  rides it; content stays on the host audit face). Failures are disclosed, never thrown past. */
     private challengeAndAnnounce;
+    /** design/180 §10 — one disclosure per PROCESS per engine, not one per append: the size is a
+     *  standing property of the account, and repeating it on every challenge is the spam that gets
+     *  advisories muted (the same argument the durable-park disclosures are built on). */
+    private challengeLedgerSizeDisclosed;
+    /**
+     * design/180 §10 — the challenge ledger's size bound is a DISCLOSURE threshold, never a cap: the
+     * ledger cannot be rotated (the exclusion predicate is derived from the events, so dropping the
+     * oldest rows would un-withhold their entries), so crossing {@link CHALLENGE_LEDGER_MAX_EVENTS}
+     * changes nothing about what is withheld — it tells the deployment that an account on the
+     * per-tool-call read path has grown to where it costs the session latency.
+     */
+    private discloseChallengeLedgerSize;
+    /**
+     * design/180 §10 — the RECOVERY channel for a corrupt fail-closed ledger (lineage / challenges).
+     *
+     * The fail-closed family refuses every read on corruption so a silent "start fresh" cannot launder
+     * taint; permanent refusal is the point, and it left a deployment with genuinely corrupt bytes no way
+     * back except deleting engine files by hand. This is that way back, and it is explicit in every
+     * dimension: only a host call reaches it (nothing in the engine self-heals), a HEALTHY ledger is
+     * refused (`memory.control_plane_not_corrupt`), the corrupt bytes are quarantined beside the file
+     * rather than deleted, and the rebuild ANNOUNCES itself — resetting the challenge ledger un-withholds
+     * whatever it was withholding, which the model's next session must not learn about silently.
+     *
+     * `reason` is required and recorded in the announcement's shape (not its text — the announcement is a
+     * model-visible face and stays opaque); it is the operator's own note on the host error face.
+     */
+    rebuildCorruptControlPlaneLedger(ledger: StrictControlPlaneLedger, reason: string): ControlPlaneRebuildReceipt;
     /**
      * Host API (advisory, control-plane trust level — the same plane that can mark pollution):
      * challenge entries by id. `requestId` is REQUIRED (the generation ledger's idempotency identity;

package/dist/core/memory-engine/engine.js

@@ -6,7 +6,7 @@ import { inlineUntrusted } from "../untrusted-text.js";
 import { formatMemoryAge } from "../memory-recall.js";
 import { computeEntryRev, parseEntryFile, serializeEntryFile } from "./frontmatter.js";
 import { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, scanEntryFiles } from "./file-backend.js";
-import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, readIndexRevs, writeIndexRevs, bumpScanFuse, canonicalize, claimRootScope, clearScanFuse, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, isContainedIn, markSessionPolluted, readSessionPollution, recordRetrievedAccount, writeFileNoFollow, readRetrievedAccount, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, appendChallengeEvents, appendLineageAudit, adjudicateLineagePending, challengedEntryIds, clearLineageForEntries, discardLineagePending, lineageContributionsOfSession, lineageLatchedIds, promoteLineagePending, readChallengeEvents, readChallengedHistory, readLineageRecord, recordChallengedHistory, recordLineageCredential, reconcileLineage, resolveChallengeEvent, stageLineagePending, } from "./layout.js";
+import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, readIndexRevs, writeIndexRevs, bumpScanFuse, canonicalize, claimRootScope, clearScanFuse, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, isContainedIn, markSessionPolluted, readSessionPollution, recordRetrievedAccount, writeFileNoFollow, readRetrievedAccount, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, appendChallengeEvents, appendLineageAudit, rebuildStrictControlPlaneLedger, isStrictControlPlaneLedgerCorrupt, CHALLENGE_LEDGER_MAX_EVENTS, adjudicateLineagePending, challengedEntryIds, clearLineageForEntries, discardLineagePending, lineageContributionsOfSession, lineageLatchedIds, promoteLineagePending, readChallengeEvents, readChallengedHistory, readLineageRecord, recordChallengedHistory, recordLineageCredential, reconcileLineage, resolveChallengeEvent, stageLineagePending, } from "./layout.js";
 import { scanMemoryFileName, scanMemoryWrite, scanRemediation } from "./scan.js";
 export const MEMORY_INSTRUCTION_TEMPLATE = `# Memory
 
@@ -173,7 +173,9 @@ export class MemoryEngine {
     challengeAndAnnounce(events) {
         if (events.length === 0)
             return [];
-        const assigned = appendChallengeEvents(this.controlDir, events, this.now);
+        const { assignments: assigned, eventCount } = appendChallengeEvents(this.controlDir, events, this.now);
+        if (eventCount !== undefined)
+            this.discloseChallengeLedgerSize(eventCount);
         const fresh = assigned.filter((a) => !a.replayed);
         if (fresh.length > 0) {
             try {
@@ -189,6 +191,60 @@ export class MemoryEngine {
         }
         return assigned;
     }
+    challengeLedgerSizeDisclosed = false;
+    discloseChallengeLedgerSize(eventCount) {
+        if (this.challengeLedgerSizeDisclosed || eventCount <= CHALLENGE_LEDGER_MAX_EVENTS)
+            return;
+        this.challengeLedgerSizeDisclosed = true;
+        const sink = this.onIncident;
+        if (sink === undefined)
+            return;
+        try {
+            const err = new Error(`memory challenge ledger holds ${eventCount} events, past the calibrated bound of ${CHALLENGE_LEDGER_MAX_EVENTS}: ` +
+                `the whole file is rewritten on every challenge and parsed on every model-visible read (index rebuild, memory tools), ` +
+                `so this account now costs the session latency. It is NOT rotated — dropping events would un-withhold their entries — ` +
+                `so the deployment resolves the settled generations or archives the account deliberately.`);
+            err.code = "memory.challenge_ledger_oversize";
+            sink(err);
+        }
+        catch {
+        }
+    }
+    rebuildCorruptControlPlaneLedger(ledger, reason) {
+        if (typeof reason !== "string" || reason.trim() === "") {
+            const e = new Error("rebuildCorruptControlPlaneLedger: a non-empty reason is required (this call drops taint evidence — it is recorded, never implicit)");
+            e.code = "config.memory_rebuild_reason";
+            throw e;
+        }
+        if (!isStrictControlPlaneLedgerCorrupt(this.controlDir, ledger)) {
+            const e = new Error(`${ledger === "challenges" ? "memory challenge ledger" : "memory lineage ledger"} reads cleanly — refusing to rebuild it. This call exists to recover a ledger whose corruption already refuses every read; resetting a healthy one would drop taint evidence that is still doing its job.`);
+            e.code = "memory.control_plane_not_corrupt";
+            throw e;
+        }
+        enqueueMemoryAnnouncement(this.controlDir, {
+            kind: "gate",
+            at: this.now(),
+            items: [
+                ledger === "challenges"
+                    ? `memory control plane: the challenge ledger was found CORRUPT and a deployment-initiated reset to empty was requested — entries that were withheld by an unresolved challenge may no longer be withheld. Treat facts recalled from memory as unverified until confirmed with the user.`
+                    : `memory control plane: the harvest lineage ledger was found CORRUPT and a deployment-initiated reset to empty was requested — which session contributed which entry may no longer be recorded for anything written before this point.`,
+            ],
+        });
+        const receipt = rebuildStrictControlPlaneLedger(this.controlDir, ledger, this.now);
+        const sink = this.onIncident;
+        if (sink !== undefined) {
+            try {
+                const err = new Error(`memory control plane: ${ledger} ledger rebuilt after corruption (reason: ${reason}). ` +
+                    `The corrupt bytes are quarantined at ${receipt.quarantinedTo.join(", ") || "(no file existed)"} — ` +
+                    `they are the only remaining record of what this account held.`);
+                err.code = "memory.control_plane_rebuilt";
+                sink(err);
+            }
+            catch {
+            }
+        }
+        return receipt;
+    }
     challengeEntries(ids, reason, requestId) {
         if (typeof requestId !== "string" || requestId === "") {
             const e = new Error("challengeEntries: requestId is required (idempotency identity — retries must reuse it; the engine does not mint one)");
@@ -207,7 +263,10 @@ export class MemoryEngine {
         return this.challengeAndAnnounce(contributions.map((c) => ({ eventId: `${requestId}:${c.entryId}`, entryId: c.entryId, reason, challengedRev: c.lastRev })));
     }
     resolveChallenge(entryId, generation, reason, requestId) {
-        return resolveChallengeEvent(this.controlDir, entryId, generation, reason, this.now, requestId);
+        const { resolved, eventCount } = resolveChallengeEvent(this.controlDir, entryId, generation, reason, this.now, requestId);
+        if (eventCount !== undefined)
+            this.discloseChallengeLedgerSize(eventCount);
+        return resolved;
     }
     adjudicatePendingLineage(txnId, action) {
         const promoted = adjudicateLineagePending(this.controlDir, txnId, action, this.now);

package/dist/core/memory-engine/index.d.ts

@@ -2,7 +2,7 @@ export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION
 export { MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, type MemorySearchDetails, type MemorySearchHit, type MemoryGetDetails, } from "./tools.js";
 export { scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE } from "./scan.js";
 export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH, type ScannedEntryFile } from "./file-backend.js";
-export { ControlPlaneCorruptError, deriveControlPlaneDir, deriveRepoControlPlaneDir, deriveRepoKey, deriveRepoMemoryDir, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, claimRootScope, rootScopeOf, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, type ChallengeAssignment, type ChallengeEvent, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, } from "./layout.js";
+export { ControlPlaneCorruptError, deriveControlPlaneDir, deriveRepoControlPlaneDir, deriveRepoKey, deriveRepoMemoryDir, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, claimRootScope, rootScopeOf, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, type ControlPlaneRebuildReceipt, type StrictControlPlaneLedger, type ChallengeAppendResult, type ChallengeAssignment, type ChallengeEvent, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, } from "./layout.js";
 export { readV2HeaderHints, type V2HeaderHints } from "./header-hints.js";
 export { parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, type ParsedEntryFile } from "./frontmatter.js";
 export type { MemoryBackend, MemoryEntry, MemoryEntryFrontmatter, MemoryEntryHeader, ScoredMemoryEntry, NotePatch, PatchReport, MaterializedFile, MemorySessionHandle, HarvestReport, HarvestRejection, HarvestRejectionCode, MemoryAnnouncement, ScanFinding, } from "./types.js";

package/dist/core/memory-engine/index.js

@@ -2,7 +2,7 @@ export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION
 export { MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, } from "./tools.js";
 export { scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE } from "./scan.js";
 export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH } from "./file-backend.js";
-export { ControlPlaneCorruptError, deriveControlPlaneDir, deriveRepoControlPlaneDir, deriveRepoKey, deriveRepoMemoryDir, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, claimRootScope, rootScopeOf, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, } from "./layout.js";
+export { ControlPlaneCorruptError, deriveControlPlaneDir, deriveRepoControlPlaneDir, deriveRepoKey, deriveRepoMemoryDir, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, claimRootScope, rootScopeOf, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, } from "./layout.js";
 export { readV2HeaderHints } from "./header-hints.js";
 export { parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile } from "./frontmatter.js";
 export { memoryBackendContract, assertMemoryBackendSearchEquivalence, } from "./memory-backend-contract.js";

package/dist/core/memory-engine/layout.d.ts

@@ -402,6 +402,33 @@ export interface ChallengeAssignment {
     at: number;
     replayed: boolean;
 }
+/**
+ * design/180 §10 — the challenge ledger's SIZE CALIBRATION.
+ *
+ * The ledger is append-only and cannot be rotated: the exclusion predicate is DERIVED from the events
+ * ("a challenge generation with no matching resolve"), so dropping the oldest rows would silently
+ * un-withhold their entries — taint laundering, the exact failure the fail-closed family exists to
+ * prevent. The bound is therefore a DISCLOSURE threshold, not a cap: crossing it changes nothing about
+ * what the ledger holds, it tells the deployment the account needs attention.
+ *
+ * Calibrated against what actually degrades, which is not disk: every append REWRITES the whole file
+ * under the strict lock, and every model-visible read path ({@link challengedEntryIds}, called on each
+ * index rebuild and each memory tool call) PARSES it whole. At ~200 bytes per event, 10k events is a
+ * ~2 MB parse on a read path that runs per tool call — the point where "an audit account nobody looks
+ * at" becomes a latency the session feels. A deployment reaching it should resolve the settled
+ * generations (they stay in the file, and that is the point) or archive the account deliberately.
+ */
+export declare const CHALLENGE_LEDGER_MAX_EVENTS = 10000;
+/** What {@link appendChallengeEvents} returns: the per-request assignments plus the ledger's size
+ *  AFTER the append — the caller owns disclosure (this module has no sink), and reading the size here
+ *  costs nothing because the record is already in hand under the lock. */
+export interface ChallengeAppendResult {
+    assignments: ChallengeAssignment[];
+    /** Total events in the ledger after this append, or `undefined` when nothing was appended — the
+     *  empty-request fast path takes no lock and reads nothing, so it has no size to report and must not
+     *  report a made-up `0` (a caller comparing that against the bound would read "tiny", not "unknown"). */
+    eventCount: number | undefined;
+}
 /** Append S-grade challenge events (idempotent per eventId, generation allocation inside the strict
  *  lock). Every NEW eventId opens a NEW generation for its entry — a resolve of an earlier
  *  generation never immunizes the entry against later pollution (design/180 R-8). */
@@ -410,11 +437,20 @@ export declare function appendChallengeEvents(controlDir: string, events: Readon
     entryId: string;
     reason: string;
     challengedRev?: string;
-}>, now: () => number): ChallengeAssignment[];
+}>, now: () => number): ChallengeAppendResult;
 /** The trusted resolve: closes EXACTLY the named generation (a later challenge's generation stays
  *  open — resolves never blanket-clear). Idempotent: resolving an already-resolved generation is a
- *  no-op. Returns false ⇔ no such open generation existed. */
-export declare function resolveChallengeEvent(controlDir: string, entryId: string, generation: number, reason: string, now: () => number, requestId?: string): boolean;
+ *  no-op. `resolved` is false ⇔ no such open generation existed.
+ *
+ *  `eventCount` rides along for the same reason it does on {@link appendChallengeEvents}: a resolve
+ *  APPENDS an event too, so it crosses the size bound exactly as a challenge does (independent
+ *  adversarial review, verified — hanging the disclosure off the challenge writer alone leaves a ledger
+ *  that crossed the bound on a resolve silent until the next challenge, which may never come).
+ *  `undefined` when nothing was appended. */
+export declare function resolveChallengeEvent(controlDir: string, entryId: string, generation: number, reason: string, now: () => number, requestId?: string): {
+    resolved: boolean;
+    eventCount: number | undefined;
+};
 /** The exclusion predicate's input: entry id → its LATEST unresolved challenge generation. An entry
  *  appears iff at least one challenge generation has no matching resolve. Throws on corruption —
  *  consumers refuse service (integrity unknown ≠ clean). */
@@ -424,6 +460,36 @@ export declare function challengedEntryIds(controlDir: string): Map<string, {
 }>;
 /** Full event read (host audit / tests). Throws on corruption. */
 export declare function readChallengeEvents(controlDir: string): ChallengeEvent[];
+/** Which fail-closed control-plane ledger a rebuild targets. */
+export type StrictControlPlaneLedger = "lineage" | "challenges";
+/** What one rebuild did — the deployment's record of a taint-bearing account it chose to reset. */
+export interface ControlPlaneRebuildReceipt {
+    ledger: StrictControlPlaneLedger;
+    /** The corrupt file (and its journal, when one existed) moved aside — never deleted. */
+    quarantinedTo: string[];
+    at: number;
+}
+/**
+ * design/180 §10 — rebuild a CORRUPT fail-closed ledger, explicitly.
+ *
+ * The fail-closed family refuses service on corruption precisely because a silent "start fresh" would
+ * LAUNDER taint (a challenged entry re-enters the prompt; a polluted session's contributions become
+ * untraceable). That refusal is permanent by design — which left a deployment whose disk really did
+ * corrupt with no way back other than deleting engine files by hand. This is that way back, and its
+ * whole shape is "never automatic":
+ *  · the caller names the ledger — nothing in the engine calls this on its own;
+ *  · a HEALTHY ledger is REFUSED (`memory.control_plane_not_corrupt`) — a rebuild is only ever the
+ *    answer to a corruption that is already blocking every read, never a way to clear an account;
+ *  · the corrupt bytes are QUARANTINED beside the file, never deleted: what the ledger held is
+ *    exactly the evidence someone will want after a laundering decision;
+ *  · the caller (the engine's host API) announces the rebuild — a reset of this account changes what
+ *    the model may see, so it is not a silent repair.
+ */
+/** Lock-less probe: does this fail-closed ledger currently REFUSE reads? The rebuild's own check runs
+ *  again under the lock (this one is for a caller that must decide something — announce, refuse — before
+ *  taking the lock). `false` for a ledger that reads cleanly, including an absent one (genuinely empty). */
+export declare function isStrictControlPlaneLedgerCorrupt(controlDir: string, ledger: StrictControlPlaneLedger): boolean;
+export declare function rebuildStrictControlPlaneLedger(controlDir: string, ledger: StrictControlPlaneLedger, now: () => number): ControlPlaneRebuildReceipt;
 /** One challenged-history row: how often a retrieved-then-corrected event hit this entry. */
 export interface ChallengedHistoryRow {
     count: number;