@sema-agent/core 7.15.0 → 7.16.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 7.16.0 — 2026-09-12
+
+### BREAKING — memory directory layout: every scope's home is `<memoryDir>/<label>`, the memory root is nobody's home (#699; design/699; @server @cli @test)
+- **Before.** The first write scope ever used for a memory dir claimed the ROOT itself (loose `*.md` + `MEMORY.md` at `<memoryDir>/`) and every later scope nested beneath it (`<memoryDir>/<label>/`). Ten rules hung off that: a durable root claim, an empty-label ⇔ root-scope registry invariant, three-arm home derivation, a `""` exception in both collision arms, three copies of "exclude the sibling scope dirs when scanning the root", a `skipRoot`/`excludeTopDirs` chmod special case, a runner fence arm refusing a write root that contains another scope, the erase sweep treating the root as an index home, read-only sessions reading the root's `MEMORY.md`, and six sidecars keyed by physical paths.
+- **After (five rules).** ① A scope's home is `join(memoryDir, label)` with `label = scopeDirName(scope)` (the registered label is the truth once written); the memory dir itself is never a home. ② The registry is `scopes.json = { v: 2, scopes, rootOwner?, migrating? }`; every label matches `SCOPE_DIR_LABEL_RE = /^[A-Za-z0-9_][A-Za-z0-9._-]*$/` (the closure of `scopeDirName`'s outputs; pinned by a 5k-input property); the four read shapes `absent | legacy | v2 | migrating` are a closed set (`SCOPE_REGISTRY_SHAPES`, disposition table `REGISTRY_SHAPE_DERIVES_PATHS`, registered in `docs/CLOSED-SETS.md`) — `legacy` and `migrating` are refused fail-closed by `registerScope` / `scopeDirFor` / `registeredScopes` until the adoption has run. ③ A home must be a REAL directory or absent (`lstat` at registration and at every mount; a link or a file at the home path refuses). ④ The two collision arms (exact + case-fold) are unchanged minus the `""` exception. ⑤ Every persistent sidecar key that names a memory file is the ledger form `(scope, rel)` — projection debts, instruction holds, session-account membership, the write-scan fuse — so a home move never re-keys anything (`index-revs.json` and `MEMORY.md` link targets stay model-facing physical coordinates, by design).
+- **Migration (one-shot, two-phase, durable; `adoptRootScopeLayout` in `layout.ts`).** Runs before the first registry-derived path of every mount (`MemoryEngine.materialize` → the backend's `adoptRootScopeLayout` face under its transaction lock, plus the copy-out projection tree directly) and at the head of every backend public face (`ensureLayout`, non-blocking try-acquire; the locked faces run it under their lock; a view object runs it on every call). Phase 0 converts the registry (`rootScope` → `rootOwner`, the owner gets its label) and enumerates the root's loose content on EVERY call; content with an owner (`rootOwner ?? this mount's write scope / the batch's first add scope`) passes four zero-write pre-checks (control plane inside the root; the home a link/file or a non-empty directory with no move in progress; any loose name already present in the home) or refuses with `ControlPlaneCorruptError` (memory-less + loud at the runner). Commit A writes the `migrating` marker; phase 1 moves each entry (`lstat` destination, `rename`, source-gone = already moved) and removes `.casefold-probe-*` residue; phase 2 clears `index-revs.json`; commit B drops the marker. No sidecar key and no index text is rewritten (cross-scope index lines heal under the existing rebuild law: orphan cleared, mechanical row re-minted, model wording lost once). A registry lock heartbeat (`utimes` + strict ownership re-proof, plus the backend's transaction-lock heartbeat) runs before every action; a lost lock throws immediately and the next holder resumes from the marker. Content with NO owner on record (a read-only mount over a registry-less root) is left in place, disclosed once, never served. Two disclosure codes: `memory.layout_migrated`, `memory.layout_unowned_root_content` (incident sink).
+- **BREAKING (package surface).** `MemorySessionHandle.writableRoot` is `string | null` — `null` iff there is no write face (`writeScope === null`); it is never `memoryDir` any more. New `writableRootOf(handle)` (throws on `null`) for call sites that established a write face. `scanEntryFiles(dir, { exclude })` — the `exclude` option is removed. `MemoryEngine.readonlyDirNamesUnderRoot` is REMOVED, together with the runner arm that was its only consumer: the set it answered — another scope's directory lying under the writable root — is empty by construction now that homes never nest. Internal bucket: `claimRootScope` / `rootScopeOf` removed.
+- **BREAKING (on disk; downstream may read or seed these).** `scopes.json` form (above). `projection-debts.json` / `holds.json` / `session-accounts.json` are `version: 2` with `(scope, rel)` keys (`HoldRow.relPath` → `HoldRow.rel`, home-relative; `SessionAccountRow.unattributed` is `Array<{ scope, rel }>` plus `unattributable?: string[]`); each converts once, in its own lock, on the first read that finds the old form (idempotent by field name + version); a row the registry cannot attribute is KEPT (`unresolved` / `unattributable`) and never served / marks the whole session unattributed — never dropped. `scan-fuse.json` is `{ v: 2, counts }` keyed by `scanFuseKey(scope, rel)`; the absolute-path form is dropped (fail-open reset). The user-visible path of every entry and index gains one level (`memory/x.md` → `memory/<label>/x.md`; server's default scope `local` ⇒ `memory/local/`).
+- **Narrowing (read-only sessions).** An all-read-only session (`writableRoot === null`) never reads a `MEMORY.md` from disk in either provenance mode — its index is the mechanical rebuild off committed headers (links computed against the memory dir as a virtual base). The model-worded index the root owner's read-only sessions used to get by accident is no longer served to them; write sessions are unchanged.
+- **Retired special cases.** Root claim at materialize and at `applyPatches`; `siblingScopeDirNames`, `excludedSubdirNames`, the five `isRoot` scan branches, `chmodScopeTree`'s `skipRoot` / `excludeTopDirs`; the erase sweep's memory-root index candidate (its failure text names `<scope homes>`); the harvest/materialize `exclude` sets. `gateWrite` on a read-only handle judges the whole plane (`memoryDir`) and refuses every path under it with `read_only_layering`.
+- **Runner (the fence).** `prepare-memory.ts` consumes `writableRootOf(writeHandle)` at the admission seat and takes an explicit `root !== null` branch in the two write-gate legs. The admission's sibling-scope refusal is gone: `foreignUnderRoot` keeps only the control-plane arm (a directory advertised to the model must not contain the engine's own metadata), and `writeChannelOpen` keeps all four conjuncts. Consequence — the deployment the old arm refused (the write scope owning the root with any other scope registered: a single-user server with an org layer, or any `defaultScopes` extra) is admitted and taught again, and it is not a hole: the admitted directory is that scope's home, so a sibling scope's file, the homes' shared parent and a scope another process registers mid-session all stay outside the fence (`path_not_in_root`).
+- **Operations.** Stop every process sharing a memory dir before upgrading; an older engine re-occupying the root after the move leaves a non-empty home beside loose root content, which the next mount refuses loudly (no silent merge). Interruption safety is process-level (`atomicWriteFileSync` does not fsync directories); every step resumes from the registry marker and the sidecar row forms.
+- **Review rounds (adversarial, three; all findings reproduced by reading, adopted unless noted).** Round 1 — five: a registry commit fenced only before its journal write (a holder stolen from past its commit point could overwrite the stealer's main file / remove its journal) → strict ownership re-proved before each of the three steps; the v1 sidecar key conversions were lazy (a scope registered after the move, named like an old topic directory, would re-read a v1 key's first segment) → converted inside the adoption; a v1 hold row's slug was not shape-checked (a crafted row could derive an escaping seat) → the rel-path shape law on `slug`; registry accumulators over `{}` dropped a `__proto__` scope → null-prototype accumulators; a v1 root owner whose prospective home already stood non-empty was silently re-read under new slugs → refused before conversion. Round 2 — three: conversion ran after the commit that cleared the durable mark → conversion now precedes every registry commit (the v1 registry / the marker stays until every sidecar is in the ledger form); the strict journal roll-forward replayed unfenced → fenced before its replay write and its journal removal; a home spelled in another letter case on a folding volume was enumerated as loose content and moved into itself → recognized by directory identity, self-move refused. Round 3 — three: the strict-ledger commit (holds / session accounts / projection debts) had the round-1 gap → fenced like the registry commit; the marker persisted the root verbatim (a relative spelling resumed from another cwd would read as finished) → absolute; **declared, not chased**: the window between a fence and the atomic writer's publishing rename is inherent to the mkdir-lock design (three rounds on the same root — the lock family — stop here by rule).
+- Pins: `test/memory-layout-migration.test.ts` (39 — P1 registry shapes + the 5k label property; P2 exclusivity + physical form; P3 mainline on the real load path; P4 idempotence + three breakpoints + a foreign-tree marker; P5 four pre-checks; P6 heartbeat + stolen lock; P7 journal-before-adoption; P9 read-only index both modes; P10 owner resolution ①–④; P11 chmod; P12/P15 erase sweep; P14 tripwire; P16 read-only gate; P17 key conversions + unattributable rows; the review-round seams: conversion-before-registration, the escaping v1 hold slug, the `__proto__` scope, the occupied v1 home, the stolen-lock commit refusal, pre-check 4 on the v2 path, the heartbeat refusing at the very next action, the backend face's replay-then-adopt order, conversion-before-commit on both branches, the folded home spelling, the absolute marker root); re-pinned `memory-engine` / `memory-scope-enumeration` / `memory-txn-lock` registry pins and the design/336 hold/account fixtures. Re-pinned end-to-end through the Runner: `test/backlog691-advertised-writable-dir.test.ts` (P8 — two scopes over one memory dir, the write scope the first writer: home admitted and taught, own home read/write both ways, sibling + mid-session third scope + shared parent refused, no refused/skipped line). Wire rows: `docs/wire-consumption/unreleased-699.md`.
+
+- Docs/gate (#710) · new `gate:docs-tool-names` fails on a RETIRED tool name (`report_blocked`, `run_workflow`, `web_fetch`, `submit_output`, `present_plan`, `tool_search`, `MultiEdit`, `bash_readonly`, …) surviving in `docs/**/*.md` outside a small historical-record whitelist; one-time rename sweep over `ARCHITECTURE.md`, `GATE-OUTCOME-STATIONS.md`, `INTEGRATION-CORE.md`, `PROMPT-ASSEMBLY-EXECUTION-PLAN.md`, `PROMPT-ASSEMBLY-HANDOFF.md`, `PROMPT-SECTION-MAP.md`, `PROMPT-SENTENCE-EVIDENCE-INDEX.md`, `ROADMAP.md`, `SERVICE-INTEGRATION-GUIDE.md`, `sdk/02`, `sdk/07`, `sdk/09` to their live names, plus one factual fix (`sdk/09-security-and-policies.md`: `handsReadOnly` mounts `Bash` in its read-only posture, not a separate `bash_readonly` tool). No behaviour change.
+
+### Contract — `Model.cost` is optional; `isModelPriced` is exported (#718; @server @cli)
+- **Member-level type change (package surface).** `Model.cost` is now `cost?: {…}`. The runtime already read it as optional everywhere — `modelCostToPricing(undefined)` yields the all-zero table, `selectModel` sorts a model without `cost` as `Infinity`, every brain adapter reads `c?.input ?? 0`, and the RB-368 predicate `isModelPriced` takes `cost?: unknown` — only the type claimed it was required, so a host without a price table had to fabricate one or cast. Absent ⇒ UNPRICED; a free model declares four `0` rates; the two are now distinguishable at the type as they already were at runtime. Readers of `model.cost.<rate>` on a core-typed `Model` must guard for absence (compile-time; no core read and no server/cli `src` read does so unguarded).
+- **Exported.** `isModelPriced(model, pricing)` (tier `advanced`) — the one RB-368 predicate ("does a price table EXIST": an id-keyed `RunnerDeps.pricing` entry or the model's own `cost`) that a host previously had to re-implement beside `computeCostMicroUsd` / `modelCostToPricing`.
+- Pins: `test/backlog718-model-cost-optional.test.ts` (the literal without `cost` typechecks; predicate three-way; root export identity); `test/export-surface.snapshot.json`.
+
+### Tooling (no behaviour change)
+- Docs (#704 ② pilot sweep · `src/tools/fs`, comments only — zero behaviour face): every comment in the bucket now states a contract or an invariant; the ticket ids (`RB-NNN`/`#NNN`/`design/NNN`), channel coordinates, review-round attributions, batch names and deprecated-corpus byte offsets are gone, and a defect retelling is rewritten as the rule that holds. CC parity/divergence assertions, fail-closed reasons, refusal orderings and safety consequences are kept verbatim in substance. Bucket reading: comment lines 7334→7147, ratio 0.4835→0.4771, process-word hits 863→9 (the 9 remaining are English false positives — `Math.round`, `round trip`). Four bucket ratchets banked (`comment-ratio`, `internal-wording` 46→3, `line-anchor` 15→6, `legacy-residue` 35→33) plus one now-unique `contract-sentences` baseline row removed. Narrative archived to the internal repo.
+- Docs (#704 ② sweep · `src/core/runner`, comments only — zero behaviour face, 36 batch commits): a mechanical two-tier label stripper (leading ticket-cluster removal + capitalize-restart; pure-citation-parenthetical removal) over all 111 files in the bucket, followed by a hand fix where the stripper's capitalization exposed a pre-existing cross-file exact-duplicate sentence (`gate:contract-sentences`) between `prepare-boundary-parks.ts` and `prepare-park-ask.ts` — the shorter copy is now a pointer to the fuller one. Every comment keeps its contract/invariant content, fail-closed reasoning and CC-anchor sentence verbatim; only the leading `design/NNN`/`RB-NNN`/`#NNN`/`[NNNN]`/`codex …` coordinate cluster and pure-citation parentheticals are gone. Bucket reading: comment lines 23666→23667 (+1, the dedup-fix wrap), total lines 47238→47239, ratio 0.5010→0.50101, process-word hits 3048→1340 (56% down; the residue is dominated by domain vocabulary the lexicon false-positives on — `review`/`round` inside real identifiers like `dry_run_review`/`plan_review`/`Math.round` — plus mid-sentence citations the leading-label/pure-citation matchers deliberately do not touch). Two bucket ratchets banked (`comment-ratio` processHitsMax 3048→1340, ratioMax 0.501→0.5011; `internal-wording` 174→121); `legacy-residue` (104) and `line-anchor` (13) unchanged for this bucket. No internal-archive file — every removed span was a short ticket/citation label, not a relocatable narrative paragraph.
+- Docs (#704 ② sweep, second pass · `src/core/runner`, comments only — zero behaviour face, ~30 batch commits, hand-edited): the first pass's leading-label/pure-citation matchers were conservative on mid-sentence and multi-line citations (design/RB/#/[NNNN]/codex-round/rescan clusters woven into the middle of a contract sentence); this pass read every one of the 1204 process-word hits the first pass left (excluding `prepare-memory.ts`, car A/#699's file) by hand, file by file, and either compressed the citation out of the sentence (keeping the contract clause) or confirmed the hit as genuine domain vocabulary the lexicon false-positives on (`review`/`plan_review`/`human-review`/`dry-run review`/`code-review` — real gate-kind and CC-tool names, not review-process narrative; `round` inside `model round`/`classifier round`/`round cap`/`corrective round` — real bounded-iteration counts, not review-round citations). `design`/`RB`/`#`/`codex`/`rescan` citations are now at ZERO across the whole bucket (one `[1995]①` kept verbatim — a quoted test-name string, not a citation). Bucket reading (excluding `prepare-memory.ts`, unchanged by this car): process-word hits 1204→149 (88% down on the touched files); whole-bucket total (incl. `prepare-memory.ts`'s 109, task-0 census regex false-positive fix applied first) 1313→258. Two bucket ratchets banked (`comment-ratio` processHitsMax 1340→258; `internal-wording` 121→91) plus one `contract-sentences` baseline shrink (a 14-file and a 2-file duplicate row both resolved; one new byte-identical duplicate the citation-stripping introduced was reworded, not admitted). `comment-census.mjs`'s `PROCESS_WORD_RE` gained two false-positive exclusions (`Math.round(...)`/`round trip` no longer match `round`; identifier-embedded `review` spellings were already excluded by the existing word boundary, now pinned) — every bucket's baseline in `test/comment-ratio-ratchet.test.ts` re-measured and banked down to match (lower-only). Two structural-pin test landmarks in `prepare-wiring-manifest.ts` were reverted verbatim after breaking `test/design385-slice2b-agents.test.ts`'s exact-substring search (test files are off-limits; the source comment kept its citation instead). No internal-archive file — every removed span was a citation label or a short compressible clause, not a relocatable narrative paragraph.
+- Added · `npm run car:gate -- '<word list>' [--base <sha>] [--full] [--log-dir <dir>]` (`scripts/car-gate.mjs`, #705): runs a dispatch order's door-family as one command — `tsc --noEmit`, a derived vitest suite (content-grepped `test/*.test.ts` ∪ the eleven door-family pins ∪ `test/gate-all-roster.test.ts`; hub names in the word list auto-stripped and announced), and `verify-layering`; `--full` adds `npm run build && node scripts/gate-all.mjs --with-dist --rc`. Any step non-zero makes the whole run non-zero and every step still runs. Pins: `test/car-gate.test.ts`.
+- Added · `npm run gate:comment-ratio` (`scripts/comment-census.mjs`, #704, gate-landing only — no src sweep in this car): a per-directory-bucket ratchet on `src/**/*.ts`'s comment-line ratio and process-word (round/rescan/codex/design-ticket/battle-narrative) hit count, sibling to `internal-wording-gate`/`legacy-residue-gate`. One-way (ratchet-down-must-bank), a HARD cap (0.25 ratio / 0 hits) for a bucket absent from the table, wired into `gate:all`'s static tier. Pins: `test/comment-ratio-ratchet.test.ts`.
+
 ## 7.15.0 — 2026-09-11
 
 ### Internal — abstraction unification pass over the 7.15.0 merges (no behaviour change; exports +1 type)

package/dist/core/governance-codes.js

@@ -14,6 +14,8 @@ export const NON_GOVERNANCE_MEMORY_CODES = new Set([
     "memory.announce_failed",
     "memory.partition_adopt_failed",
     "memory.partition_split",
+    "memory.layout_migrated",
+    "memory.layout_unowned_root_content",
     "memory.tail",
     "memory.pollution_mark_failed",
     "memory.session_polluted",

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

@@ -144,32 +144,54 @@ export declare function replayExternalSettlementEffects(controlDir: string, inpu
     sessionId: string;
 }>;
 export declare const SESSION_ACCOUNTS_FILE = "session-accounts.json";
+/** One member of the sticky set: the ledger form `(scope, rel)` — `rel` relative to the scope's
+ *  home, `/`-separated. Location-free, so a home move never re-keys the membership. */
+export interface UnattributedMember {
+    scope: string;
+    rel: string;
+}
 export interface SessionAccountRow {
     sessionId: string;
     openedAt: number;
-    /** The STICKY unattributed set (rel paths), frozen at materialize (§3.6 归属判据): pre-existing,
-     *  uncommitted files seen while a FOREIGN dangling open row stood. Membership never shrinks on
-     *  later writes (the r3-5 sticky law); it clears only when the row is re-opened with a fresh
-     *  classification (the residue was adjudicated by an intervening harvest). */
-    unattributed: string[];
+    /** The STICKY unattributed set, frozen at materialize (§3.6 归属判据): pre-existing, uncommitted
+     *  files seen while a FOREIGN dangling open row stood. Membership never shrinks on later writes
+     *  (the sticky law); it clears only when the row is re-opened with a fresh classification (the
+     *  residue was adjudicated by an intervening harvest). */
+    unattributed: UnattributedMember[];
+    /** The v1 members (memory-dir-relative paths) the registry could not attribute at the one-time
+     *  conversion. Kept, never dropped; while any stands, EVERY membership question about
+     *  this session answers "unattributed" (over-marking is the safe direction). */
+    unattributable?: string[];
     closedAt?: number;
     /** r7-3 — the host valve closed this row WITHOUT adjudication: it stops dangling but keeps
      *  triggering the residue arm until the next FULL-domain harvest closes an account normally
      *  (an unadjudicated close must not launder the residue window it covered). */
     unadjudicated?: true;
 }
+/** The one-time v1 key-form conversions of the three engine sidecars, in one call (each in its own
+ *  lock, each idempotent). The layout adoption runs this before any later scope registration can
+ *  change what a v1 key's first segment names. */
+export declare function convertV1SidecarKeys(controlDir: string): void;
 /** The dangling-trigger read: open rows (and unadjudicated closes) belonging to OTHER sessions.
  *  These are what arm the unattributed residue classification at a session's materialize. */
 export declare function foreignDanglingSessionAccounts(controlDir: string, selfSessionId: string): SessionAccountRow[];
+/** The membership question the harvest asks per file: is `(scope, rel)` in the session's sticky
+ *  set? A session carrying members the conversion could not attribute answers yes for every seat. */
+export interface SessionUnattributedSet {
+    has(scope: string, rel: string): boolean;
+    /** True when no seat can answer yes (no members, none unattributable). */
+    readonly empty: boolean;
+}
+export declare function emptyUnattributedSet(): SessionUnattributedSet;
 /** Open (or re-open, on a same-session resume) the session's account row, persisting the sticky
  *  unattributed classification frozen at THIS materialize. */
 export declare function openSessionAccount(controlDir: string, input: {
     sessionId: string;
     now: () => number;
-    unattributed: readonly string[];
+    unattributed: readonly UnattributedMember[];
 }): void;
 /** The current session's sticky unattributed set (the harvest's residue-arm input). */
-export declare function sessionUnattributedSet(controlDir: string, sessionId: string): Set<string>;
+export declare function sessionUnattributedSet(controlDir: string, sessionId: string): SessionUnattributedSet;
 /** Close the session's account row — called ONLY after a FULL-domain harvest (zero BUDGET-deferred
  *  files, i.e. `HarvestReport.degraded` absent): a partial harvest's close would launder the deferred
  *  residue window (§3.6 序则②). A normal full close also clears every standing `unadjudicated` flag
@@ -209,8 +231,10 @@ export interface HoldRow {
     op: "add" | "update";
     /** CAS anchor at capture time (update form): release refuses to blind-write over a later edit. */
     baseRev?: string;
-    /** Path relative to the memory dir (the plane seat the file was removed from). */
-    relPath: string;
+    /** The plane seat the file was removed from, in the ledger form: relative to the write scope's
+     *  home (`<memoryDir>/<label>`), `/`-separated — `${slug}.md`. Location-free, so a home move never
+     *  re-keys a hold. */
+    rel: string;
     /** The entry slug (path relative to the scope dir, sans `.md`) — the release leg's projection
      *  identity and its filename-scan input. */
     slug: string;
@@ -263,7 +287,8 @@ export declare function noReplaceRestore(stagingPath: string, destPath: string):
  */
 export declare function openInstructionHold(controlDir: string, input: {
     sessionId: string;
-    relPath: string;
+    /** The seat in the ledger form (relative to the write scope's home). */
+    rel: string;
     absPath: string;
     content: string;
     entryId?: string;
@@ -290,11 +315,11 @@ export declare function openInstructionHold(controlDir: string, input: {
  *    (the file stays on the plane and walks the ordinary/§3.6 arms; never "capture whatever is
  *    there now" — that would hold a third writer's bytes under the first writer's account);
  *  - `capturing` + custody absent + plane file gone ⇒ `capture_lost` (nothing to hold).
- *  - `held` + plane file REAPPEARED at the relPath ⇒ left alone (a fresh write is a fresh file —
+ *  - `held` + plane file REAPPEARED at the seat ⇒ left alone (a fresh write is a fresh file —
  *    the next harvest judges it on its own; the hold's custody bytes stay the hold's).
  */
 export declare function reconcileHolds(controlDir: string, input: {
-    memoryDir: string;
+    homeOf: (scope: string) => string;
     now: () => number;
 }): void;
 /** Dispose one held row: custody bytes move to the quarantine directory (host-auditable), the row

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

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, linkSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { QUARANTINE_DIR, appendChallengeEvents, enqueueMemoryAnnouncement, ensureDirExists, lineageContributionsOfSession, lockedStrictUpdate, markSessionPolluted, readSessionPollution, readStrictSidecar, ControlPlaneCorruptError } from "./layout.js";
+import { QUARANTINE_DIR, appendChallengeEvents, enqueueMemoryAnnouncement, ensureDirExists, v1MemoryPathKeyResolver, lineageContributionsOfSession, lockedStrictUpdate, markSessionPolluted, readProjectionDebts, readSessionPollution, readStrictSidecar, ControlPlaneCorruptError } from "./layout.js";
 export const DELEGATION_SETTLEMENT_FILE = "delegation-settlement.json";
 function reqStr(v) {
     return typeof v === "string" && v.length > 0;
@@ -233,36 +233,101 @@ export function replayExternalSettlementEffects(controlDir, input) {
     return applied;
 }
 export const SESSION_ACCOUNTS_FILE = "session-accounts.json";
+function malformedAccountRow(row) {
+    return (typeof row !== "object" ||
+        row === null ||
+        !reqStr(row.sessionId) ||
+        typeof row.openedAt !== "number" ||
+        !Number.isFinite(row.openedAt) ||
+        !Array.isArray(row.unattributed) ||
+        (row.closedAt !== undefined && (typeof row.closedAt !== "number" || !Number.isFinite(row.closedAt))) ||
+        (row.unadjudicated !== undefined && row.unadjudicated !== true));
+}
+function isUnattributedMember(x) {
+    return typeof x === "object" && x !== null && reqStr(x.scope) && safeRelPath(x.rel);
+}
 function coerceSessionAccounts(raw) {
     if (raw === undefined)
-        return { version: 1, rows: [] };
+        return { version: 2, rows: [] };
     const rec = raw;
     if (typeof rec !== "object" || rec === null || !Array.isArray(rec.rows))
         throw new ControlPlaneCorruptError("memory session-account ledger has the wrong shape");
-    if (rec.version !== 1)
+    if (rec.version !== 1 && rec.version !== 2)
         throw new ControlPlaneCorruptError(`memory session-account ledger has an unrecognized version (${String(rec.version)}) — refusing (fail-closed)`);
-    for (const r of rec.rows) {
+    const bad = () => {
+        throw new ControlPlaneCorruptError("memory session-account ledger: a row is malformed — refusing (fail-closed; an unevaluable row must not read as adjudicated)");
+    };
+    const rows = rec.rows;
+    for (const r of rows) {
         const row = r;
-        if (typeof row !== "object" ||
-            row === null ||
-            !reqStr(row.sessionId) ||
-            typeof row.openedAt !== "number" ||
-            !Number.isFinite(row.openedAt) ||
-            !Array.isArray(row.unattributed) ||
-            row.unattributed.some((x) => typeof x !== "string") ||
-            (row.closedAt !== undefined && (typeof row.closedAt !== "number" || !Number.isFinite(row.closedAt))) ||
-            (row.unadjudicated !== undefined && row.unadjudicated !== true)) {
-            throw new ControlPlaneCorruptError("memory session-account ledger: a row is malformed — refusing (fail-closed; an unevaluable row must not read as adjudicated)");
+        if (malformedAccountRow(row))
+            bad();
+        const members = Array.isArray(row.unattributed) ? row.unattributed : bad();
+        if (rec.version === 1) {
+            if (members.some((x) => typeof x !== "string"))
+                bad();
         }
-    }
-    return rec;
+        else {
+            if (!members.every(isUnattributedMember))
+                bad();
+            if (row.unattributable !== undefined && (!Array.isArray(row.unattributable) || row.unattributable.some((x) => typeof x !== "string")))
+                bad();
+        }
+    }
+    return rec.version === 1 ? { version: 1, rows: rows } : { version: 2, rows: rows };
+}
+function convertSessionAccounts(read, controlDir) {
+    if (read.version === 2)
+        return { rec: read, converted: false };
+    const resolve = v1MemoryPathKeyResolver(controlDir);
+    const rows = read.rows.map((r) => {
+        const unattributed = [];
+        const unattributable = [];
+        for (const relPath of r.unattributed) {
+            const key = resolve(relPath);
+            if (key === undefined)
+                unattributable.push(relPath);
+            else
+                unattributed.push(key);
+        }
+        return {
+            sessionId: r.sessionId,
+            openedAt: r.openedAt,
+            unattributed,
+            ...(unattributable.length > 0 ? { unattributable } : {}),
+            ...(r.closedAt !== undefined ? { closedAt: r.closedAt } : {}),
+            ...(r.unadjudicated !== undefined ? { unadjudicated: r.unadjudicated } : {}),
+        };
+    });
+    return { rec: { version: 2, rows }, converted: true };
+}
+export function convertV1SidecarKeys(controlDir) {
+    readProjectionDebts(controlDir);
+    readHolds(controlDir);
+    readSessionAccountsConverted(controlDir);
+}
+function readSessionAccountsConverted(controlDir) {
+    const read = coerceSessionAccounts(readStrictSidecar(controlDir, SESSION_ACCOUNTS_FILE, "memory session-account ledger"));
+    if (read.version === 2)
+        return read;
+    return lockedStrictUpdate(controlDir, SESSION_ACCOUNTS_FILE, "memory session-account ledger", coerceSessionAccounts, (again) => {
+        const { rec, converted } = convertSessionAccounts(again, controlDir);
+        return converted ? { next: rec, result: rec } : { result: rec };
+    });
 }
 export function foreignDanglingSessionAccounts(controlDir, selfSessionId) {
-    const rec = coerceSessionAccounts(readStrictSidecar(controlDir, SESSION_ACCOUNTS_FILE, "memory session-account ledger"));
+    const rec = readSessionAccountsConverted(controlDir);
     return rec.rows.filter((r) => r.sessionId !== selfSessionId && (r.closedAt === undefined || r.unadjudicated === true));
 }
+export function emptyUnattributedSet() {
+    return { has: () => false, empty: true };
+}
+function memberKey(scope, rel) {
+    return JSON.stringify([scope, rel]);
+}
 export function openSessionAccount(controlDir, input) {
-    lockedStrictUpdate(controlDir, SESSION_ACCOUNTS_FILE, "memory session-account ledger", coerceSessionAccounts, (rec) => {
+    lockedStrictUpdate(controlDir, SESSION_ACCOUNTS_FILE, "memory session-account ledger", coerceSessionAccounts, (read) => {
+        const { rec } = convertSessionAccounts(read, controlDir);
         const row = rec.rows.find((r) => r.sessionId === input.sessionId);
         if (row === undefined) {
             rec.rows.push({ sessionId: input.sessionId, openedAt: input.now(), unattributed: [...input.unattributed] });
@@ -276,17 +341,25 @@ export function openSessionAccount(controlDir, input) {
             row.openedAt = input.now();
             delete row.closedAt;
             delete row.unadjudicated;
-            row.unattributed = [...new Set([...row.unattributed, ...input.unattributed])];
+            const merged = new Map(row.unattributed.map((m) => [memberKey(m.scope, m.rel), m]));
+            for (const m of input.unattributed)
+                merged.set(memberKey(m.scope, m.rel), { scope: m.scope, rel: m.rel });
+            row.unattributed = [...merged.values()];
         }
         return { next: rec, result: undefined };
     });
 }
 export function sessionUnattributedSet(controlDir, sessionId) {
-    const rec = coerceSessionAccounts(readStrictSidecar(controlDir, SESSION_ACCOUNTS_FILE, "memory session-account ledger"));
-    return new Set(rec.rows.find((r) => r.sessionId === sessionId)?.unattributed ?? []);
+    const row = readSessionAccountsConverted(controlDir).rows.find((r) => r.sessionId === sessionId);
+    if (row === undefined)
+        return emptyUnattributedSet();
+    const all = (row.unattributable?.length ?? 0) > 0;
+    const keys = new Set(row.unattributed.map((m) => memberKey(m.scope, m.rel)));
+    return { has: (scope, rel) => all || keys.has(memberKey(scope, rel.split("\\").join("/"))), empty: !all && keys.size === 0 };
 }
 export function closeSessionAccount(controlDir, input) {
-    return lockedStrictUpdate(controlDir, SESSION_ACCOUNTS_FILE, "memory session-account ledger", coerceSessionAccounts, (rec) => {
+    return lockedStrictUpdate(controlDir, SESSION_ACCOUNTS_FILE, "memory session-account ledger", coerceSessionAccounts, (read) => {
+        const { rec } = convertSessionAccounts(read, controlDir);
         const row = rec.rows.find((r) => r.sessionId === input.sessionId);
         if (row === undefined)
             return { result: false };
@@ -303,7 +376,8 @@ export function resolveSessionAccountRecord(controlDir, input) {
         e.code = "memory.session_account_resolve_unattributed";
         throw e;
     }
-    lockedStrictUpdate(controlDir, SESSION_ACCOUNTS_FILE, "memory session-account ledger", coerceSessionAccounts, (rec) => {
+    lockedStrictUpdate(controlDir, SESSION_ACCOUNTS_FILE, "memory session-account ledger", coerceSessionAccounts, (read) => {
+        const { rec } = convertSessionAccounts(read, controlDir);
         const row = rec.rows.find((r) => r.sessionId === input.sessionId);
         if (row === undefined) {
             const e = new Error(`resolveSessionAccount: unknown sessionId ${JSON.stringify(input.sessionId)}`);
@@ -321,21 +395,23 @@ const HOLD_STATUSES = new Set(["capturing", "held", "released", "disposed"]);
 const HOLD_TERMINALS = new Set(["dirty", "expired", "conflict", "discarded", "capture_lost"]);
 function coerceHolds(raw) {
     if (raw === undefined)
-        return { version: 1, rows: [] };
+        return { version: 2, rows: [] };
     const rec = raw;
     if (typeof rec !== "object" || rec === null || !Array.isArray(rec.rows))
         throw new ControlPlaneCorruptError("memory instruction-hold ledger has the wrong shape");
-    if (rec.version !== 1)
+    if (rec.version !== 1 && rec.version !== 2)
         throw new ControlPlaneCorruptError(`memory instruction-hold ledger has an unrecognized version (${String(rec.version)}) — refusing (fail-closed)`);
-    for (const r of rec.rows) {
+    const v1 = rec.version === 1;
+    const rows = [];
+    const raws = rec.rows;
+    for (const r of raws) {
         const row = r;
         if (typeof row !== "object" ||
             row === null ||
             !reqStr(row.holdId) ||
             !reqStr(row.sessionId) ||
             (row.op !== "add" && row.op !== "update") ||
-            !reqStr(row.relPath) ||
-            !reqStr(row.slug) ||
+            !safeRelPath(row.slug) ||
             !reqStr(row.scope) ||
             !reqStr(row.captureName) ||
             !reqStr(row.contentDigest) ||
@@ -350,15 +426,28 @@ function coerceHolds(raw) {
             (row.entryId !== undefined && typeof row.entryId !== "string") ||
             (row.baseRev !== undefined && typeof row.baseRev !== "string") ||
             (row.op === "update" && (!reqStr(row.entryId) || !reqStr(row.baseRev))) ||
-            !safeRelPath(row.relPath) ||
+            (v1 ? !safeRelPath(row.relPath) : !safeRelPath(row.rel)) ||
             !safeBasename(row.captureName)) {
             throw new ControlPlaneCorruptError("memory instruction-hold ledger: a row is malformed — refusing (fail-closed; an unevaluable hold must not read as settled)");
         }
+        if (v1) {
+            const { relPath: _relPath, ...rest } = row;
+            rows.push({ ...rest, rel: `${row.slug}.md` });
+        }
+        else {
+            rows.push(row);
+        }
     }
-    return rec;
+    return { version: 2, rows };
+}
+function holdsOnDiskAreV1(raw) {
+    return typeof raw === "object" && raw !== null && raw.version === 1;
 }
 export function readHolds(controlDir) {
-    return coerceHolds(readStrictSidecar(controlDir, HOLDS_FILE, "memory instruction-hold ledger")).rows;
+    const raw = readStrictSidecar(controlDir, HOLDS_FILE, "memory instruction-hold ledger");
+    if (!holdsOnDiskAreV1(raw))
+        return coerceHolds(raw).rows;
+    return lockedStrictUpdate(controlDir, HOLDS_FILE, "memory instruction-hold ledger", coerceHolds, (again) => ({ next: again, result: again.rows }));
 }
 function sha256(buf) {
     return createHash("sha256").update(buf).digest("hex");
@@ -397,7 +486,7 @@ export function noReplaceRestore(stagingPath, destPath) {
     return "restored";
 }
 export function openInstructionHold(controlDir, input) {
-    const holdId = `hold-${input.now()}-${createHash("sha256").update(`${input.sessionId}\n${input.relPath}\n${input.content}`).digest("hex").slice(0, 12)}`;
+    const holdId = `hold-${input.now()}-${createHash("sha256").update(`${input.sessionId}\n${input.rel}\n${input.content}`).digest("hex").slice(0, 12)}`;
     const buf = Buffer.from(input.content, "utf8");
     const digest = sha256(buf);
     const captureName = `${holdId}.md`;
@@ -420,7 +509,7 @@ export function openInstructionHold(controlDir, input) {
                 ...(input.entryId !== undefined ? { entryId: input.entryId } : {}),
                 op: input.op,
                 ...(input.baseRev !== undefined ? { baseRev: input.baseRev } : {}),
-                relPath: input.relPath,
+                rel: input.rel,
                 slug: input.slug,
                 scope: input.scope,
                 captureName,
@@ -490,12 +579,12 @@ export function openInstructionHold(controlDir, input) {
 }
 export function reconcileHolds(controlDir, input) {
     const holdDir = join(controlDir, HOLD_DIR);
-    const discloseStranded = (holdId, relPath, stagingName) => {
+    const discloseStranded = (holdId, rel, stagingName) => {
         try {
             enqueueMemoryAnnouncement(controlDir, {
                 kind: "gate",
                 at: input.now(),
-                items: [`instruction hold ${holdId}: a concurrent writer's bytes for ${JSON.stringify(relPath)} could not be restored onto the plane — they are preserved at hold/${stagingName} in the memory control plane for host recovery`],
+                items: [`instruction hold ${holdId}: a concurrent writer's bytes for ${JSON.stringify(rel)} could not be restored onto the plane — they are preserved at hold/${stagingName} in the memory control plane for host recovery`],
             });
         }
         catch {
@@ -512,7 +601,7 @@ export function reconcileHolds(controlDir, input) {
                 terminalLost = true;
             }
             else {
-                const plane = join(input.memoryDir, row.relPath);
+                const plane = join(input.homeOf(row.scope), row.rel);
                 if (existsSync(plane)) {
                     try {
                         const stagingName = uniqueStagingName(row.holdId, input.now);
@@ -522,7 +611,7 @@ export function reconcileHolds(controlDir, input) {
                             unlinkSync(staging);
                         }
                         else if (noReplaceRestore(staging, plane) === "stranded") {
-                            discloseStranded(row.holdId, row.relPath, stagingName);
+                            discloseStranded(row.holdId, row.rel, stagingName);
                         }
                     }
                     catch {
@@ -531,7 +620,7 @@ export function reconcileHolds(controlDir, input) {
             }
         }
         else {
-            const plane = join(input.memoryDir, row.relPath);
+            const plane = join(input.homeOf(row.scope), row.rel);
             if (existsSync(plane)) {
                 const bytes = readFileSync(plane);
                 if (sha256(bytes) === row.contentDigest) {
@@ -549,7 +638,7 @@ export function reconcileHolds(controlDir, input) {
                             }
                         }
                         else if (noReplaceRestore(staging, plane) === "stranded") {
-                            discloseStranded(row.holdId, row.relPath, stagingName);
+                            discloseStranded(row.holdId, row.rel, stagingName);
                         }
                     }
                     catch {

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

@@ -1186,6 +1186,10 @@ export declare class MemoryEngine {
      *  eventId anchors on the pollution record (sessionId + marked-at), so however many times this
      *  settlement replays the same pollution event, the generation is allocated once. */
     private settlePromotions;
+    /** The layout-adoption seat of a mount: a backend pinning its own directory root adopts under its
+     *  transaction lock; a copy-out projection tree and a backend without the face are adopted by the
+     *  engine directly (registry lock only — nothing else writes those trees during a mount). */
+    private adoptLayoutBeforeMount;
     materialize(scopes: readonly string[], writeScope: string | null, opts?: {
         adoptionRestricted?: boolean;
         sessionId?: string;
@@ -1242,6 +1246,9 @@ export declare class MemoryEngine {
      * Throws only on a corrupt hold/settlement ledger — the caller's fail-closed reconciliation arm
      * refuses the harvest (integrity unknown must not read as "no holds").
      */
+    /** A hold's plane seat as a memory-dir-relative path (the report/warning spelling every other
+     *  harvest path uses), derived from the ledger-form row. */
+    private holdPlaneRel;
     private settleDueHolds;
     /**
      * The release leg: re-walk the captured bytes through the FULL gate set and commit them under
@@ -1663,8 +1670,6 @@ export declare class MemoryEngine {
      * @returns the rejection to report, or `undefined` when the index is clean/absent.
      */
     private gateDerivedIndex;
-    /** Names of read-only sibling scope dirs directly under the writable root (excluded from scans; public since #691 — the runner refuses to admit a writable root that contains another scope's directory to the file tools' allowlist). */
-    readonlyDirNamesUnderRoot(handle: MemorySessionHandle): Set<string>;
     /** Projection write: reads the target to skip a no-op, then writes — the same check-then-use shape
      *  as the containment restores, so it takes the same no-follow write. A link at a projection path
      *  is never a supported layout (the harvest scan refuses symlinked entry files outright), and this
@@ -1699,12 +1704,8 @@ export declare class MemoryEngine {
      * `getByIds` there would sync-adopt mid-harvest.
      */
     private debtCommittedProjection;
-    /** Sibling scope subdir names under `dir` (excluded from a scope-tree walk when `dir` is the root —
-     *  a root-owning layer's chmod/restore must never touch another scope's home). */
-    private siblingScopeDirNames;
-    /** chmod a scope's entry tree (best-effort; skipRoot leaves the top dir writable — used when a
-     *  read-only layer's dir IS the shared root / an ancestor of the writable root, which must stay
-     *  traversable+writable; excludeTopDirs skips sibling scope homes under a root-owning layer).
+    /** chmod a scope's entry tree (best-effort). The tree is the scope's own home and nothing else —
+     *  no other scope's directory can lie under it.
      *
      *  `opts.announced` is the CALLER's per-materialize ledger of paths already disclosed (#495 M-1).
      *  One materialize sweeps each inherited tree TWICE — restore write perms at the top, re-apply