@sema-ai/core 1.275.1

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

@@ -0,0 +1,643 @@
+// design/138 §2.7 (r2.1) — memory-directory layout: the memory dir root is PURE CONFIG (an in-repo
+// git-tracked dir for a project scope, or the repo-keyed home mount below for user/personal scopes —
+// the engine asserts NEITHER), plus the scope→dir mapping shared by the engine (projection) and the
+// FileBackend (storage), so the two can never disagree about where an entry's file lives (the
+// zero-copy invariant depends on this single source). TODO(S1b): per-scope PHYSICAL roots in one
+// session (project in-repo + user out-of-repo simultaneously) — this module currently maps all of a
+// session's scopes under ONE root.
+//
+// 双轨评审 B3 (架构): the ENGINE CONTROL PLANE. All engine metadata (the committed-rev ledger, the
+// scope registry, consolidation cursors, the committed shadow, quarantine, the transaction journal)
+// lives in a directory OUTSIDE the model-writable memory dir — under the memory-engine CONFIG ROOT
+// (`<configRoot>/<key>/.engine/`), never inside the repo and never inside the memory dir, even when
+// the memory dir itself is configured in-repo (§2.7). The model's file channel therefore can NEVER
+// reach CAS/scope metadata; sidecar corruption is FAIL-CLOSED ({@link ControlPlaneCorruptError}) —
+// harvest refuses and reports instead of degrading to an empty ledger / re-claimable root.
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+/** The root-claim record: which scope's entries live DIRECTLY in the memory dir root (CC parity —
+ *  `memory/MEMORY.md` + flat topic files). Claimed by the FIRST writeScope ever used for this repo's
+ *  memory dir and durable thereafter; every other scope gets a `memory/<scope-label>/` subdir.
+ *  B3: lives in the CONTROL PLANE (`scopes.json`), never in the model-writable memory dir. */
+const SCOPES_FILE = "scopes.json";
+/** Cursor sidecar for the design/84 Seam B pair on the FileBackend (`{ [scope]: cursor }`). B3: control plane. */
+export const CURSORS_FILE = "cursors.json";
+/** B3 fail-closed: a control-plane sidecar exists but cannot be trusted (unparseable / wrong shape).
+ *  Read paths propagate it (materialize fails ⇒ the runner falls open to a memory-less session with
+ *  onError); harvest converts it into a refused report (incident `sidecar_corrupt`). It is NEVER
+ *  silently degraded to an empty ledger / unclaimed root — that would let a corrupted (or truncated)
+ *  sidecar erase CAS baselines and re-open the root claim. */
+export class ControlPlaneCorruptError extends Error {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "ControlPlaneCorruptError";
+    }
+}
+/**
+ * CC-style repo key: the absolute repo root path, every non-alphanumeric rune folded to `-` (the same
+ * slug family CC uses for its per-project dirs). Deterministic + filesystem-safe; collisions across
+ * repos require pathological sibling names and only merge their memory dirs (never corrupt them).
+ */
+export function deriveRepoKey(repoRoot) {
+    return resolve(repoRoot).normalize("NFC").replace(/[^A-Za-z0-9]/g, "-");
+}
+/**
+ * `<configRoot>/<repoKey>/memory` — the repo-level stable mount (§2.7: taskRoot 外, worktree-shared).
+ *
+ * Worktree note (验收 L5, documented behavior): the KEY must be the BASE repo root. The runner passes
+ * `deps.rootPath ?? taskRootPath` — when `rootPath` is configured, every derived worktree of that repo
+ * shares ONE memory dir (a worktree moves the task cwd, never the memory mount); when `rootPath` is
+ * NOT configured the taskRootPath fallback keys memory to the task's own checkout path, so an
+ * isolated-worktree task without `rootPath` gets a worktree-private memory dir. That fallback is the
+ * accepted degraded behavior (no silent cross-repo mixing; configure `rootPath` for worktree sharing).
+ */
+export function deriveRepoMemoryDir(configRoot, repoRoot) {
+    return join(configRoot, deriveRepoKey(repoRoot), "memory");
+}
+// ---------------------------------------------------------------------------------------------
+// design/142 §1.5 — marker-first identity keying + the path→projectId hint cache
+// ---------------------------------------------------------------------------------------------
+/** design/142 §1.5 — the IDENTITY-keyed mount (v2 scope contract + a resolved project marker):
+ *  `<configRoot>/proj-<projectId>/memory`. Unlike the path-derived {@link deriveRepoMemoryDir},
+ *  this key survives rename/move/re-clone/container remounts — identity lives in the repo's marker,
+ *  the mount stops referencing the path entirely. */
+export function deriveProjectMemoryDir(configRoot, projectId) {
+    return join(configRoot, `proj-${projectId.toLowerCase()}`, "memory");
+}
+/** Control-plane sibling of {@link deriveProjectMemoryDir} (B3: always on the config-root side). */
+export function deriveProjectControlDir(configRoot, projectId) {
+    return join(configRoot, `proj-${projectId.toLowerCase()}`, ".engine");
+}
+/** design/142 §1.5 — the path→projectId HINT CACHE (`<configRoot>/project-id-hints.json`). NOT an
+ *  identity source (the marker is the single truth source); purely the recovery breadcrumb for a
+ *  deleted/lost marker: materialize can tell "this path used to carry marker X" and prompt a
+ *  restore instead of silently minting a fresh identity. Best-effort on both faces (a corrupt hint
+ *  file degrades to "no hints", never blocks a session). */
+export const PROJECT_ID_HINTS_FILE = "project-id-hints.json";
+export function recordProjectIdHint(configRoot, repoRoot, projectId) {
+    try {
+        const path = join(configRoot, PROJECT_ID_HINTS_FILE);
+        let hints = {};
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf8"));
+            if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed))
+                hints = parsed;
+        }
+        catch {
+            /* absent/corrupt ⇒ start fresh (hints are breadcrumbs, not a ledger) */
+        }
+        const key = resolve(repoRoot);
+        if (hints[key] === projectId.toLowerCase())
+            return;
+        hints[key] = projectId.toLowerCase();
+        mkdirSync(configRoot, { recursive: true });
+        atomicWriteFileSync(path, `${JSON.stringify(hints, null, 2)}\n`);
+    }
+    catch {
+        /* best-effort */
+    }
+}
+export function lookupProjectIdHint(configRoot, repoRoot) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(configRoot, PROJECT_ID_HINTS_FILE), "utf8"));
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+            return undefined;
+        const v = parsed[resolve(repoRoot)];
+        return typeof v === "string" ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** B3 — `<configRoot>/<key>/.engine`: the engine CONTROL PLANE for the memory dir/repo identified by
+ *  `key` (a repo root for the standard flow, or the memory dir itself for a directory-pinned backend).
+ *  Sibling of the derived `memory/` mount, ALWAYS on the config-root side — when the memory dir is
+ *  configured in-repo, the control plane still lives here (model-invisible, not injected, not in-repo). */
+export function deriveControlPlaneDir(configRoot, key) {
+    return join(configRoot, deriveRepoKey(key), ".engine");
+}
+/**
+ * Resolve the memory-engine config root: explicit (`RunnerDeps.memoryEngineDir`) → `AGENT_DATA_DIR`
+ * env → `~/.ai-agent` (the same default family as the file stores' `resolveDataRoot`; re-stated here
+ * so core/memory-engine does not import from src/stores).
+ */
+export function resolveMemoryEngineRoot(explicit) {
+    const raw = explicit ?? process.env.AGENT_DATA_DIR ?? join(homedir(), ".ai-agent");
+    return isAbsolute(raw) ? raw : resolve(raw);
+}
+/**
+ * Filesystem-safe scope dir label. 评审 H5 (唯一映射): the cleaned slug alone is LOSSY
+ * (`org:7` and `org/7` both fold to `org-7` — two tenants, one directory = cross-scope bleed), so any
+ * scope whose cleaned form differs from the original gets a short content-hash suffix
+ * (`org-7-a1b2c3`), making the mapping injective for all practical inputs; an already-safe scope maps
+ * to itself (stable, human-readable). {@link registerScope} additionally FAIL-CLOSES on a registry
+ * collision (two distinct scopes → one dir name), so even a hash collision cannot silently merge scopes.
+ */
+export function scopeDirName(scope) {
+    if (/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(scope))
+        return scope;
+    const cleaned = scope.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^[.-]+/, "") || "scope";
+    const hash = createHash("sha256").update(scope, "utf8").digest("hex").slice(0, 6);
+    return `${cleaned}-${hash}`;
+}
+function readScopesRecord(controlDir) {
+    const path = join(controlDir, SCOPES_FILE);
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return {}; // absent ⇒ genuinely unclaimed (first run)
+        // 对抗复审 L4: any OTHER read failure (EACCES/EIO/…) is NOT "unclaimed" — swallowing it would let
+        // the next locked update overwrite the registry with an empty table (a silent fail-open downgrade
+        // of a FAIL-CLOSED sidecar: CAS-load-bearing root claim + scope homes erased by a transient IO error).
+        throw new ControlPlaneCorruptError(`scope registry unreadable (${err.code ?? "io error"}): ${path}`, { cause: err });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new ControlPlaneCorruptError(`scope registry is unparseable: ${path}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new ControlPlaneCorruptError(`scope registry has the wrong shape: ${path}`);
+    }
+    const rec = parsed;
+    if (rec.rootScope !== undefined && typeof rec.rootScope !== "string") {
+        throw new ControlPlaneCorruptError(`scope registry rootScope is not a string: ${path}`);
+    }
+    let scopes;
+    if (rec.scopes !== undefined) {
+        if (!rec.scopes || typeof rec.scopes !== "object" || Array.isArray(rec.scopes)) {
+            throw new ControlPlaneCorruptError(`scope registry scopes map has the wrong shape: ${path}`);
+        }
+        for (const [k, v] of Object.entries(rec.scopes)) {
+            if (typeof v !== "string")
+                throw new ControlPlaneCorruptError(`scope registry entry ${JSON.stringify(k)} is not a string: ${path}`);
+        }
+        scopes = rec.scopes;
+    }
+    return { rootScope: rec.rootScope, scopes };
+}
+/**
+ * 独立轨 F5 (design/142 S2b 连带) — scopes.json read-modify-write under the SAME sidecar lock family
+ * as announcements/scan-fuse. The dual-root personal mount is ONE physical tree shared by every
+ * concurrent session on the machine: an unlocked first-use root-claim race (two sessions both read
+ * "unclaimed", both write themselves as rootScope, last-writer-wins) mis-attributes root-dir entries
+ * across scopes. NOT lockedJournaledUpdate: scopes.json is FAIL-CLOSED on corruption (B3) — this
+ * variant reads via readScopesRecord (throws ControlPlaneCorruptError) instead of fail-open rebuild.
+ */
+function lockedScopesUpdate(controlDir, fn) {
+    ensureDirExists(controlDir);
+    const file = join(controlDir, SCOPES_FILE);
+    const journal = `${file}.journal`;
+    const lock = `${file}.lock`;
+    // 对抗复审 L4 (second half): scopes.json is FAIL-CLOSED — a wedged lock must throw, never proceed
+    // lock-less into a read-modify-write of the registry (the fail-open deadline steal is for the
+    // non-load-bearing sidecars only). The read path (readScopesRecord) throws on non-ENOENT IO errors
+    // for the same reason. Same lock primitive as the fail-open family, so it shares the single-winner
+    // tombstone steal + owner-token release guard (L1/L2 class fixes).
+    const token = acquireSidecarLock(lock, { onDeadline: "throw" });
+    try {
+        rollForwardSidecar(file, journal);
+        const rec = readScopesRecord(controlDir);
+        const { next, result } = fn(rec);
+        if (next !== undefined) {
+            const data = `${JSON.stringify(next, null, 2)}\n`;
+            // L2-analog 归属复验 at the commit point: a holder stalled past LOCK_STALE_MS and stolen from
+            // must not commit over the stealer's registry write (fail-closed, unlike the fail-open family).
+            assertSidecarLockOwnership(lock, token, "scope registry");
+            atomicWriteFileSync(journal, data); // commit point (crash after this rolls forward)
+            atomicWriteFileSync(file, data);
+            rmSync(journal, { force: true });
+        }
+        return result;
+    }
+    finally {
+        releaseSidecarLock(lock, token);
+    }
+}
+/** Which scope owns the memory dir ROOT (undefined = unclaimed). */
+export function rootScopeOf(controlDir) {
+    return readScopesRecord(controlDir).rootScope;
+}
+/**
+ * Claim the memory dir root for `scope` iff unclaimed (idempotent, first-writer-wins, durable).
+ * Returns the (possibly pre-existing) root owner. Lock-serialized (独立轨 F5): two first-users of a
+ * shared mount race the claim under the sidecar lock — exactly one wins, the other SEES the winner.
+ */
+export function claimRootScope(controlDir, scope) {
+    return lockedScopesUpdate(controlDir, (rec) => {
+        if (rec.rootScope !== undefined)
+            return { result: rec.rootScope };
+        return { next: { rootScope: scope, scopes: { ...rec.scopes, [scope]: "" } }, result: scope };
+    });
+}
+/** Register `scope` in the durable registry (idempotent) and return its home dir under `memoryDir`.
+ *  H5 fail-closed: a dir-name collision with a DIFFERENT registered scope throws — two scopes must
+ *  never share one directory (silent cross-scope merge). Lock-serialized (独立轨 F5). */
+export function registerScope(memoryDir, controlDir, scope) {
+    return lockedScopesUpdate(controlDir, (rec) => {
+        const dirName = rec.rootScope === scope ? "" : scopeDirName(scope);
+        for (const [other, otherDir] of Object.entries(rec.scopes ?? {})) {
+            if (other !== scope && otherDir !== "" && otherDir === dirName) {
+                throw new ControlPlaneCorruptError(`scope directory collision: ${JSON.stringify(scope)} and ${JSON.stringify(other)} both map to ${JSON.stringify(dirName)} — refusing (fail-closed)`);
+            }
+        }
+        if (rec.scopes?.[scope] === undefined) {
+            return { next: { ...rec, scopes: { ...rec.scopes, [scope]: dirName } }, result: dirName === "" ? memoryDir : join(memoryDir, dirName) };
+        }
+        if (rec.scopes[scope] !== dirName) {
+            // A registered scope's home NEVER moves (entries live there) — honor the registry, not the formula.
+            return { result: rec.scopes[scope] === "" ? memoryDir : join(memoryDir, rec.scopes[scope]) };
+        }
+        return { result: dirName === "" ? memoryDir : join(memoryDir, dirName) };
+    });
+}
+/** All registered scopes → home dir name (`""` = the root). */
+export function registeredScopes(controlDir) {
+    return readScopesRecord(controlDir).scopes ?? {};
+}
+/** The stable home directory of `scope`'s entry files: the root when it owns the root, else the
+ *  REGISTERED subdir (falls back to the {@link scopeDirName} formula for a never-registered scope). */
+export function scopeDirFor(memoryDir, controlDir, scope) {
+    const rec = readScopesRecord(controlDir);
+    if (rec.rootScope === scope)
+        return memoryDir;
+    const registered = rec.scopes?.[scope];
+    if (registered !== undefined)
+        return registered === "" ? memoryDir : join(memoryDir, registered);
+    return join(memoryDir, scopeDirName(scope));
+}
+/** Canonicalize a path for containment checks (resolves symlinks on the EXISTING prefix). */
+export function canonicalize(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        // Non-existent leaf: canonicalize the nearest existing ancestor + re-append the remainder.
+        const parent = resolve(p, "..");
+        if (parent === p)
+            return p;
+        return join(canonicalize(parent), p.slice(parent.length + 1) || "");
+    }
+}
+/** True iff `child` (canonicalized) is `root` or inside it. */
+export function isContainedIn(root, child) {
+    const r = canonicalize(root);
+    const c = canonicalize(child);
+    // opus 1.258 review (LOW, platform sweep): `sep`, not a hardcoded '/', so win32 backslash paths
+    // neither fail-OPEN the write gate nor mass-reject harvest as outside_root.
+    return c === r || c.startsWith(`${r}${sep}`);
+}
+/** mkdir -p convenience used by the engine/backend (0o700 like the file stores). */
+export function ensureDirExists(dir) {
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+// ============================================================================
+// design/138 S2-B/S2-C — journaled control-plane state: the announcement queue
+// (`announcements.json`) and the write-scan fuse (`scan-fuse.json`).
+//
+// O-F6/C-F5: a bare read-modify-write over atomicWriteFileSync only prevents TORN files — two
+// concurrent writers (multi-worktree sessions sharing one repo-level control plane) would still
+// overwrite each other's enqueue. These sidecars therefore go through `lockedJournaledUpdate`:
+//   lock (cross-process mkdir mutex, stale-stolen) → roll forward any interrupted journal →
+//   re-read → mutate → journal (atomic rename = commit point) → execute (atomic file write) →
+//   drop journal → unlock.
+// This is the applyPatches stage→journal→execute discipline applied at sidecar scale, PLUS the
+// mutual exclusion the announcement path needs because its writers (harvest tail / read-side sync /
+// session-first drain) are not serialized by any CAS. Corrupt state stays FAIL-OPEN (discarded and
+// rebuilt): announcements/fuse counts are never CAS-load-bearing (§9.1 — only cursors share this).
+// ============================================================================
+/** S2-B — the queued memory-change announcements (control plane; drained at session-first inject). */
+export const ANNOUNCEMENTS_FILE = "announcements.json";
+/** S2-B — bounded queue: overflow FOLDS (oldest dropped, counted) instead of growing unbounded. */
+export const MEMORY_ANNOUNCEMENTS_MAX = 20;
+/** S2-C — per-file write-rejection counts (the beforeWrite silent-reject fuse; O-F9/C-F7: scoped
+ *  state in `.engine/`, so the count survives suspend/resume and backend re-construction). */
+export const SCAN_FUSE_FILE = "scan-fuse.json";
+/** Rejections at which the write-time feedback mutes (S2-C: 拒 ≥3 次熔断为静默拒). */
+export const SCAN_FUSE_THRESHOLD = 3;
+/** Synchronous sleep for the lock spin (Atomics.wait — no busy CPU loop, no async plumbing). */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+const LOCK_STALE_MS = 1_500;
+const LOCK_WAIT_CAP_MS = 3_000;
+/** Cross-process mutex via mkdir (atomic on POSIX). A lock older than {@link LOCK_STALE_MS} is
+ *  presumed crashed and stolen; after {@link LOCK_WAIT_CAP_MS} total we proceed anyway (fail-open —
+ *  these sidecars are not CAS-load-bearing, and wedging a session start on a lock would be worse).
+ *
+ *  opus 1.258 review (MED, steal TOCTOU): a bare rmSync+mkdir steal lets TWO stealers both win (B's
+ *  force-rm deletes A's FRESH lock). The steal is made single-winner by an atomic `renameSync` of the
+ *  stale lock dir to a unique tombstone first — rename is atomic, exactly one racer succeeds; the
+ *  loser's rename throws ENOENT and it loops back to a normal mkdir wait. The deadline branch keeps
+ *  the documented proceed-anyway semantics but steals through the same single-winner gate. */
+function acquireSidecarLock(lockDir, opts = {}) {
+    const deadline = Date.now() + LOCK_WAIT_CAP_MS;
+    const stealOnce = () => {
+        // Single-winner steal: atomic rename to a unique tombstone; only one racer's rename succeeds.
+        const tomb = `${lockDir}.stale-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+        try {
+            renameSync(lockDir, tomb);
+        }
+        catch {
+            return false; // another racer stole it (or the holder released) — go back to the mkdir wait
+        }
+        rmSync(tomb, { recursive: true, force: true });
+        return true;
+    };
+    for (;;) {
+        try {
+            mkdirSync(lockDir); // NOT recursive: recursive:true reports success on an EXISTING dir
+            // codex 1.258 review (MED, second half): OWNER TOKEN — a holder that stalls past LOCK_STALE_MS
+            // and gets stolen must not, on resume, delete the NEW holder's lock (its finally used to rm
+            // unconditionally). The token names this acquisition; release only removes the lock while the
+            // token is still ours.
+            const token = `${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+            try {
+                writeSync(openSync(join(lockDir, "owner"), "w"), token);
+            }
+            catch {
+                /* best-effort — a tokenless lock releases like the pre-token behavior */
+            }
+            return token;
+        }
+        catch {
+            try {
+                const age = Date.now() - statSync(lockDir).mtimeMs;
+                if (age > LOCK_STALE_MS) {
+                    stealOnce(); // win or lose, loop back to mkdir — losers must NOT force-rm the winner's fresh lock
+                    continue;
+                }
+            }
+            catch {
+                continue; // holder released between mkdir and stat — retry immediately
+            }
+            if (Date.now() > deadline) {
+                if (opts.onDeadline === "throw") {
+                    // 对抗复审 L4: fail-closed callers (scopes.json) never proceed lock-less. No all-dead window
+                    // here (L3 class): LOCK_STALE_MS < LOCK_WAIT_CAP_MS, so a crashed holder is always stolen
+                    // BEFORE this deadline — reaching it means live contention wedged, which must surface.
+                    throw new Error(`sidecar lock wait timed out (${LOCK_WAIT_CAP_MS}ms) at ${lockDir} — refusing to proceed without the lock (fail-closed sidecar)`);
+                }
+                stealOnce(); // documented fail-open: proceed anyway, but through the single-winner gate
+                continue;
+            }
+            sleepSync(5);
+        }
+    }
+}
+/** Roll an interrupted sidecar journal forward (journal exists ⇒ its content IS the committed next
+ *  state — adopt it). An unparseable journal is dropped (fail-open — see module note above). */
+function rollForwardSidecar(file, journal) {
+    let raw;
+    try {
+        raw = readFileSync(journal, "utf8");
+    }
+    catch {
+        return; // no journal — nothing interrupted
+    }
+    try {
+        JSON.parse(raw); // adopt only a parseable journal
+        atomicWriteFileSync(file, raw);
+    }
+    catch {
+        /* fail-open: unknowable partial state for a non-load-bearing sidecar — discard */
+    }
+    rmSync(journal, { force: true });
+}
+/** The locked, journaled sidecar update (see module note). `mutate` receives the parsed current
+ *  state (undefined when absent/corrupt — fail-open) and returns the next state, or undefined to
+ *  skip the write entirely (read-only pass). */
+function lockedJournaledUpdate(controlDir, fileName, mutate) {
+    ensureDirExists(controlDir);
+    const file = join(controlDir, fileName);
+    const journal = `${file}.journal`;
+    const lock = `${file}.lock`;
+    const token = acquireSidecarLock(lock);
+    try {
+        rollForwardSidecar(file, journal);
+        let current;
+        try {
+            current = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch {
+            current = undefined; // absent/corrupt ⇒ rebuild (fail-open)
+        }
+        const next = mutate(current);
+        if (next === undefined)
+            return;
+        const data = `${JSON.stringify(next, null, 2)}\n`;
+        atomicWriteFileSync(journal, data); // commit point (crash after this rolls forward)
+        atomicWriteFileSync(file, data);
+        rmSync(journal, { force: true });
+    }
+    finally {
+        releaseSidecarLock(lock, token);
+    }
+}
+/** 对抗复审 L2-analog (fail-closed callers only): re-verify the owner token at the COMMIT POINT —
+ *  a stolen-from holder aborts instead of writing over the stealer. Lenient on an absent/unreadable
+ *  owner file (token writes are best-effort in this family — same leniency as release), strict on a
+ *  FOREIGN token (that is a positive proof the lock is someone else's now). */
+function assertSidecarLockOwnership(lockDir, token, what) {
+    let held;
+    try {
+        held = readFileSync(join(lockDir, "owner"), "utf8");
+    }
+    catch {
+        return; // pre-token degraded shape — cannot disprove ownership
+    }
+    if (held !== token) {
+        throw new ControlPlaneCorruptError(`${what}: sidecar lock ownership lost before commit (holder stalled past ${LOCK_STALE_MS}ms and was stolen from) — update aborted`);
+    }
+}
+/** Release only while the owner token is still OURS (codex 1.258 MED second half): a holder that was
+ *  stolen from (stall > LOCK_STALE_MS) finds a foreign/absent token and leaves the new holder's lock
+ *  alone — its own write may have raced, but the sidecars are fail-open and the NEXT locked update
+ *  self-heals; deleting the live lock would instead cascade a third writer in. */
+function releaseSidecarLock(lockDir, token) {
+    try {
+        const held = readFileSync(join(lockDir, "owner"), "utf8");
+        if (held !== token)
+            return; // stolen while we stalled — the lock is someone else's now
+    }
+    catch {
+        /* owner file unreadable/absent: fall through and release (pre-token degraded shape) */
+    }
+    rmSync(lockDir, { recursive: true, force: true });
+}
+/** Read a sidecar with journal roll-forward SEMANTICS but no writes (safe without the lock: a
+ *  journal present means that content is the committed next state). */
+function readSidecarJson(controlDir, fileName) {
+    const file = join(controlDir, fileName);
+    for (const p of [`${file}.journal`, file]) {
+        try {
+            return JSON.parse(readFileSync(p, "utf8"));
+        }
+        catch {
+            /* try the next source */
+        }
+    }
+    return undefined;
+}
+/** Lenient shape recovery (fail-open): keep only well-formed entries, never throw. */
+function coerceAnnouncements(raw) {
+    const rec = { folded: 0, queue: [] };
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return rec;
+    const r = raw;
+    if (typeof r.folded === "number" && Number.isFinite(r.folded) && r.folded > 0)
+        rec.folded = Math.floor(r.folded);
+    if (Array.isArray(r.queue)) {
+        for (const e of r.queue) {
+            const a = e;
+            if (a &&
+                typeof a === "object" &&
+                (a.kind === "gate" || a.kind === "external") &&
+                typeof a.at === "number" &&
+                Array.isArray(a.items) &&
+                a.items.every((i) => typeof i === "string")) {
+                rec.queue.push({ kind: a.kind, at: a.at, ...(typeof a.sessionId === "string" ? { sessionId: a.sessionId } : {}), items: a.items });
+            }
+        }
+    }
+    return rec;
+}
+/** S2-B — enqueue one announcement (journaled + locked; bounded with overflow folding). */
+export function enqueueMemoryAnnouncement(controlDir, ann) {
+    if (ann.items.length === 0)
+        return;
+    lockedJournaledUpdate(controlDir, ANNOUNCEMENTS_FILE, (current) => {
+        const rec = coerceAnnouncements(current);
+        rec.queue.push(ann);
+        if (rec.queue.length > MEMORY_ANNOUNCEMENTS_MAX) {
+            rec.folded += rec.queue.length - MEMORY_ANNOUNCEMENTS_MAX;
+            rec.queue = rec.queue.slice(-MEMORY_ANNOUNCEMENTS_MAX);
+        }
+        return rec;
+    });
+}
+/** S2-B — drain the queue (session-first inject, 时机①). Returns what was queued and resets it. */
+export function drainMemoryAnnouncements(controlDir) {
+    const file = join(controlDir, ANNOUNCEMENTS_FILE);
+    if (!existsSync(file) && !existsSync(`${file}.journal`))
+        return { folded: 0, queue: [] }; // fast path: nothing queued, no lock/write
+    let drained = { folded: 0, queue: [] };
+    lockedJournaledUpdate(controlDir, ANNOUNCEMENTS_FILE, (current) => {
+        drained = coerceAnnouncements(current);
+        if (drained.queue.length === 0 && drained.folded === 0)
+            return undefined; // nothing to reset
+        return { folded: 0, queue: [] };
+    });
+    return drained;
+}
+/** Test/observability peek (journal-aware, non-destructive). */
+export function peekMemoryAnnouncements(controlDir) {
+    return coerceAnnouncements(readSidecarJson(controlDir, ANNOUNCEMENTS_FILE));
+}
+function coerceFuse(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        if (typeof v === "number" && Number.isFinite(v) && v > 0)
+            out[k] = Math.floor(v);
+    }
+    return out;
+}
+/** S2-C — record one write-time scan rejection for `key` (canonical file path); returns the count
+ *  BEFORE this bump (callers mute the feedback when it is already ≥ {@link SCAN_FUSE_THRESHOLD}). */
+export function bumpScanFuse(controlDir, key) {
+    let prior = 0;
+    lockedJournaledUpdate(controlDir, SCAN_FUSE_FILE, (current) => {
+        const counts = coerceFuse(current);
+        prior = counts[key] ?? 0;
+        counts[key] = prior + 1;
+        return counts;
+    });
+    return prior;
+}
+/** S2-C — the current fuse count for `key` (0 = never rejected / cleared). */
+/** F1 (REPORT-EXTENDED-2026-07-08) — the derived-index rev snapshot: target → entry rev AS OF the
+ *  last rebuild. rebuildIndex keeps a model-worded index line only while the entry rev is unchanged;
+ *  a rev change drops the stale wording (the injected index otherwise answers the OLD value for the
+ *  next session). Control plane, best-effort, fail-open (absent/corrupt ⇒ {}). */
+const INDEX_REVS_FILE = "index-revs.json";
+export function readIndexRevs(controlDir) {
+    const parsed = readSidecarJson(controlDir, INDEX_REVS_FILE);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(parsed))
+        if (typeof v === "string")
+            out[k] = v;
+    return out;
+}
+export function writeIndexRevs(controlDir, revs) {
+    try {
+        ensureDirExists(controlDir);
+        atomicWriteFileSync(join(controlDir, INDEX_REVS_FILE), `${JSON.stringify(revs, null, 2)}\n`);
+    }
+    catch {
+        /* best-effort — a missed snapshot degrades to keep-model-wording-once, never breaks rebuild */
+    }
+}
+export function scanFuseCount(controlDir, key) {
+    return coerceFuse(readSidecarJson(controlDir, SCAN_FUSE_FILE))[key] ?? 0;
+}
+/** S2-C — clear the fuse for files harvest just ACCEPTED (a committed write resets the strike count). */
+export function clearScanFuse(controlDir, keys) {
+    const wanted = [...keys];
+    if (wanted.length === 0)
+        return;
+    const file = join(controlDir, SCAN_FUSE_FILE);
+    if (!existsSync(file) && !existsSync(`${file}.journal`))
+        return;
+    lockedJournaledUpdate(controlDir, SCAN_FUSE_FILE, (current) => {
+        const counts = coerceFuse(current);
+        let changed = false;
+        for (const k of wanted) {
+            if (counts[k] !== undefined) {
+                delete counts[k];
+                changed = true;
+            }
+        }
+        return changed ? counts : undefined;
+    });
+}
+/** B3/H4 — durable atomic write: tmp file in the SAME directory (rename atomicity needs one fs),
+ *  fsync'd, then renamed over the target. Every control-plane sidecar write goes through this — a
+ *  crash can leave the OLD content or the NEW content, never a torn file. Throws on failure
+ *  (fail-closed: a sidecar that cannot be written must not be silently skipped). */
+export function atomicWriteFileSync(path, data) {
+    ensureDirExists(dirname(path));
+    const tmp = join(dirname(path), `.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`);
+    const fd = openSync(tmp, "w", 0o600);
+    try {
+        writeSync(fd, data);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            /* best-effort tmp cleanup */
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=layout.js.map