spexcode 0.6.7 → 0.7.0-next.0

package/node_modules/@spexcode/spec-cli/dist/lint.js

@@ -1,9 +1,10 @@
 import { readFileSync, existsSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { repoRoot, git, sourceIndexes, rowsFor, treeFilePaths, treeFileText, withEventLedgerBuild } from '@spexcode/spec-core';
-import { loadSpecs, parseFrontmatter } from '@spexcode/spec-core';
+import { bodyMentions, loadSpecs, parseFrontmatter } from '@spexcode/spec-core';
 import { readJsonConfig } from '@spexcode/spec-core';
-import { extractors, extractorFor, extOf, parseCodeEntry, relationClaimsPath, resolveSelectors, windowEvents, anchorHitQueries } from '@spexcode/spec-core';
+import { extractors, extractorFor, extOf, parseCodeEntry, parseRelation, relationClaimsPath, resolveSelectors, windowEvents, anchorHitQueries } from '@spexcode/spec-core';
+import { EVAL_FILE, parseScenarios } from '@spexcode/spec-eval/scenarios';
 import { DEFAULT_TEST_GLOBS, sourcePolicyDescription, trackedSourceFiles } from './source-files.js';
 export const SPEC_LINT_REPORT_PROJECTION = 'spex.spec-lint.report';
 export const SPEC_LINT_REPORT_SCHEMA_VERSION = 1;
@@ -276,24 +277,17 @@ async function specLintInLedger(root, regs, options) {
         }
     // mention: a `[[id]]` in a body must name a real node (ERROR — a dangling mention is a broken edge in
     // the very graph the tree exists to keep honest). Checked against the SAME minted ids every other
-    // surface resolves ([[id-url-safe]]). Prose only: a fenced block or inline `code span` is sample text
-    // (`[[node]]`, `[[<id>]]` placeholders live there), not a reference.
+    // surface resolves ([[id-url-safe]]). The body reader is `bodyMentions`, and this rule is now its ONLY
+    // consumer: the loader used to ship the surviving names as a per-node edge, and that projection is gone
+    // ([[context-dock]]) because a prose mention is a fact about the graph, never about the node the reader
+    // has open. The parser stays where it is — judging what is prose and what is sample text is the same
+    // judgement whoever asks, and this rule is the one place a name must be resolved at all.
+    // One finding per distinct dangling name: a name repeated in one body is still one broken edge.
     const idSet = new Set(specs.map((s) => s.id));
-    const MENTION_RE = /\[\[(\.?[\p{L}\p{N}_-]+)\]\]/gu;
     for (const s of specs) {
-        let inFence = false;
-        for (const rawLine of s.body.split('\n')) {
-            if (/^\s*```/.test(rawLine)) {
-                inFence = !inFence;
-                continue;
-            }
-            if (inFence)
-                continue;
-            const line = rawLine.replace(/`[^`]*`/g, '');
-            for (const m of line.matchAll(MENTION_RE)) {
-                if (!idSet.has(m[1]))
-                    out.push({ level: 'error', rule: 'mention', spec: s.id, msg: `'${s.id}' mentions [[${m[1]}]] — no such node; retarget or drop it (backtick it if it is sample text)` });
-            }
+        for (const id of bodyMentions(s.body)) {
+            if (!idSet.has(id))
+                out.push({ level: 'error', rule: 'mention', spec: s.id, msg: `'${s.id}' mentions [[${id}]] — no such node; retarget or drop it (backtick it if it is sample text)` });
         }
     }
     // living: a spec body describes the node's CURRENT intent — it is not a changelog. Version history
@@ -329,19 +323,53 @@ async function specLintInLedger(root, regs, options) {
         const top = over.slice(0, 5).map(([f, ids]) => `${f.split('/').pop()}(${ids.length})`).join(', ');
         out.push({ level: 'warn', rule: 'owners', msg: `${over.length} file(s) are governed by > ${cfg.maxOwners} nodes — each holds more separately-specified functionality than one file should. Worst: ${top}. SPLIT the file so each governor owns its own module (or merge the nodes, or give it a single foundation owner + related:).` });
     }
+    const nodeSource = (s, relation, entries) => ({ relation, entries, drift: true, owner: `'${s.id}'`, repair: `the spec's ${relation}: entry` });
+    const scenarioSources = (s) => {
+        const evalPath = join(dirname(s.path), EVAL_FILE);
+        if (!existsAtTip(evalPath))
+            return [];
+        let scenarios;
+        // A malformed eval.md is `spex eval lint`'s eval-schema finding, not this gate's: refusing to parse it
+        // here would turn one measurement-layer typo into a blocked commit.
+        try {
+            scenarios = parseScenarios(textAtTip(evalPath) ?? '');
+        }
+        catch {
+            return [];
+        }
+        return scenarios.flatMap((sc) => [
+            // ONLY the scenario's OWN declarations. An empty scenario `code:` inherits the node's axis, and those
+            // entries are already this node's source above — re-reading them here would double-report one selector.
+            { relation: 'code', raw: sc.code },
+            { relation: 'related', raw: sc.related },
+        ].flatMap(({ relation, raw }) => raw?.length
+            ? [{ relation, entries: parseRelation([...raw], relation).entries, drift: false,
+                    owner: `'${s.id}' scenario '${sc.name}'`, repair: `the scenario's ${relation}: entry in ${evalPath}` }]
+            : []));
+    };
     const readyWarned = new Set();
     const anchorSteps = [];
+    // One parse per candidate file per run, shared by every source that anchors it. Without it a file many
+    // scenarios anchor is re-extracted once per scenario, and extraction is the expensive half of this gate.
+    const unitsAtTip = new Map();
     for (const s of specs) {
-        for (const { relation, entries } of [{ relation: 'code', entries: s.codeScoped }, { relation: 'related', entries: s.relatedScoped }]) {
-            for (const { path, selectors } of entries) {
+        for (const src of [
+            nodeSource(s, 'code', s.codeScoped),
+            nodeSource(s, 'related', s.relatedScoped),
+            ...scenarioSources(s),
+        ]) {
+            const { relation, drift, owner, repair } = src;
+            for (const { path, selectors } of src.entries) {
+                if (!selectors.length)
+                    continue;
                 if (pending && !changed.some((file) => relationClaimsPath(path, file)))
                     continue;
                 const x = extractorFor(regs, extOf(path));
                 if (!x) {
-                    anchorSteps.push({ finding: { level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `'${s.id}' anchors ${path}#${selectors.join(', #')} (${relation}:), but no extractor is designated for '.${extOf(path)}' files — anchor validation was skipped and remains unverified; add a LangSpec row (anchors.ts) or drop the selector(s)` } });
+                    anchorSteps.push({ finding: { level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `${owner} anchors ${path}#${selectors.join(', #')} (${relation}:), but no extractor is designated for '.${extOf(path)}' files — anchor validation was skipped and remains unverified; add a Tree-sitter language row (anchors.ts) or drop the selector(s)` } });
                     continue;
                 }
-                const ready = x.ready();
+                const ready = await x.ready();
                 if (ready !== true) {
                     // once per (extractor, reason), even across several anchored nodes — one repair, one message.
                     if (!readyWarned.has(x.id + ready)) {
@@ -353,20 +381,27 @@ async function specLintInLedger(root, regs, options) {
                 if (!existsAtTip(path))
                     continue; // the missing FILE already errored above
                 if (isDirectoryAtTip(path)) {
-                    anchorSteps.push({ finding: { level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `'${s.id}' puts a selector on a directory (${relation}: ${path}#${selectors[0]}) — a selector scopes ONE real file` } });
+                    anchorSteps.push({ finding: { level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `${owner} puts a selector on a directory (${relation}: ${path}#${selectors[0]}) — a selector scopes ONE real file` } });
                     continue;
                 }
-                let units;
-                try {
-                    const source = textAtTip(path);
-                    if (source === null)
-                        throw new Error(`candidate tree has no file '${path}'`);
-                    units = x.extract(source, path);
+                let cached = unitsAtTip.get(path);
+                if (!cached) {
+                    try {
+                        const source = textAtTip(path);
+                        if (source === null)
+                            throw new Error(`candidate tree has no file '${path}'`);
+                        cached = { units: await x.extract(source, path) };
+                    }
+                    catch (e) {
+                        cached = { error: e?.message ?? String(e) };
+                    }
+                    unitsAtTip.set(path, cached);
                 }
-                catch (e) {
-                    anchorSteps.push({ finding: { level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `anchor ${path}#${selectors.join(', #')} ('${s.id}') is unverifiable — the current file does not parse: ${e?.message ?? e}` } });
+                if ('error' in cached) {
+                    anchorSteps.push({ finding: { level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `anchor ${path}#${selectors.join(', #')} (${owner}) is unverifiable — the current file does not parse: ${cached.error}` } });
                     continue;
                 }
+                const units = cached.units;
                 // each selector resolves (or errors) on its own; only the live ones feed the window engine.
                 // The dead/ambiguous verdict itself comes from the ONE shared classifier ([[code-anchor]]); only the
                 // wording of the gate's findings lives here.
@@ -374,18 +409,18 @@ async function specLintInLedger(root, regs, options) {
                 for (const res of resolveSelectors(units, selectors)) {
                     const sym = res.selector;
                     if ('dead' in res) {
-                        anchorSteps.push({ finding: { level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `dead anchor: ${path}#${sym} ('${s.id}') names no unit on the current tree — the unit was deleted or renamed; update the spec's ${relation}: entry to follow it` } });
+                        anchorSteps.push({ finding: { level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `dead anchor: ${path}#${sym} (${owner}) names no unit on the current tree — the unit was deleted or renamed; update ${repair} to follow it` } });
                         continue;
                     }
                     if ('ambiguous' in res) {
-                        anchorSteps.push({ finding: { level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `ambiguous anchor: ${path}#${sym} ('${s.id}') names ${res.ambiguous} same-named units in one file — an anchor must be unique; rename one unit` } });
+                        anchorSteps.push({ finding: { level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `ambiguous anchor: ${path}#${sym} (${owner}) names ${res.ambiguous} same-named units in one file — an anchor must be unique; rename one unit` } });
                         continue;
                     }
                     if (res.ok.typeOnly)
                         anchorSteps.push({ finding: { level: 'warn', rule: 'anchor', spec: s.id, file: path, msg: `${path}#${sym} anchors a ${res.ok.kind} — anchoring a type is usually wrong (types reshape with every refactor); anchor the behaviour-bearing unit instead` } });
                     live.push(sym);
                 }
-                if (!live.length)
+                if (!drift || !live.length)
                     continue;
                 const since = rowsFor(hidx, s.path)[0]?.hash || '';
                 const win = windowEvents(didx, since, path, s.id);

package/node_modules/@spexcode/spec-cli/dist/listen.d.ts

@@ -1,8 +1,9 @@
 import type { Server } from 'node:net';
+export declare function resolveConfiguredPort(rawPort: string | undefined): number;
 export declare function listenOrExit(server: Server, port: number, opts: {
     host?: string;
     label: string;
     cleanup?: () => void;
-    onListen?: () => void;
-    ready: string | string[];
+    onListen?: (port: number) => void;
+    ready: string | string[] | ((port: number) => string | string[]);
 }): void;

package/node_modules/@spexcode/spec-cli/dist/listen.js

@@ -1,3 +1,13 @@
+export function resolveConfiguredPort(rawPort) {
+    const normalized = rawPort?.trim();
+    if (!normalized)
+        return 8787;
+    const port = Number(normalized);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new Error(`PORT must be an integer from 0 to 65535, got ${JSON.stringify(rawPort)}`);
+    }
+    return port;
+}
 // @@@ listenOrExit ([[listener-readiness]]) - the one public-listener transition: before `listening`, a bind
 // failure is loud and fatal; after it, publication side effects and user-visible ready lines may run. Keeping
 // both halves here prevents a private child or pre-bind caller from announcing a surface it does not own.
@@ -13,8 +23,10 @@ export function listenOrExit(server, port, opts) {
         process.exit(1);
     });
     const publishReady = () => {
-        opts.onListen?.();
-        for (const line of Array.isArray(opts.ready) ? opts.ready : [opts.ready])
+        const actualPort = server.address().port;
+        opts.onListen?.(actualPort);
+        const ready = typeof opts.ready === 'function' ? opts.ready(actualPort) : opts.ready;
+        for (const line of Array.isArray(ready) ? ready : [ready])
             console.log(line);
     };
     if (opts.host)

package/node_modules/@spexcode/spec-cli/dist/machine-peer.d.ts

@@ -51,8 +51,9 @@ export declare class MachinePeerGateway {
     private control;
     private retry;
     private closing;
-    start(): void;
+    start(): Promise<void>;
     private startControl;
+    private listenControl;
     private handleRpc;
     private startInbound;
     private stopInbound;

package/node_modules/@spexcode/spec-cli/dist/machine-peer.js

@@ -72,13 +72,17 @@ export function readPeerMachineId() {
     writeStore({ ...store, machineId });
     return machineId;
 }
+// @@@ peer sender spelling - the authenticated peer identity travels as the message's ordinary `senderSessionId`,
+// so it must fit the protocol's frozen session_id grammar `[0-9A-Za-z_][0-9A-Za-z_-]*` (session-protocol §5.2:
+// no `:`, no leading `-`; namespaces are encoded INTO the id). `peer_<machineId>_<sessionId>` is that encoding;
+// the earlier `peer:` spelling was refused by every receiving backend with PROTOCOL_SESSION_ID_INVALID.
 export function peerSenderRef(machineId, sessionId) {
-    return sessionId && validMachineId(sessionId) ? `peer:${machineId}:${sessionId}` : `peer:${machineId}`;
+    return sessionId && validMachineId(sessionId) ? `peer_${machineId}_${sessionId}` : `peer_${machineId}`;
 }
 function validPeerSender(value, machineId) {
     if (typeof value !== 'string')
         return false;
-    const match = value.match(/^peer:([0-9a-f-]{36})(?::([0-9a-f-]{36}))?$/i);
+    const match = value.match(/^peer_([0-9a-f-]{36})(?:_([0-9a-f-]{36}))?$/i);
     return !!match && match[1] === machineId && (match[2] === undefined || validMachineId(match[2]));
 }
 export function findMachinePeer(sshAddress) {
@@ -160,7 +164,7 @@ function peerProjectsForSession(sessionId) {
     const hits = [];
     for (const id of ids) {
         const root = join(projects, id);
-        const record = join(root, 'sessions', sessionId, 'session.json');
+        const record = join(root, 'sessions', sessionId, 'runtime.json');
         if (!existsSync(record))
             continue;
         const direct = readEndpointRecord(join(root, 'backend.json'));
@@ -367,34 +371,61 @@ function sshArgs(peer) {
         '--', peer.sshAddress,
     ];
 }
+// true iff something ACCEPTS a connection at this unix path; any error (ECONNREFUSED for a leftover path, ENOENT
+// for a vanished one) means no live listener.
+function probeUnixListener(path) {
+    return new Promise((resolve) => {
+        const socket = createConnection(path);
+        socket.once('connect', () => { socket.destroy(); resolve(true); });
+        socket.once('error', () => resolve(false));
+    });
+}
 export class MachinePeerGateway {
     inbound = new Map();
     children = new Map();
     control = null;
     retry = null;
     closing = false;
+    // start() resolves once the control socket is claimed. With no leftover path the claim is synchronous (the
+    // listener is issued before the promise settles, so callers may issue control RPCs right away); a leftover path
+    // is probed first, which is the only asynchronous branch.
     start() {
         for (const peer of listMachinePeers())
             this.startInbound(peer);
-        this.startControl();
-        for (const peer of listMachinePeers())
-            if (peer.owner)
-                this.ensureTunnel(peer);
-        this.retry = setInterval(() => {
+        return this.startControl().then(() => {
             for (const peer of listMachinePeers())
-                if (peer.owner && peer.state === 'connecting')
+                if (peer.owner)
                     this.ensureTunnel(peer);
-        }, PEER_RETRY_MS);
-        this.retry.unref();
+            this.retry = setInterval(() => {
+                for (const peer of listMachinePeers())
+                    if (peer.owner && peer.state === 'connecting')
+                        this.ensureTunnel(peer);
+            }, PEER_RETRY_MS);
+            this.retry.unref();
+        });
     }
+    // @@@ stale control socket - a killed gateway never unlinks peer.sock, so the FILE proves nothing about
+    // ownership; only a connect does. A live gateway accepts the connection; a leftover path refuses it
+    // (ECONNREFUSED). So a missing path is claimed at once, a refusing path is unlinked and reclaimed, and only an
+    // accepting listener is "another `spex dashboard`" — the same test claude-rendezvous applies to its socket file.
     startControl() {
         const path = peerSocketPath();
         mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-        if (existsSync(path)) {
-            const error = new Error(`machine peer service already owns ${path} — another \`spex dashboard\` may be running`);
-            error.name = 'BackendError';
-            throw error;
+        if (!existsSync(path)) {
+            this.listenControl(path);
+            return Promise.resolve();
         }
+        return probeUnixListener(path).then((live) => {
+            if (live) {
+                const error = new Error(`machine peer service already owns ${path} — another \`spex dashboard\` is running`);
+                error.name = 'BackendError';
+                throw error;
+            }
+            rmSync(path, { force: true });
+            this.listenControl(path);
+        });
+    }
+    listenControl(path) {
         this.control = createNetServer({ allowHalfOpen: true }, (socket) => {
             let input = '';
             socket.setEncoding('utf8');

package/node_modules/@spexcode/spec-cli/dist/materialize.d.ts

@@ -1,4 +1,4 @@
-import { type HarnessArtifacts } from './harness.js';
+import { GENERATED_MARK, type HarnessArtifacts } from './harness.js';
 export type MaterializedArtifact = {
     kind: 'hook manifest' | 'contract' | 'shim' | 'skill' | 'agent' | 'plugin bundle' | 'trust';
     path: string;
@@ -13,6 +13,6 @@ export declare function retiredAxisNotice(cfg: {
     private?: boolean;
 }): void;
 export declare function stripSpexcodeBlock(text: string, comment?: readonly [string, string]): string;
-export declare const GENERATED_MARK = "<!-- spexcode:generated -->";
+export { GENERATED_MARK };
 export declare function dematerialize(proj?: string, arts?: HarnessArtifacts): void;
 export declare function materialize(proj?: string): MaterializeResult;

package/node_modules/@spexcode/spec-cli/dist/materialize.js

@@ -4,13 +4,33 @@ import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import { loadSystemConfig, loadSkillConfig, loadAgentConfig, loadConfig } from '@spexcode/spec-core';
 import { compileManifest } from './hooks.js';
-import { writeManagedBlock, removeManagedBlock, HARNESSES } from './harness.js';
+import { writeManagedBlock, removeManagedBlock, writeManagedJsonHooks, removeManagedJsonHooks, sharedShimHasHostContent, isGeneratedArtifact, GENERATED_MARK, HARNESSES } from './harness.js';
 import { git, gitBinary } from '@spexcode/spec-core';
 import { runtimeRoot, treeSlotDir, mainCheckout, readConfig } from '@spexcode/spec-core';
 import { resolveHarnessTargets, partitionHarnesses } from './harness-select.js';
 import { emitPlugin, cleanPlugin, pluginBundleDir, pluginVersion } from './plugin-harness.js';
 import { clearContractFilterPayload, contractFilterPlanted, plantContractFilter, removeContractFilter, settleIndexStat } from './contract-filter.js';
 import { writeFileIfChanged } from './file-write.js';
+// land one shim. A file wholly ours is the plain byte-equality write; a config file the host agent SHARES with
+// the user gets ONLY our identity-stamped hook entries merged in, so their permissions, env, statusLine and
+// own hooks survive adoption (writeManagedJsonHooks, [[harness-adapter]]).
+// A shared file we cannot PARSE is the one landing that can fail, and it fails for a reason that is the
+// user's to fix. Report it and carry on: their broken JSON must not also cost them the contract, the skills
+// and the allowlist this pass still owes every other target (the pre-commit anchor runs this on the way into
+// every commit). Returns whether the shim actually landed.
+function landShim(file, shim) {
+    try {
+        if (shim.ownership === 'shared-json' && shim.hooks)
+            writeManagedJsonHooks(file, shim.hooks);
+        else
+            writeFileIfChanged(file, shim.content);
+        return true;
+    }
+    catch (e) {
+        console.error(`spexcode: no hooks delivered to ${file} — ${e.message}`);
+        return false;
+    }
+}
 const PKG = fileURLToPath(new URL('..', import.meta.url)); // installed spec-cli root
 const DISPATCH = join(PKG, 'hooks', 'dispatch.sh');
 // the ONE spex entry: the launcher (bin/spex.mjs), never a raw source entry - the launcher runs compiled
@@ -50,6 +70,53 @@ export function retiredAxisNotice(cfg) {
 function gitCommonDirOf(proj) {
     return git(['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim();
 }
+// Codex resolves linked-worktree project hooks from the main checkout, but old materializers left a second
+// executable copy in each worktree. Migrate only an exact SpexCode-only JSON config; a file with any user
+// hook is theirs and remains untouched. This is a one-time identity migration, not a sibling configuration
+// sweep: it never creates files and never changes the main checkout's owner.
+function retireLegacyCodexAnchors(checkout) {
+    let listing;
+    try {
+        listing = git(['-C', checkout, 'worktree', 'list', '--porcelain']);
+    }
+    catch {
+        return;
+    }
+    const paths = [...listing.matchAll(/^worktree (.+)$/gm)].map(match => match[1]).filter(path => path !== checkout);
+    for (const tree of paths) {
+        const file = join(tree, '.codex', 'hooks.json');
+        if (!existsSync(file))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            continue;
+        const hooks = parsed.hooks;
+        if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks))
+            continue;
+        const commands = [];
+        for (const groups of Object.values(hooks)) {
+            if (!Array.isArray(groups))
+                continue;
+            for (const group of groups) {
+                if (!group || typeof group !== 'object')
+                    continue;
+                for (const hook of group.hooks ?? []) {
+                    if (hook && typeof hook === 'object' && typeof hook.command === 'string')
+                        commands.push(hook.command);
+                }
+            }
+        }
+        if (!commands.length || commands.some(command => !command.includes('dispatch.sh')))
+            continue;
+        writeFileIfChanged(file, '{\n  "hooks": {}\n}\n');
+    }
+}
 function infoExcludePath(proj) {
     return join(gitCommonDirOf(proj), 'info', 'exclude');
 }
@@ -112,8 +179,10 @@ function hostContentOf(file) {
     return stripSpexcodeBlock(readFileSync(file, 'utf8'));
 }
 // the identity stamp on every generated skill/agent file — what lets the erase phase forget a product whose
-// NODE was renamed or deleted (the name-scoped sweep can only reconstruct paths the LIVE config still names).
-export const GENERATED_MARK = '<!-- spexcode:generated -->';
+// NODE was renamed or deleted (the name-scoped sweep can only reconstruct paths the LIVE config still names),
+// and what stops the write phase from landing on a same-named file the user wrote. Defined with the adapter
+// (both halves of the pass need it); re-exported here for the commit-surgery reader.
+export { GENERATED_MARK };
 function pruneGeneratedSkills(dir, keep) {
     if (!dir || !existsSync(dir))
         return false;
@@ -176,11 +245,20 @@ function reconcileTree(proj, targets, tracked) {
         removeManagedBlock(file, ['<!-- ', ' -->'], !tracked(file));
         removed = true;
     }
-    const treeShims = new Set(HARNESSES.filter((h) => h.shimScope === 'tree').map((h) => h.shimFile(proj)));
-    const anchors = new Set(HARNESSES.map((h) => h.worktreeHookAnchor(proj)).filter((path) => !!path));
-    for (const file of [...treeShims, ...anchors]) {
+    // a DESELECTED harness's shim is un-landed the same way its owner would clean it: entry-by-entry out of a
+    // config file the host agent shares with the user, whole-file only when the file is wholly ours.
+    const shimSites = HARNESSES.flatMap((h) => [
+        ...(h.shimScope === 'tree' ? [[h.shimFile(proj), h.shimOwnership]] : []),
+        ...((path) => path ? [[path, h.shimOwnership]] : [])(h.worktreeHookAnchor(proj)),
+    ]);
+    for (const [file, ownership] of new Map(shimSites)) {
         if (targets.treeShims.has(file) || targets.anchors.has(file) || !existsSync(file))
             continue;
+        if (ownership === 'shared-json') {
+            removeManagedJsonHooks(file);
+            removed = true;
+            continue;
+        }
         if (readFileSync(file, 'utf8').includes('dispatch.sh')) {
             rmSync(file, { force: true });
             removed = true;
@@ -266,6 +344,32 @@ export function materialize(proj = process.cwd()) {
     const targets = resolveHarnessTargets(cfg.harnesses);
     retiredAxisNotice(cfg); // [[residence]] — the vote axis is retired
     const { selected, plugins } = partitionHarnesses(targets);
+    // WHERE a shim lives and WHICH toolchain it names are two questions, and only the first is per-tree.
+    //
+    // Residence is forced by the adapter: Codex reads one project shim shared by every linked worktree, while
+    // Claude reads project settings from the session's cwd only, so every tree carries its own copy.
+    //
+    // The toolchain is the SAME answer for both: the main checkout owns the hook path. It used to be answered
+    // per scope — the project shim took the checkout, tree-scoped shims took whichever install happened to be
+    // running materialize — and the consequence was invisible and constant. A session's worktree is created by
+    // the BACKEND's install, so its shim named the checkout; the first commit inside that worktree runs
+    // pre-commit → materialize with the WORKTREE's install, which rewrote the same shim to name the branch.
+    // Every session therefore ran its opening turns on one toolchain and silently switched to another mid-flight,
+    // with no receipt anywhere. Neither half was wrong on its own; having two answers was.
+    //
+    // The main checkout is the right one, and for the reason the project shim already gave: a worktree's CLI may
+    // write its own tree-local artifacts but may never replace the shared hook owner. A session worktree is a
+    // DESK, not a toolchain install — it has no node_modules of its own, so a tree-pointing shim makes the very
+    // first hook of a fresh session try to build the branch. Governance is the product's, not the branch's.
+    const checkout = mainCheckout(proj);
+    retireLegacyCodexAnchors(checkout);
+    const projectDispatch = existsSync(join(checkout, 'spec-cli', 'hooks', 'dispatch.sh'))
+        ? join(checkout, 'spec-cli', 'hooks', 'dispatch.sh')
+        : DISPATCH;
+    const projectSpex = existsSync(join(checkout, 'spec-cli', 'bin', 'spex.mjs'))
+        ? join(checkout, 'spec-cli', 'bin', 'spex.mjs')
+        : SPEX;
+    const shimFor = (h) => h.shim(projectDispatch, projectSpex);
     const skillNodes = loadSkillConfig();
     const agentNodes = loadAgentConfig();
     const commandNodes = loadConfig();
@@ -297,19 +401,33 @@ export function materialize(proj = process.cwd()) {
             throw new Error(`conflicting materialize targets for ${path}`);
         targets.set(path, content);
     };
+    const addShimTarget = (targets, path, shim) => {
+        const prior = targets.get(path);
+        if (prior !== undefined && prior.content !== shim.content)
+            throw new Error(`conflicting materialize targets for ${path}`);
+        targets.set(path, shim);
+    };
     for (const h of selected) {
         if (contract)
             for (const f of h.contractFiles(proj))
                 addTarget(contractTargets, f, contract);
-        const shim = h.shim(DISPATCH, SPEX);
-        if (h.shimScope === 'tree') {
-            addTarget(treeShimTargets, h.shimFile(proj), shim.content);
-        }
+        const shim = shimFor(h);
+        // Codex discovers the root-checkout shim through this worktree anchor, but also parses the anchor as a
+        // project config layer. A second copy of our dispatcher therefore runs the same PreToolUse event twice.
+        // Keep the anchor present for layer discovery while leaving its hook set empty; the root checkout remains
+        // the sole executable hook owner.
+        // Claude reads project settings from the session's cwd only (measured on Claude Code 2.1.241: a hook
+        // configured solely in the main checkout never fires inside a nested linked worktree), so every tree
+        // carries its own tree-scoped shim; a session launched at the root fires the root's, never both. Its
+        // RESIDENCE is per-tree; its command paths are the main checkout's, exactly like the project shim's.
+        const target = { ownership: h.shimOwnership, content: shim.content, hooks: shim.hooks };
+        if (h.shimScope === 'tree')
+            addShimTarget(treeShimTargets, h.shimFile(proj), target);
         // a linked-worktree ANCHOR copy of the shim, when the harness needs one (codex: the shim lives at the main
         // checkout, so the worktree gets no `.codex/` unless we place one). One adapter line; null otherwise.
         const anchor = h.worktreeHookAnchor(proj);
         if (anchor)
-            addTarget(anchorTargets, anchor, shim.content);
+            addShimTarget(anchorTargets, anchor, { ownership: 'exclusive', content: '{\n  "hooks": {}\n}\n' });
     }
     for (const sk of skillNodes)
         for (const h of selected) {
@@ -351,42 +469,57 @@ export function materialize(proj = process.cwd()) {
         record('contract', file);
     }
     const contractPaths = [...contractTargets.keys()];
-    for (const [file, content] of treeShimTargets) {
+    // A shim file's residence is the SAME live content fact a contract file's is ([[residence]]): wholly ours →
+    // a machine fact hidden by the tree's ignore block, exactly as before; carrying the user's own content (or
+    // already tracked) → left VISIBLE, because hiding a file they own is data-loss shaped. A visible shim means
+    // our hook commands — absolute paths to THIS machine's toolchain — sit in a file they may commit, so say so.
+    const visibleShims = [];
+    for (const [file, shim] of [...treeShimTargets, ...anchorTargets]) {
         mkdirSync(dirname(file), { recursive: true });
-        writeFileIfChanged(file, content);
-        record('shim', file);
-        machinePaths.push(file);
-    }
-    for (const [file, content] of anchorTargets) {
-        mkdirSync(dirname(file), { recursive: true });
-        writeFileIfChanged(file, content);
+        if (!landShim(file, shim))
+            continue;
         record('shim', file);
-        machinePaths.push(file);
+        const theirs = shim.ownership === 'shared-json' && (isTrackedHere(file) || sharedShimHasHostContent(file));
+        if (theirs)
+            visibleShims.push(file);
+        else
+            machinePaths.push(file);
     }
+    if (visibleShims.length)
+        console.warn(`spexcode: ${visibleShims.map((f) => relative(proj, f)).join(', ')} carries your own configuration, so it stays visible to git — and it now also holds SpexCode's hook entries, whose commands are absolute paths to THIS machine's toolchain. Committing them would break the file for everyone else. Keep them out of your commits (each clone re-materializes its own), or adopt with "harnesses": [] and wire the hooks yourself.`);
     const selectedByDispatch = new Map(selected.map((h) => [h.dispatchId, h]));
     for (const h of selectedByDispatch.values()) {
-        const shim = h.shim(DISPATCH, SPEX);
+        const shim = shimFor(h);
         if (h.shimScope === 'project') {
             const file = h.shimFile(proj);
             mkdirSync(dirname(file), { recursive: true });
-            writeFileIfChanged(file, shim.content);
-            record('shim', file);
+            if (landShim(file, { ownership: h.shimOwnership, content: shim.content, hooks: shim.hooks }))
+                record('shim', file);
         }
         for (const file of h.writeTrust(proj, shim.cmd))
             record('trust', file);
     }
-    for (const [file, content] of skillTargets) {
-        mkdirSync(dirname(file), { recursive: true });
-        writeFileIfChanged(file, content);
-        artifactPaths.push(file);
-        record('skill', file);
-    }
-    for (const [file, content] of agentTargets) {
+    // A spec node named `distill` says WHICH path to write, never that the path is ours to take. An existing
+    // file with no GENERATED_MARK is the user's own same-named skill/agent — skip it and report the collision,
+    // the same identity gate the erase half has always applied. Skipped paths are NOT recorded and NOT excluded:
+    // the file is theirs in every respect, including how git sees it.
+    const collisions = [];
+    const plantGenerated = (kind, file, content) => {
+        if (!isGeneratedArtifact(file)) {
+            collisions.push(file);
+            return;
+        }
         mkdirSync(dirname(file), { recursive: true });
         writeFileIfChanged(file, content);
         artifactPaths.push(file);
-        record('agent', file);
-    }
+        record(kind, file);
+    };
+    for (const [file, content] of skillTargets)
+        plantGenerated('skill', file, content);
+    for (const [file, content] of agentTargets)
+        plantGenerated('agent', file, content);
+    if (collisions.length)
+        console.warn(`spexcode: left ${collisions.length} file(s) untouched — you already have a file at that name and it is not SpexCode-generated: ${collisions.map((f) => relative(proj, f)).join(', ')}. Rename the colliding .spec node (or your file) if you want the generated one delivered.`);
     // (8) the PLUGIN target ([[plugin-harness]]): materialize the whole system into one self-contained Claude-plugin
     //     bundle per selected folder. A plugin is EXCLUSIVE (`selected` is empty then). Pruning a DESELECTED
     //     folder needs the PREVIOUS folder set, which the live config no longer names — the one landing point
@@ -440,11 +573,19 @@ export function materialize(proj = process.cwd()) {
     const ignoreFile = join(proj, '.gitignore');
     const ignoreTracked = isTrackedHere(ignoreFile);
     const ignoreHost = existsSync(ignoreFile) ? stripSpexcodeBlock(readFileSync(ignoreFile, 'utf8'), ['# ', '']) : '';
-    if (!ignoreTracked && !ignoreHost.trim())
+    // the self-entry only earns its keep alongside a real one: with NOTHING selected ("harnesses": []) there is
+    // no artifact to hide, and a .gitignore whose whole content is a rule ignoring itself is pure footprint.
+    // An empty body then un-writes the block, taking a wholly-ours .gitignore with it.
+    if (localEntries.length && !ignoreTracked && !ignoreHost.trim())
         localEntries.push('.gitignore');
     const ignoreBody = entries(localEntries);
-    if (writeManagedBlock(ignoreFile, ignoreBody, ['# ', '']))
-        changedMaterialized.add(ignoreFile);
+    if (ignoreBody) {
+        if (writeManagedBlock(ignoreFile, ignoreBody, ['# ', '']))
+            changedMaterialized.add(ignoreFile);
+    }
+    else {
+        removeManagedBlock(ignoreFile, ['# ', ''], !ignoreTracked && !ignoreHost.trim());
+    }
     const payloads = filterContracts.map((file) => ({ file: relative(proj, file), content: contract }));
     if (ignoreTracked || ignoreHost.trim())
         payloads.push({ file: '.gitignore', content: ignoreBody });