@sema-agent/core 5.39.0 → 5.41.0

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

@@ -1,7 +1,8 @@
 export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, renderAnnouncements, type MemoryEngineOptions, type MemoryInjection, type EntryProvenanceAccount, } from "./engine.js";
 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, type TransferEvidence, type CommittedBinding, type CommittedEntrySnapshot, type CommittedScopeSnapshots, type EntryCustodyReport, erasureSelectHash, type EraseMemoryEntriesInput, type ErasureSelect, type ErasedBinding, type MemoryErasureAttestation, } from "./file-backend.js";
+export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH, type ScannedEntryFile, type TransferEvidence, type CommittedBinding, type CommittedEntrySnapshot, type CommittedScopeSnapshots, type EntryCustodyReport, erasureSelectHash, type EraseMemoryEntriesInput, type ErasureSelect, type ErasedBinding, type MemoryErasureAttestation, type MemoryExportSnapshot, } from "./file-backend.js";
+export { computeBundleSectionHashes, computeMemoryBundleHash, memoryBundleInvalid, type MemoryExportBundle, type MemoryImportReport, type MemoryBundleImportPlan, type BundleChallengeRow, type BundleLineageRow, type BundlePollutedSession, } from "./export-bundle.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";

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

@@ -2,6 +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, erasureSelectHash, } from "./file-backend.js";
+export { computeBundleSectionHashes, computeMemoryBundleHash, memoryBundleInvalid, } from "./export-bundle.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";

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

@@ -248,6 +248,16 @@ export interface SidecarLockOptions {
  *  volume, revoked permission) makes mkdir fail forever while the lock dir it would stat never
  *  exists — spun this synchronous loop at full speed and never reached its own cap. */
 export declare function acquireSidecarLock(lockDir: string, opts?: SidecarLockOptions): string;
+/** 证伪式复审 L2-analog: re-verify the owner token at the COMMIT POINT — a stolen-from holder
+ *  aborts instead of writing over the stealer. A FOREIGN token always aborts (positive proof the
+ *  lock is someone else's now). What an ABSENT/UNREADABLE owner file means splits by caller family
+ *  (backlog #255): the fail-closed LEDGER family (`"strict"` — challenges/lineage via
+ *  lockedStrictUpdate) treats unprovable ownership as lost — those sidecars promise their commit
+ *  point is fenced, and "cannot disprove" is not a fence; the fail-open calibration family
+ *  (`"lenient"`, the pre-#255 shape — e.g. the scope registry, whose sidecars self-heal at the next
+ *  locked update) keeps the leniency, because its token writes are best-effort and an absent owner
+ *  file there is the documented pre-token degraded shape, not evidence of a steal. */
+export declare function assertSidecarLockOwnership(lockDir: string, token: string, what: string, mode?: "strict" | "lenient"): void;
 interface AnnouncementsRecord {
     /** How many announcements were dropped by the bounded-queue fold (disclosed at render). */
     folded: number;
@@ -284,6 +294,25 @@ export declare function markSessionPolluted(controlDir: string, sessionId: strin
  *  record stands in. Only ABSENCE is clean, so a control plane that cannot be stat'ed at all reads
  *  clean for every session rather than disabling memory deployment-wide. */
 export declare function readSessionPollution(controlDir: string, sessionId: string): SessionPollutionRecord | undefined;
+/**
+ * design/178 v2-c §3-3 — enumerate EVERY durable pollution marker (the export snapshot's pollution
+ * face; `readSessionPollution` stays the per-session read). Same fail-closed record posture as the
+ * per-session read: a marker file that exists but cannot be read or parsed answers a synthesized
+ * record, never a silent omission (corruption must not launder the state out of an export). An
+ * absent marker directory is the genuine empty state (ENOENT-only); any OTHER enumeration failure
+ * THROWS — a listing that silently dropped markers would export a package that launders pollution.
+ */
+export declare function listSessionPollution(controlDir: string): Record<string, SessionPollutionRecord>;
+/**
+ * design/178 v2-c §5.3 — the STRICT durable pollution import. Deliberately NOT
+ * `markSessionPolluted`: that leg is best-effort-with-disclosure and mints its own `at`, so a
+ * bundle's source record (the governance fact being carried) could neither land verbatim nor prove
+ * durability. This leg writes the SOURCE record verbatim (`wx`); on EEXIST it reads the standing
+ * record back and COMPARES — equal = converged no-op, different = the destination's first-mark-wins
+ * record stands and the divergence is REPORTED (`"divergent"`), never silently absorbed. Any other
+ * write failure THROWS (the import aborts with its latch standing — §1-2⑤).
+ */
+export declare function importSessionPollution(controlDir: string, sessionId: string, record: SessionPollutionRecord): "written" | "already" | "divergent";
 /** The retrieved-account sidecar (control plane): entry id → { count, lastAt }. */
 export declare const USAGE_RETRIEVED_FILE = "usage-retrieved.json";
 /** Bound on tracked ids — over the cap, the entries with the OLDEST `lastAt` are evicted first
@@ -320,10 +349,15 @@ export interface LineageContribution {
     lastRev: string;
     lastAt: number;
 }
-/** One staged (pre-commit) row: an entry this transaction WOULD commit. */
+/** One staged (pre-commit) row: an entry this transaction WOULD commit. `kind: "latch-only"` marks
+ *  a bundle-import SYNTHETIC latch row (design/178 v2-c §1): it withholds the id on the model-visible
+ *  read faces exactly like a real staged row, but it is NOT a contribution — the erasure lane's
+ *  capture-and-clear strikes it without crediting its txn's sessionId, and the host adjudication
+ *  refuses to touch its transaction (the import protocol's receipt-gated release is the only exit). */
 export interface LineagePendingRow {
     entryId: string;
     rev: string;
+    kind?: "latch-only";
 }
 /** One staged transaction: rows land BEFORE `applyPatches`; the commit credential lands after it
  *  succeeds; promotion consumes both. A pending txn without a credential is the crash window —
@@ -338,6 +372,12 @@ export interface LineagePendingTxn {
         appliedIds: string[];
         at: number;
     };
+    /** design/178 v2-c §1 — present ⇔ this txn is a bundle-import SYNTHETIC LATCH: it never promotes
+     *  (no credential is ever written), the generic adjudication REFUSES both arms on it, and the only
+     *  release channel is {@link releaseImportLatch} (durable completion-receipt precondition). An
+     *  older binary reads it as an ordinary uncredentialed pending txn and reports it undecidable —
+     *  the accepted mixed-version posture (the drain precondition of the ledger family applies). */
+    kind?: "latch-only";
 }
 /** Stage this transaction's would-commit rows BEFORE `applyPatches` (write-ahead). Throws on any
  *  write/lock/corruption failure — the caller refuses the whole harvest (fail-closed). */
@@ -373,8 +413,39 @@ export declare function reconcileLineage(controlDir: string, now: () => number):
         txnId: string;
         sessionId: string;
         entryIds: string[];
+        kind?: "latch-only";
     }>;
 };
+/** design/178 v2-c §1 — the import COMPLETION-RECEIPT directory (control plane): one `wx`-minted
+ *  JSON per bundle hash, written only after the import's governance legs all landed. Its presence
+ *  is {@link releaseImportLatch}'s hard precondition and the idempotent re-import's short-circuit
+ *  credential. */
+export declare const IMPORT_RECEIPTS_DIR = "import-receipts";
+/** The lineage txn id of a bundle import's synthetic latch (ONE latch per bundle — a re-import of
+ *  the same bundle re-stages the same txn id, which is what makes the latch idempotent). */
+export declare function importLatchTxnId(bundleHash: string): string;
+/**
+ * design/178 v2-c §1-1 — stage the bundle import's SYNTHETIC LATCH: one pending lineage txn
+ * (txnId = {@link importLatchTxnId}) whose rows name every bundle entry id, every row and the txn
+ * itself carrying the structural `kind: "latch-only"` seat. From this write until
+ * {@link releaseImportLatch}, those ids are withheld on every model-visible read face (the same
+ * dirty-latch consumption real staged rows get) — a crash anywhere inside the import leaves the
+ * withhold standing (durable pending row), and re-staging the same bundle is an idempotent
+ * overwrite with identical content. Never credentialed, never promoted.
+ */
+export declare function stageImportLatch(controlDir: string, bundleHash: string, rows: ReadonlyArray<{
+    entryId: string;
+    rev: string;
+}>, now: () => number): string;
+/**
+ * design/178 v2-c §1-2⑥ — the ONE latch release channel. Hard precondition: the durable completion
+ * receipt for the bundle is IN PLACE (`import-receipts/<bundleHash>.json`, minted after the
+ * governance legs all landed) — absent receipt ⇒ loud refusal, the latch stands, and convergence is
+ * re-running the same bundle import. Receipt-presence is ENOENT-only-absent (a probe failure never
+ * reads as "no receipt" — fail-closed). Idempotent: an already-released (absent) txn is a no-op;
+ * a NON-latch txn under the id is refused (this is never a generic discard).
+ */
+export declare function releaseImportLatch(controlDir: string, txnId: string): void;
 /** The DIRTY-LATCH set: every entry id named by ANY pending row (credentialed or not). While an id
  *  is latched, its model-visible read faces (index mechanical rows / memory_search / memory_get)
  *  refuse — "the account is not settled, the content does not go on the table". Throws on a
@@ -429,6 +500,33 @@ export declare function clearLineageForEntries(controlDir: string, entryIds: rea
  * carries the chain's pre-captured set (honest downgrade, never a fabricated rebuild).
  */
 export declare function captureAndClearLineageForEntries(controlDir: string, entryIds: readonly string[]): Map<string, string[]>;
+/** One (entryId, sessionId) pair whose imported value LOST to the destination's standing row —
+ *  design/178 v2-c §5.1's disclosure seat (kept is always "destination": the in-account fact is
+ *  never overwritten by an equal-time divergent import, only reported). */
+export interface LineageImportDivergence {
+    entryId: string;
+    sessionId: string;
+    kept: "destination";
+}
+/**
+ * design/178 v2-c §5.1 — the lineage FIDELITY importer: write bundle lineage rows into the
+ * committed set VERBATIM (`lastRev`/`lastAt` carried byte-for-byte — the promote leg mints its own
+ * `now` and is therefore unusable for carriage). Deterministic same-key merge, idempotent under
+ * re-import of the same bundle:
+ *  - destination has no (entryId, sessionId) row ⇒ the source row lands verbatim;
+ *  - both present, source `lastAt` is GREATER ⇒ source wins ("last contribution" is a time-axis
+ *    fact); destination greater ⇒ destination stands (no divergence — the merge is deterministic);
+ *  - equal `lastAt`, equal `lastRev` ⇒ no-op; equal `lastAt`, DIFFERENT `lastRev` ⇒ the
+ *    destination row stands and the pair is reported (first-mark-wins side: an in-account fact is
+ *    never rewritten by an外来 package; the disagreement must not be silent).
+ * Throws on a corrupt ledger (fail-closed family).
+ */
+export declare function importLineageCommitted(controlDir: string, rows: ReadonlyArray<{
+    entryId: string;
+    sessionId: string;
+    lastRev: string;
+    lastAt: number;
+}>): LineageImportDivergence[];
 /** Full-ledger read (tests / host observability). Throws on corruption. */
 export declare function readLineageRecord(controlDir: string): {
     committed: Record<string, Record<string, LineageContribution>>;

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

@@ -598,12 +598,15 @@ function lockedJournaledUpdate(controlDir, fileName, mutate) {
         releaseSidecarLock(lock, token);
     }
 }
-function assertSidecarLockOwnership(lockDir, token, what) {
+export function assertSidecarLockOwnership(lockDir, token, what, mode = "lenient") {
     let held;
     try {
         held = readFileSync(join(lockDir, "owner"), "utf8");
     }
-    catch {
+    catch (err) {
+        if (mode === "strict" && err.code !== undefined) {
+            throw new ControlPlaneCorruptError(`${what}: sidecar lock ownership UNPROVABLE at commit (owner file ${err.code === "ENOENT" ? "absent" : `unreadable: ${err.code}`}) — a fail-closed ledger must not commit on a fence it cannot prove; update aborted`, { cause: err });
+        }
         return;
     }
     if (held !== token) {
@@ -766,6 +769,48 @@ export function readSessionPollution(controlDir, sessionId) {
     }
     return { at: 0, reason: "pollution marker present but unreadable (kept fail-closed)" };
 }
+export function listSessionPollution(controlDir) {
+    const dir = join(controlDir, SESSION_POLLUTION_DIR);
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return {};
+        throw new ControlPlaneCorruptError(`session pollution markers could not be enumerated (${err.code ?? "io error"}) at ${dir} — an enumeration failure is not an empty set (fail-closed)`, { cause: err });
+    }
+    const out = Object.create(null);
+    for (const name of names.sort()) {
+        if (!name.endsWith(".json"))
+            continue;
+        let sessionId;
+        try {
+            sessionId = decodeURIComponent(name.slice(0, -".json".length));
+        }
+        catch {
+            continue;
+        }
+        const rec = readSessionPollution(controlDir, sessionId);
+        if (rec !== undefined)
+            out[sessionId] = rec;
+    }
+    return out;
+}
+export function importSessionPollution(controlDir, sessionId, record) {
+    const path = pollutionPath(controlDir, sessionId);
+    ensureDirExists(dirname(path));
+    try {
+        writeFileSync(path, `${JSON.stringify({ at: record.at, reason: record.reason }, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+        return "written";
+    }
+    catch (err) {
+        if (!(err instanceof Error && "code" in err && err.code === "EEXIST"))
+            throw err;
+    }
+    const standing = readSessionPollution(controlDir, sessionId);
+    return standing !== undefined && standing.at === record.at && standing.reason === record.reason ? "already" : "divergent";
+}
 export const USAGE_RETRIEVED_FILE = "usage-retrieved.json";
 export const USAGE_RETRIEVED_MAX_IDS = 4096;
 function coerceRetrievedAccount(raw) {
@@ -855,7 +900,7 @@ function lockedStrictUpdate(controlDir, fileName, what, coerce, fn) {
         const { next, result } = fn(current);
         if (next !== undefined) {
             const data = `${JSON.stringify(next, null, 2)}\n`;
-            assertSidecarLockOwnership(lock, token, what);
+            assertSidecarLockOwnership(lock, token, what, "strict");
             atomicWriteFileSync(journal, data);
             atomicWriteFileSync(file, data);
             rmSync(journal, { force: true });
@@ -890,7 +935,10 @@ function readStrictSidecar(controlDir, fileName, what) {
     try {
         journalRaw = readFileSync(journal, "utf8");
     }
-    catch {
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw new ControlPlaneCorruptError(`control-plane journal unreadable ((${err.code ?? "io error"})) — a committed next state may exist that cannot be proven; repair the read fault rather than serving the pre-transaction state: ${journal}`, { cause: err });
+        }
         journalRaw = undefined;
     }
     if (journalRaw !== undefined) {
@@ -932,10 +980,14 @@ function coerceLineage(raw) {
         if (!txn || typeof txn !== "object" || typeof txn.sessionId !== "string" || typeof txn.at !== "number" || !Array.isArray(txn.rows)) {
             throw badShape(`pending[${JSON.stringify(txnId)}]`);
         }
+        if (txn.kind !== undefined && txn.kind !== "latch-only")
+            throw badShape(`pending[${JSON.stringify(txnId)}] kind`);
         for (const row of txn.rows) {
             const p = row;
             if (!p || typeof p !== "object" || typeof p.entryId !== "string" || typeof p.rev !== "string")
                 throw badShape(`pending[${JSON.stringify(txnId)}] row`);
+            if (p.kind !== undefined && p.kind !== "latch-only")
+                throw badShape(`pending[${JSON.stringify(txnId)}] row kind`);
         }
         if (txn.credential !== undefined) {
             const c = txn.credential;
@@ -1006,6 +1058,9 @@ export function adjudicateLineagePending(controlDir, txnId, action, now) {
         const txn = rec.pending[txnId];
         if (txn === undefined)
             return { result: [] };
+        if (isLatchOnlyTxn(txn)) {
+            throw new ControlPlaneCorruptError(`memory lineage ledger: pending transaction ${txnId} is a bundle-import latch — it cannot be ${action === "promote" ? "promoted (its rows are not contributions)" : "discarded (its withhold guards not-yet-governed imported entries)"}; re-run the same bundle import to converge it (releaseImportLatch is receipt-gated)`);
+        }
         if (action === "discard") {
             delete rec.pending[txnId];
             return { next: rec, result: [] };
@@ -1032,7 +1087,7 @@ export function reconcileLineage(controlDir, now) {
         let changed = false;
         for (const [txnId, txn] of Object.entries(rec.pending)) {
             if (txn.credential === undefined) {
-                undecidable.push({ txnId, sessionId: txn.sessionId, entryIds: txn.rows.map((r) => r.entryId) });
+                undecidable.push({ txnId, sessionId: txn.sessionId, entryIds: txn.rows.map((r) => r.entryId), ...(isLatchOnlyTxn(txn) ? { kind: "latch-only" } : {}) });
                 continue;
             }
             const applied = new Set(txn.credential.appliedIds);
@@ -1050,6 +1105,66 @@ export function reconcileLineage(controlDir, now) {
         return { ...(changed ? { next: rec } : {}), result: { promoted, undecidable } };
     });
 }
+function isLatchOnlyTxn(txn) {
+    if (txn.kind === "latch-only")
+        return true;
+    return txn.rows.some((row) => row.kind === "latch-only");
+}
+export const IMPORT_RECEIPTS_DIR = "import-receipts";
+export function importLatchTxnId(bundleHash) {
+    return `import:${bundleHash}`;
+}
+function importReceiptPath(controlDir, bundleHash) {
+    return join(controlDir, IMPORT_RECEIPTS_DIR, `${bundleHash}.json`);
+}
+export function stageImportLatch(controlDir, bundleHash, rows, now) {
+    const txnId = importLatchTxnId(bundleHash);
+    lockedStrictUpdate(controlDir, LINEAGE_FILE, "memory lineage ledger", coerceLineage, (rec) => {
+        const existing = rec.pending[txnId];
+        if (existing !== undefined && !isLatchOnlyTxn(existing)) {
+            throw new ControlPlaneCorruptError(`memory lineage ledger: pending transaction ${txnId} exists and is NOT an import latch — refusing to overwrite a real staged transaction`);
+        }
+        rec.pending[txnId] = {
+            sessionId: txnId,
+            at: now(),
+            kind: "latch-only",
+            rows: rows.map((r) => ({ entryId: r.entryId, rev: r.rev, kind: "latch-only" })),
+        };
+        return { next: rec, result: undefined };
+    });
+    return txnId;
+}
+export function releaseImportLatch(controlDir, txnId) {
+    const prefix = "import:";
+    if (!txnId.startsWith(prefix) || !/^[0-9a-f]{64}$/.test(txnId.slice(prefix.length))) {
+        throw new ControlPlaneCorruptError(`releaseImportLatch: ${JSON.stringify(txnId)} is not an import-latch transaction id (import:<64-hex bundleHash>)`);
+    }
+    const receipt = importReceiptPath(controlDir, txnId.slice(prefix.length));
+    let receiptPresent;
+    try {
+        readFileSync(receipt);
+        receiptPresent = true;
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw new ControlPlaneCorruptError(`releaseImportLatch: the completion receipt at ${receipt} could not be read (${err.code ?? "io error"}) — a probe failure is not absence (fail-closed), and absence would refuse the release`, { cause: err });
+        }
+        receiptPresent = false;
+    }
+    if (!receiptPresent) {
+        throw new ControlPlaneCorruptError(`releaseImportLatch: no completion receipt at ${receipt} — the import's governance legs are not proven landed, the latch stays; re-run the same bundle import to converge`);
+    }
+    lockedStrictUpdate(controlDir, LINEAGE_FILE, "memory lineage ledger", coerceLineage, (rec) => {
+        const txn = rec.pending[txnId];
+        if (txn === undefined)
+            return { result: undefined };
+        if (!isLatchOnlyTxn(txn)) {
+            throw new ControlPlaneCorruptError(`releaseImportLatch: pending transaction ${txnId} is NOT an import latch — refusing (this channel never discards a real staged transaction)`);
+        }
+        delete rec.pending[txnId];
+        return { next: rec, result: undefined };
+    });
+}
 export function lineageLatchedIds(controlDir) {
     const rec = coerceLineage(readStrictSidecar(controlDir, LINEAGE_FILE, "memory lineage ledger"));
     const out = new Set();
@@ -1134,6 +1249,27 @@ export function captureAndClearLineageForEntries(controlDir, entryIds) {
         return { ...(changed ? { next: rec } : {}), result };
     });
 }
+export function importLineageCommitted(controlDir, rows) {
+    if (rows.length === 0)
+        return [];
+    return lockedStrictUpdate(controlDir, LINEAGE_FILE, "memory lineage ledger", coerceLineage, (rec) => {
+        const divergence = [];
+        let changed = false;
+        for (const row of rows) {
+            const sessions = (rec.committed[row.entryId] ??= Object.create(null));
+            const standing = Object.prototype.hasOwnProperty.call(sessions, row.sessionId) ? sessions[row.sessionId] : undefined;
+            if (standing === undefined || row.lastAt > standing.lastAt) {
+                sessions[row.sessionId] = { lastRev: row.lastRev, lastAt: row.lastAt };
+                changed = true;
+                continue;
+            }
+            if (row.lastAt === standing.lastAt && row.lastRev !== standing.lastRev) {
+                divergence.push({ entryId: row.entryId, sessionId: row.sessionId, kept: "destination" });
+            }
+        }
+        return { ...(changed ? { next: rec } : {}), result: divergence };
+    });
+}
 export function readLineageRecord(controlDir) {
     const rec = coerceLineage(readStrictSidecar(controlDir, LINEAGE_FILE, "memory lineage ledger"));
     return { committed: rec.committed, pending: rec.pending };
@@ -1291,7 +1427,7 @@ export function rebuildStrictControlPlaneLedger(controlDir, ledger, now) {
         }
         const at = now();
         const quarantinedTo = [];
-        assertSidecarLockOwnership(lock, token, what);
+        assertSidecarLockOwnership(lock, token, what, "strict");
         for (const path of [file, journal]) {
             if (!existsSync(path))
                 continue;
@@ -1309,7 +1445,7 @@ export function rebuildStrictControlPlaneLedger(controlDir, ledger, now) {
             }
             quarantinedTo.push(dest);
         }
-        assertSidecarLockOwnership(lock, token, what);
+        assertSidecarLockOwnership(lock, token, what, "strict");
         atomicWriteFileSync(file, `${JSON.stringify(empty, null, 2)}\n`);
         rmSync(journal, { force: true });
         return { ledger, quarantinedTo, at };

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

@@ -22,7 +22,7 @@ export interface MemoryBackendContractHooks {
      * assembly answers it as capability-absent.
      */
     onOptionalMember?: (report: {
-        member: "committedSnapshotOf" | "committedSnapshotsOfScopes" | "custodyOf" | "eraseWithEvidence";
+        member: "committedSnapshotOf" | "committedSnapshotsOfScopes" | "custodyOf" | "eraseWithEvidence" | "exportSnapshotOf" | "governanceExport" | "custodyImport" | "importBundleCommit";
         status: "verified" | "absent";
     }) => void;
 }

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

@@ -384,6 +384,58 @@ export async function memoryBackendContract(hooks) {
         await assert.rejects(async () => erase.call(b, { requestId: "req-contract-1", select: { ids: ["id-other-7777"] } }), (err) => err.code === "memory.erasure_selector_mismatch", "a reused requestId with a different selector refuses loudly");
         hooks.onOptionalMember?.({ member: "eraseWithEvidence", status: "verified" });
     });
+    defer("design/178 v2-c optional export/import faces: export composite / governance slice / custody carriage (absent ⇒ reported)", async () => {
+        const b = await hooks.make();
+        const seats = [
+            ["exportSnapshotOf", b.exportSnapshotOf],
+            ["governanceExport", b.governanceExport],
+            ["custodyImport", b.custodyImport],
+            ["importBundleCommit", b.importBundleCommit],
+        ];
+        for (const [member, seat] of seats) {
+            assert.ok(seat === undefined || typeof seat === "function", `${member} must be undefined (absent) or a function — a non-function occupant is a defect, not absence`);
+        }
+        const e = entry("id-export-0001", "s1", "exported", "exported body", { name: "Exported" });
+        await b.applyPatches([{ op: "add", id: e.id, entry: e }]);
+        const exportSnapshotOf = typeof seats[0]?.[1] === "function" ? seats[0][1] : undefined;
+        if (exportSnapshotOf === undefined) {
+            hooks.onOptionalMember?.({ member: "exportSnapshotOf", status: "absent" });
+        }
+        else {
+            const snap = await exportSnapshotOf.call(b, ["s1"]);
+            assert.ok(typeof snap.storeId === "string" && snap.storeId.length > 0, "the export snapshot names the store identity");
+            assert.strictEqual(typeof snap.fullStore, "boolean");
+            assert.deepStrictEqual(snap.entries.map((r) => r.id), [e.id], "the composite answers the committed entries of the requested scopes");
+            assert.strictEqual(snap.entries[0]?.rev, e.rev, "entries carry the committed rev");
+            assert.ok(Array.isArray(snap.custody) && Array.isArray(snap.unbound) && Array.isArray(snap.pendingLatch));
+            hooks.onOptionalMember?.({ member: "exportSnapshotOf", status: "verified" });
+        }
+        const governanceExport = typeof seats[1]?.[1] === "function" ? seats[1][1] : undefined;
+        if (governanceExport === undefined) {
+            hooks.onOptionalMember?.({ member: "governanceExport", status: "absent" });
+        }
+        else {
+            const slice = await governanceExport.call(b, ["s1"]);
+            assert.strictEqual(slice.complete, true, "a quiet store's governance slice answers complete");
+            assert.ok(Array.isArray(slice.custody) && Array.isArray(slice.unbound));
+            hooks.onOptionalMember?.({ member: "governanceExport", status: "verified" });
+        }
+        const custodyImport = typeof seats[2]?.[1] === "function" ? seats[2][1] : undefined;
+        if (custodyImport === undefined) {
+            hooks.onOptionalMember?.({ member: "custodyImport", status: "absent" });
+        }
+        else {
+            const opts = { bundleHash: "c".repeat(64), sourceStoreId: "contract-src-store" };
+            const outcome = await custodyImport.call(b, [{ ev: "kit-del-1", channel: "delete", id: "id-ghost-kit-1", rev: "deadbeefdeadbeef", at: 1 }], opts);
+            assert.strictEqual(outcome.appended, 1, "a well-formed delete row for an absent id is carried (anti-resurrection evidence needs no living entry)");
+            assert.deepStrictEqual(outcome.withheld, []);
+            const unknown = await custodyImport.call(b, [{ ev: "kit-unk-1", channel: "kit-unknown-channel", payload: 1, at: 1 }], opts);
+            assert.strictEqual(unknown.appended, 0, "an unknown channel is never appended verbatim");
+            assert.deepStrictEqual(unknown.withheld, [{ srcEv: "kit-unk-1", channel: "kit-unknown-channel" }], "an unknown channel is withheld AND reported — never a whole-package refusal");
+            hooks.onOptionalMember?.({ member: "custodyImport", status: "verified" });
+        }
+        hooks.onOptionalMember?.({ member: "importBundleCommit", status: typeof seats[3]?.[1] === "function" ? "verified" : "absent" });
+    });
     if (!hooks.makeSibling) {
         const reason = hooks.skipCrossInstanceCas?.trim();
         if (reason) {

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

@@ -163,7 +163,14 @@ export function createMemoryEngineTools(opts) {
                     throw err;
                 return refusedSearch("error", GENERIC_FAILURE, "failed");
             }
-            const live = top.filter((h) => bodyById.has(h.id));
+            let terminalExclusions;
+            try {
+                terminalExclusions = planes.map((plane) => plane.challengeExclusions?.());
+            }
+            catch {
+                return refusedSearch("challenge_ledger_unavailable", "Memory search is unavailable: the challenge ledger for a mounted memory plane cannot be read (fail-closed). Report this to the operator.", "failed");
+            }
+            const live = top.filter((h) => bodyById.has(h.id) && terminalExclusions[h.planeIndex]?.has(h.id) !== true);
             if (live.length === 0) {
                 const details = { outcome: "ok", hits: [] };
                 return { content: `No memory entries matched ${JSON.stringify(inlineUntrusted(query, 120))}. If the user expected you to know this, say that you checked memory and found nothing.`, details };

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

@@ -357,14 +357,26 @@ export async function prepareCcImport(opts) {
             continue;
         }
         layers.push({ path: layer.path, layer: layer.layer, found: true });
-        let container;
+        let settingsRoot;
         try {
-            container = JSON.parse(raw)?.permissions;
+            settingsRoot = JSON.parse(raw);
         }
         catch (err) {
             skipped.push({ rule: layer.path, reason: `settings file is not valid JSON (${errText(err)})` });
             continue;
         }
+        let container;
+        if (settingsRoot === null)
+            container = undefined;
+        else if (typeof settingsRoot === "object" && !Array.isArray(settingsRoot))
+            container = settingsRoot.permissions;
+        else {
+            skipped.push({
+                rule: layer.path,
+                reason: `settings file is not a JSON object — no bucket in this layer could be read, so it is reported as unread rather than as empty (it stays in the settings file either way)`,
+            });
+            continue;
+        }
         let permissions;
         if (container === undefined || container === null)
             permissions = undefined;

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

@@ -87,6 +87,26 @@ export function prepareConfigDoors(input) {
     const { deps, sessions, resume, internals } = input;
     let spec = input.spec;
     assertRestoreGatedToolsValue(spec.restoreGatedTools);
+    const assertToolNameListValue = (value, seat) => {
+        if (value === undefined)
+            return;
+        if (!Array.isArray(value)) {
+            const e = new Error(`TaskSpec.${seat} must be an array of tool names or absent (got ${value === null ? "null" : typeof value}) — a garbage list must refuse loudly, never be read as "no ${seat}".`);
+            e.code = "config.tool_face_control";
+            throw e;
+        }
+        const entries = value;
+        for (const entry of entries) {
+            if (typeof entry !== "string") {
+                const e = new Error(`TaskSpec.${seat} entries must be strings (got ${entry === null ? "null" : typeof entry}).`);
+                e.code = "config.tool_face_control";
+                throw e;
+            }
+        }
+    };
+    assertToolNameListValue(spec.excludeTools, "excludeTools");
+    assertToolNameListValue(spec.deferTools, "deferTools");
+    assertToolNameListValue(spec.alwaysLoadTools, "alwaysLoadTools");
     const toolFaceSnapshot = {
         exclude: spec.excludeTools ? Object.freeze([...spec.excludeTools]) : undefined,
         defer: spec.deferTools ? Object.freeze([...spec.deferTools]) : undefined,

package/dist/core/runner/prepare-task.js

@@ -327,6 +327,13 @@ function orgRevisionEvidenceOf(resolution, onDefect) {
 function persistedRuleHitOf(admitting) {
     return admitting === undefined ? undefined : { rule: admitting.rule, dots: admitting.adds.map((a) => ({ actor: a.dot.actor, counter: a.dot.counter })) };
 }
+function cwdConflictsRestoreError(requestedCwd) {
+    const e = new Error(`RunInternals.requestedCwd ("${requestedCwd}") cannot be combined with a checkpoint workspace restore — ` +
+        `the restored workspace's own mount path is authoritative for the task root, so a requested cwd on this leg ` +
+        `would be ignored (or worse, probed against an unrestored environment). Drop requestedCwd on resume legs.`);
+    e.code = "config.cwd_conflicts_restore";
+    return e;
+}
 export async function prepareTask(spec, deps, sessions, resume, internals, runnerSelf) {
     const doors = prepareConfigDoors({ spec, deps, sessions, resume, internals });
     spec = doors.spec;
@@ -421,6 +428,10 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         e.code = "config.cwd_unsupported";
         throw e;
     }
+    if (internals?.requestedCwd !== undefined && resume?.workspaceHandle !== undefined) {
+        await settleTeardownLeg(() => forgetOnThrow(), "forgetOnThrow (cwd-conflicts-restore leg)", (err) => deps.onError?.(err, { phase: "config", sessionId }));
+        throw cwdConflictsRestoreError(internals.requestedCwd);
+    }
     try {
         ownedEnv = deps.executionEnvFactory
             ? await deps.executionEnvFactory({
@@ -1248,6 +1259,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 if (c.ok)
                     additionalRootsCanonical.push(c.value);
             }
+            for (const a of [additionalRootsCanonical, additionalReadRootsCanonical])
+                a.splice(0, a.length, ...new Set(a));
             const readFileState = new Map((resume?.seed.readFileState ?? []).map(([k, v]) => [rebaseRestoredPath(k), v]));
             readFileStateForCheckpoint = readFileState;
             seedContextFiles = async (files) => {

package/dist/core/runner/runtask.js

@@ -1,6 +1,6 @@
 import { persistedReadDenyEntryProblem } from "../../tools/fs/read-deny.js";
 import { createSafeNotifier, observeThenableRejection } from "../safe-notify.js";
-import { deliverDelegationLifecycle } from "../types.js";
+import { deliverDelegationLifecycle, deliverEngineNotice } from "../types.js";
 import { AgentHarness, DEFAULT_COMPACTION_SETTINGS, uuidv7 } from "../../internal/harness.js";
 import { snapshotActorAssertion } from "../../internal/llm.js";
 import { CheckpointError, BINDING_CHECKPOINT_VERSION, checkpointVersionOf, F012_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, FACE_CHECKPOINT_VERSION, remainingBudgetMicroUsd, readPendingSteerQueue, remainingTokens, LEGACY_PENDING_STEER_INPUT_ID, MAX_STEER_INPUT_ID_CHARS, validatePendingSteer, winnerFromOutcome, } from "../checkpoint-store.js";
@@ -2068,6 +2068,14 @@ export class Runner {
             for (const p of payloads)
                 this.pendingSessionNotifications.pend(notificationSessionId, p);
         };
+        prepared.harness.onUndrainedUserInputs = (counts) => {
+            deliverEngineNotice(this.deps.onNotice, {
+                code: "task.user_steer_undrained",
+                message: `${counts.steer + counts.followUp} user input(s) accepted as "queued" were never consumed — the run ended first ` +
+                    `(${counts.steer} steer, ${counts.followUp} follow-up). They are NOT redelivered; re-send against a live run if still wanted.`,
+                detail: { steer: counts.steer, followUp: counts.followUp, ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}) },
+            });
+        };
         prepared.harness.onEngineNoteConsumed = (p) => {
             const peer = p?.peer;
             if (peer !== undefined && Array.isArray(peer.hopChain))
@@ -4126,6 +4134,11 @@ export class Runner {
         if (cp.state.workspaceHandle !== undefined && this.deps.executionEnvFactory === undefined) {
             throw new CheckpointError("checkpoint.unsupported_version", "checkpoint has a remote workspaceHandle but no RunnerDeps.executionEnvFactory is wired to rebuild the env", { reason: "env_factory_missing" });
         }
+        if (cp.state.workspaceHandle !== undefined && internals?.requestedCwd !== undefined) {
+            throw new CheckpointError("checkpoint.cwd_conflicts_restore", `internals.requestedCwd ("${internals.requestedCwd}") cannot be combined with a checkpoint workspace restore — ` +
+                "the restored workspace's own mount path is authoritative for the task root. Drop requestedCwd on resume legs " +
+                "(the checkpoint stays pending and is resumable without it).");
+        }
         if (cp.state.inheritedGate?.requiresParentConstraint === true) {
             const supplied = internals?.inheritedGate?.parentConstraints?.length ?? 0;
             if (supplied === 0) {

package/dist/core/runner/synthetic-tools.js

@@ -196,7 +196,9 @@ export function createSkillTool(skills, scope) {
             const name = String(a.skill ?? "");
             const skill = byName.get(name);
             if (!skill) {
-                throw new Error(`Unknown skill "${name}". Available skills: ${names}.`);
+                throw new Error(`Unknown skill "${name}". Available skills: ${names}. ` +
+                    `(Only skills registered with this deployment are loadable — other products' skills directories are not read. ` +
+                    `If the user wants one of those here, read its source file and recreate its content for this deployment instead.)`);
             }
             if (scope && skill.manifest) {
                 scope.push({ kind: "manifest", manifest: skill.manifest });

package/dist/core/runner/tool-disclosure.js

@@ -45,7 +45,8 @@ export function classifyDeferred(opts) {
         if (!pinned.has(name))
             deferred.add(name);
     if (opts.deferMode === "auto") {
-        const candidates = opts.fullTools.filter((t) => !deferred.has(t.name) && !pinned.has(t.name));
+        const callerNames = new Set(opts.specs.map((s) => s.name));
+        const candidates = opts.fullTools.filter((t) => !deferred.has(t.name) && !pinned.has(t.name) && callerNames.has(t.name));
         const inlineFace = opts.fullTools.filter((t) => !deferred.has(t.name));
         const total = inlineFace.reduce((n, t) => n + inlinedChars(t), 0);
         const window = (opts.model.contextTokens ?? opts.model.contextWindow ?? 0) * CHARS_PER_TOKEN;