spexcode 0.6.1 → 0.6.5

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

@@ -0,0 +1,468 @@
+import { writeFileSync, mkdirSync, readFileSync, existsSync, readdirSync, renameSync, rmSync, rmdirSync } from 'node:fs';
+import { join, dirname, relative } from 'node:path';
+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 { 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';
+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
+// CLI code and keeps the source-workspace mid-merge guard (one line + exit 75), so every hook callback
+// inherits both.
+const SPEX = join(PKG, 'bin', 'spex.mjs');
+// the manifest + content-hash marker + plugin-folder ledger land in the materialized TREE's own slot of the
+// GLOBAL per-project store (layout.treeSlotDir — trees/<enc-worktree>), NOT the worktree and NOT one shared
+// per-project file: each is a pure function of ONE tree's .plugins, and the old single slot let the last-
+// materialized tree's hook set reach every other tree's dispatch ([[hook-dispatch]]). The worktree keeps
+// zero SpexCode-materialized runtime; only the harness-discovered contract files + shims (which the harness
+// must find in-tree) are written under proj below.
+// the deterministic content fingerprint of the config roots + THE TOOLCHAIN ITSELF (`hp_config_hash` in the
+// shell mirror, harness.sh). Stamped as a freshness record after every materialize; it folds in
+// hp_toolchain_version (the toolchain-side content hash), so a stale stamp is diagnosable after a toolchain
+// update ([[harness-delivery]]).
+export function contentHash(proj) {
+    try {
+        const harnessSh = join(PKG, 'hooks', 'harness.sh');
+        const gitDir = dirname(gitBinary(process.env));
+        const env = { ...process.env, PATH: `${gitDir}:${process.env.PATH || ''}` };
+        return execFileSync('bash', ['-c', `cd "${proj}" && . "${harnessSh}" && hp_config_hash`], { env }).toString().trim();
+    }
+    catch {
+        return '';
+    }
+}
+export function retiredAxisNotice(cfg) {
+    if (!cfg.render?.trim() && !cfg.private)
+        return;
+    const field = cfg.render?.trim() ? `"render": "${cfg.render.trim()}"` : '"private": true';
+    console.error(`spexcode: the render vote is retired — ${field} is ignored. Materialized artifacts are never tracked:\n` +
+        `  tree-local ignore rules live in a filtered working .gitignore, and a host-tracked contract is covered by the\n` +
+        `  clean/smudge filter, and a clone without spex runs \`spex materialize\` in its setup step. Remove the\n` +
+        `  field from spexcode.json / spexcode.local.json to retire this notice (see \`spex guide footprint\`).`);
+}
+function gitCommonDirOf(proj) {
+    return git(['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim();
+}
+function infoExcludePath(proj) {
+    return join(gitCommonDirOf(proj), 'info', 'exclude');
+}
+function isTracked(proj, file) {
+    try {
+        git(['-C', proj, 'ls-files', '--error-unmatch', file]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function clearSkipWorktree(proj, file) {
+    if (!isTracked(proj, file))
+        return;
+    try {
+        git(['-C', proj, 'update-index', '--no-skip-worktree', file]);
+    }
+    catch { }
+}
+function registeredTrees(proj) {
+    const rows = git(['-C', mainCheckout(proj), 'worktree', 'list', '--porcelain', '-z']).split('\0');
+    return rows.filter((row) => row.startsWith('worktree ')).map((row) => row.slice('worktree '.length));
+}
+function selectionBody(selected, plugin = false) {
+    return [...new Set([...selected.map((h) => h.dispatchId), ...(plugin ? ['plugin'] : [])])].sort().join('\n') + '\n';
+}
+function publishSelection(path, body) {
+    try {
+        if (readFileSync(path, 'utf8') === body)
+            return;
+    }
+    catch (error) {
+        if (error?.code !== 'ENOENT')
+            throw error;
+    }
+    const prepared = `${path}.${process.pid}.tmp`;
+    writeFileSync(prepared, body);
+    renameSync(prepared, path);
+}
+function managedBlockPattern(comment) {
+    const [open, close] = comment;
+    const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`\\n*${escape(`${open}spexcode:start${close}`)}[\\s\\S]*?${escape(`${open}spexcode:end${close}`)}\\n*`);
+}
+export function stripSpexcodeBlock(text, comment = ['<!-- ', ' -->']) {
+    const sentinel = managedBlockPattern(comment);
+    const m = sentinel.exec(text);
+    if (!m)
+        return text;
+    // mirror removeManagedBlock exactly: our block + its surrounding blanks collapse to one '\n', and only a
+    // block sitting at the TOP of the file drops the leading newline (a host file beginning with its own
+    // blank lines keeps them — clean(smudge(x)) == x).
+    const replaced = text.replace(sentinel, '\n');
+    return m.index === 0 ? replaced.replace(/^\n+/, '') : replaced;
+}
+function hostContentOf(file) {
+    if (!existsSync(file))
+        return '';
+    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 -->';
+function pruneGeneratedSkills(dir, keep) {
+    if (!dir || !existsSync(dir))
+        return false;
+    let changed = false;
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+        if (!e.isDirectory())
+            continue;
+        const f = join(dir, e.name, 'SKILL.md');
+        try {
+            if (!keep.has(e.name) && existsSync(f) && readFileSync(f, 'utf8').includes(GENERATED_MARK)) {
+                rmSync(join(dir, e.name), { recursive: true, force: true });
+                changed = true;
+            }
+        }
+        catch { /* unreadable → not provably ours */ }
+    }
+    return changed;
+}
+function pruneGeneratedAgents(dir, keep) {
+    if (!dir || !existsSync(dir))
+        return false;
+    let changed = false;
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+        if (!e.isFile() || !e.name.endsWith('.md'))
+            continue;
+        const f = join(dir, e.name);
+        try {
+            if (!keep.has(e.name.slice(0, -3)) && readFileSync(f, 'utf8').includes(GENERATED_MARK)) {
+                rmSync(f, { force: true });
+                changed = true;
+            }
+        }
+        catch { /* unreadable → not provably ours */ }
+    }
+    return changed;
+}
+function cleanupHarnessDirs(proj) {
+    const roots = new Set([proj, mainCheckout(proj)]);
+    const dirs = HARNESSES.flatMap((h) => {
+        const anchor = h.worktreeHookAnchor(proj);
+        return [h.skillDir(proj), h.agentDir(proj), dirname(h.shimFile(proj)), anchor ? dirname(anchor) : null];
+    }).filter((d) => !!d);
+    for (const d of [...new Set([...dirs, ...dirs.map((dir) => dirname(dir))])]
+        .filter((dir) => !roots.has(dir)).sort((a, b) => b.length - a.length)) {
+        try {
+            rmdirSync(d);
+        }
+        catch { }
+    }
+}
+function reconcileTree(proj, targets, tracked) {
+    let removed = false;
+    const contractFiles = new Set(HARNESSES.flatMap((h) => h.contractFiles(proj)));
+    for (const file of contractFiles) {
+        if (targets.contracts.has(file) || !existsSync(file))
+            continue;
+        const text = readFileSync(file, 'utf8');
+        if (!text.includes('<!-- spexcode:start -->'))
+            continue;
+        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]) {
+        if (targets.treeShims.has(file) || targets.anchors.has(file) || !existsSync(file))
+            continue;
+        if (readFileSync(file, 'utf8').includes('dispatch.sh')) {
+            rmSync(file, { force: true });
+            removed = true;
+        }
+    }
+    for (const dir of new Set(HARNESSES.map((h) => h.skillDir(proj)).filter((path) => !!path)))
+        removed = pruneGeneratedSkills(dir, targets.skills.get(dir) ?? new Set()) || removed;
+    for (const dir of new Set(HARNESSES.map((h) => h.agentDir(proj)).filter((path) => !!path)))
+        removed = pruneGeneratedAgents(dir, targets.agents.get(dir) ?? new Set()) || removed;
+    if (removed)
+        cleanupHarnessDirs(proj);
+}
+function eraseTree(proj, arts, preserveProject) {
+    for (const h of HARNESSES) {
+        // h.clean = the adapter's surgical inverse: contract block (sentinels, deleteIfEmpty), the dispatch.sh-
+        // stamped shim + worktree anchor, the trust block, and the arts-named skill/agent files.
+        h.clean(proj, arts, preserveProject);
+        for (const f of h.contractFiles(proj))
+            clearSkipWorktree(proj, f);
+        pruneGeneratedSkills(h.skillDir(proj), new Set());
+        pruneGeneratedAgents(h.agentDir(proj), new Set());
+    }
+    // same authorship rule as the contract files: deleteIfEmpty only when .gitignore is UNTRACKED (wholly-ours
+    // generated file); a HOST-TRACKED .gitignore that carried nothing but our block is stripped, never deleted.
+    removeManagedBlock(join(proj, '.gitignore'), ['# ', ''], !isTracked(proj, '.gitignore'));
+    clearContractFilterPayload(proj, [...HARNESSES.flatMap((h) => h.contractFiles(proj)), join(proj, '.gitignore')]);
+    // the block-strip left tracked contract files stat-dirty (under a filter git NEVER content-verifies them,
+    // and even unfiltered the phantom-`M` lingers) — settle the index stat, content-guarded so a user's real
+    // unstaged edit is never staged ([[content-filter]] edge 2).
+    try {
+        settleIndexStat(proj, HARNESSES.flatMap((h) => h.contractFiles(proj)));
+    }
+    catch { /* not a git repo */ }
+    // leaving nothing behind: drop the now-EMPTY dirs the assert phase mkdir'ed (.claude/.codex/.opencode/.pi
+    // and their skills/agents/plugins/extensions subdirs). Each dir AND its parent are swept deepest-first,
+    // because a harness may nest its shim a level below its home (opencode's .opencode/plugins/, pi's
+    // .pi/extensions/) — but never the checkout roots themselves. rmdirSync is NON-recursive, so a dir holding
+    // any user file survives untouched; `.git/spexcode/` is deliberately NOT swept (shared per-clone home).
+    cleanupHarnessDirs(proj);
+}
+export function dematerialize(proj = process.cwd(), arts = { skills: [], agents: [] }) {
+    const trees = registeredTrees(proj);
+    const current = git(['-C', proj, 'rev-parse', '--show-toplevel']).trim();
+    for (const tree of trees) {
+        if (!existsSync(tree))
+            throw new Error(`cannot dematerialize project while registered worktree ${tree} is inaccessible — repair or remove/prune it first`);
+        git(['-C', tree, 'rev-parse', '--show-toplevel']);
+    }
+    for (const tree of trees) {
+        // Only the caller's live spec may widen the name sweep. Siblings are identity-stamp-only: the
+        // same name there may be user-owned or may not exist in this tree's divergent spec at all.
+        eraseTree(tree, tree === current ? arts : { skills: [], agents: [] }, false);
+    }
+    try {
+        removeManagedBlock(infoExcludePath(proj), ['# ', ''], false);
+    }
+    catch { /* not a git repo */ }
+    removeContractFilter(proj, [...HARNESSES.flatMap((h) => h.contractFiles(proj)), join(proj, '.gitignore')], true);
+}
+// the whole pay-per-change materialize. proj defaults to cwd. Its receipt is populated at each successful
+// write so callers report the actual selected footprint instead of maintaining a second artifact inventory.
+export function materialize(proj = process.cwd()) {
+    const rt = treeSlotDir(proj); // this tree's slot in the global store, not the worktree
+    mkdirSync(rt, { recursive: true });
+    const planted = [];
+    const record = (kind, path) => {
+        if (!planted.some((a) => a.kind === kind && a.path === path))
+            planted.push({ kind, path });
+    };
+    // (1) hook manifest (persistent — the dispatcher reads it; regenerated only here, on change).
+    const manifest = join(rt, 'hooks-manifest');
+    writeFileIfChanged(manifest, compileManifest());
+    record('hook manifest', manifest);
+    // (2) the contract = the surface:system plugin bodies (in name order), written WHOLE into EACH harness's
+    //     contract file(s) + (3) each harness's thin shim → dispatch.sh + (4) its trust. All owned by the adapter.
+    // ONE source, no per-project escape hatch: the contract IS the surface:system plugin bodies. A project's
+    // own hand-written prose is not folded in — repo-local notes belong in the harness file's own
+    // block-outside region (untracked, per-clone), and anything that must reach EVERY agent is a plugin node.
+    const contract = loadSystemConfig().map((c) => c.body.trim()).filter(Boolean).join('\n\n');
+    // WHICH harnesses to deliver into ([[harness-select]]): this tree's explicit spexcode.json `harnesses` set.
+    // resolveHarnessTargets FAILS LOUD on an illegal set (plugin+native, plugin w/o folder).
+    const cfg = readConfig(proj);
+    const targets = resolveHarnessTargets(cfg.harnesses);
+    retiredAxisNotice(cfg); // [[residence]] — the vote axis is retired
+    const { selected, plugins } = partitionHarnesses(targets);
+    const skillNodes = loadSkillConfig();
+    const agentNodes = loadAgentConfig();
+    const commandNodes = loadConfig();
+    // a skill node → the agentskills.io SKILL.md primitive: `name`+`description` frontmatter (the load-trigger)
+    // over the body instructions, closed by the GENERATED_MARK identity stamp (what the erase phase keys on).
+    // One pure artifact builder shared by every harness — divergence is only its skillDir.
+    const skillArtifact = (sk) => `---\nname: ${sk.name}\ndescription: ${JSON.stringify(sk.desc)}\n---\n\n${sk.body}\n\n${GENERATED_MARK}\n`;
+    // an agent node → a coding-agent sub-agent definition (the same primitive .claude/agents/*.md ships): the
+    // node's `desc` is the on-demand load-trigger, its `tools` the harness tool allowlist, its body the agent's
+    // system prompt. Same stamp, same reason.
+    const agentArtifact = (ag) => `---\nname: ${ag.name}\ndescription: ${ag.desc}\ntools: ${ag.tools.join(', ')}\n---\n\n${ag.body}\n\n${GENERATED_MARK}\n`;
+    // a command node → a host `/`-menu command file: plugin-only (the native path serves command presets via
+    // the dashboard /api/slash-commands instead).
+    const commandArtifact = (cm) => (cm.desc ? `---\ndescription: ${JSON.stringify(cm.desc)}\n---\n\n` : '') + `${cm.body}\n`;
+    // materialized artifacts and machine facts both land in the same per-clone exclude; contract files are kept separate
+    // because their residence is the live three-state kind detection below, not a static entry.
+    const artifactPaths = [];
+    const machinePaths = [];
+    const contractTargets = new Map();
+    const treeShimTargets = new Map();
+    const anchorTargets = new Map();
+    const skillTargets = new Map();
+    const agentTargets = new Map();
+    const skillsByDir = new Map();
+    const agentsByDir = new Map();
+    const addTarget = (targets, path, content) => {
+        const prior = targets.get(path);
+        if (prior !== undefined && prior !== content)
+            throw new Error(`conflicting materialize targets for ${path}`);
+        targets.set(path, content);
+    };
+    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);
+        }
+        // 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);
+    }
+    for (const sk of skillNodes)
+        for (const h of selected) {
+            const dir = h.skillDir(proj);
+            if (!dir)
+                continue;
+            addTarget(skillTargets, join(dir, sk.name, 'SKILL.md'), skillArtifact(sk));
+            const names = skillsByDir.get(dir) ?? new Set();
+            names.add(sk.name);
+            skillsByDir.set(dir, names);
+        }
+    for (const ag of agentNodes)
+        for (const h of selected) {
+            const dir = h.agentDir(proj);
+            if (!dir)
+                continue;
+            addTarget(agentTargets, join(dir, `${ag.name}.md`), agentArtifact(ag));
+            const names = agentsByDir.get(dir) ?? new Set();
+            names.add(ag.name);
+            agentsByDir.set(dir, names);
+        }
+    const tracked = new Map();
+    const isTrackedHere = (file) => {
+        const known = tracked.get(file);
+        if (known !== undefined)
+            return known;
+        const value = isTracked(proj, file);
+        tracked.set(file, value);
+        return value;
+    };
+    reconcileTree(proj, {
+        contracts: new Set(contractTargets.keys()), treeShims: new Set(treeShimTargets.keys()), anchors: new Set(anchorTargets.keys()),
+        skills: skillsByDir, agents: agentsByDir,
+    }, isTrackedHere);
+    const changedMaterialized = new Set();
+    for (const [file, content] of contractTargets) {
+        if (writeManagedBlock(file, content))
+            changedMaterialized.add(file);
+        record('contract', file);
+    }
+    const contractPaths = [...contractTargets.keys()];
+    for (const [file, content] of treeShimTargets) {
+        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);
+        record('shim', file);
+        machinePaths.push(file);
+    }
+    const selectedByDispatch = new Map(selected.map((h) => [h.dispatchId, h]));
+    for (const h of selectedByDispatch.values()) {
+        const shim = h.shim(DISPATCH, SPEX);
+        if (h.shimScope === 'project') {
+            const file = h.shimFile(proj);
+            mkdirSync(dirname(file), { recursive: true });
+            writeFileIfChanged(file, shim.content);
+            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) {
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileIfChanged(file, content);
+        artifactPaths.push(file);
+        record('agent', file);
+    }
+    // (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
+    //     the identity-stamped erase cannot enumerate (a folder is an arbitrary path) — so a tiny ledger in the
+    //     global store records the folders emitted last run; any prev folder absent from the current set is
+    //     clean()ed, then the current folders are emitted and the ledger rewritten.
+    const ledger = join(rt, 'plugin-folders');
+    const prevFolders = existsSync(ledger) ? readFileSync(ledger, 'utf8').split('\n').map((l) => l.trim()).filter(Boolean) : [];
+    const curFolders = plugins.map((p) => p.folder);
+    for (const f of prevFolders)
+        if (!curFolders.includes(f))
+            cleanPlugin(proj, f);
+    if (plugins.length) {
+        const bundle = {
+            contract,
+            skills: skillNodes.map((s) => ({ name: s.name, content: skillArtifact(s) })),
+            agents: agentNodes.map((a) => ({ name: a.name, content: agentArtifact(a) })),
+            commands: commandNodes.map((c) => ({ name: c.name, content: commandArtifact(c) })),
+            spex: SPEX,
+            version: pluginVersion(),
+        };
+        for (const p of plugins) {
+            emitPlugin(proj, p.folder, bundle);
+            record('plugin bundle', pluginBundleDir(proj, p.folder));
+        }
+    }
+    writeFileIfChanged(ledger, curFolders.join('\n'));
+    // (9) ignore + mixed text. Only checkout-invariant residue and project-shared shims belong in the COMMON
+    // info/exclude; selection-dependent paths live in this tree's filtered working .gitignore.
+    const mc = mainCheckout(proj);
+    const bundlePaths = curFolders.map((f) => pluginBundleDir(proj, f));
+    const commonEntries = [
+        ...[...new Set(HARNESSES.filter((h) => h.shimScope === 'project' && existsSync(h.shimFile(proj)) &&
+                readFileSync(h.shimFile(proj), 'utf8').includes('dispatch.sh')).map((h) => relative(mc, h.shimFile(proj))))]
+            .filter((p) => !p.startsWith('..')),
+        'spexcode.local.json', '.worktrees/', '.session',
+    ];
+    const entries = (list) => [...new Set(list)].sort().join('\n');
+    // Contract residence stays a live fact. Selection-dependent untracked products are ignored by this tree's
+    // working .gitignore, whose own managed block is filtered when the host tracks/owns that file.
+    const filterContracts = [];
+    const oursContracts = [];
+    for (const f of contractPaths) {
+        if (isTrackedHere(f) || hostContentOf(f).trim())
+            filterContracts.push(f);
+        else
+            oursContracts.push(f);
+    }
+    const localEntries = [...machinePaths, ...bundlePaths, ...artifactPaths, ...oursContracts]
+        .map((p) => relative(proj, p)).filter((p) => !p.startsWith('..'));
+    const ignoreFile = join(proj, '.gitignore');
+    const ignoreTracked = isTrackedHere(ignoreFile);
+    const ignoreHost = existsSync(ignoreFile) ? stripSpexcodeBlock(readFileSync(ignoreFile, 'utf8'), ['# ', '']) : '';
+    if (!ignoreTracked && !ignoreHost.trim())
+        localEntries.push('.gitignore');
+    const ignoreBody = entries(localEntries);
+    if (writeManagedBlock(ignoreFile, ignoreBody, ['# ', '']))
+        changedMaterialized.add(ignoreFile);
+    const payloads = filterContracts.map((file) => ({ file: relative(proj, file), content: contract }));
+    if (ignoreTracked || ignoreHost.trim())
+        payloads.push({ file: '.gitignore', content: ignoreBody });
+    const bindings = [
+        ...[...new Set(HARNESSES.flatMap((h) => h.contractFiles(proj).map((file) => relative(proj, file))))]
+            .map((file) => ({ file, start: '<!-- spexcode:start -->', end: '<!-- spexcode:end -->' })),
+        { file: '.gitignore', start: '# spexcode:start', end: '# spexcode:end' },
+    ];
+    if (payloads.length)
+        plantContractFilter(proj, payloads, bindings, [...changedMaterialized]);
+    else if (contractFilterPlanted(proj))
+        removeContractFilter(proj, [...HARNESSES.flatMap((h) => h.contractFiles(proj)), join(proj, '.gitignore')]);
+    // (5) finish diagnostics, then atomically publish the allowlist LAST. Dispatch consumes only that
+    // final receipt; a killed writer leaves the preceding successful selection intact.
+    const h = contentHash(proj);
+    writeFileIfChanged(join(rt, 'content-hash'), h);
+    writeFileIfChanged(join(runtimeRoot(proj), 'harness-selection-v1'), '');
+    writeManagedBlock(infoExcludePath(proj), entries(commonEntries), ['# ', '']);
+    publishSelection(join(rt, 'harnesses'), selectionBody(selected, plugins.length > 0));
+    return { contentHash: h, planted };
+}

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

@@ -0,0 +1,50 @@
+export declare function stripRefSigil(token: string): string;
+export declare function parseMentions(text: string): {
+    sessions: string[];
+    nodes: string[];
+};
+export type DispatchOutcome = {
+    token: string;
+    result: 'spawned' | 'failed';
+    detail?: string;
+    note?: string;
+};
+export type NewDispatchContext = {
+    threadId: string;
+    node: string | null;
+    author: string;
+    status?: string | null;
+} | {
+    sessionId: string;
+};
+export declare function spawnParent(author: string, sessions: {
+    id: string;
+}[]): string | null;
+export declare function newWorkerPrompt(threadId: string, node: string | null, author: string, text: string, status?: string | null): string;
+export declare function commandWorkerPrompt(sessionId: string, text: string): string;
+export declare function dispatchNewMentions(text: string, ctx: NewDispatchContext): Promise<DispatchOutcome[]>;
+export declare const summarizeDispatch: (outcomes: DispatchOutcome[]) => string;
+type Session = {
+    id: string;
+    node: string | null;
+    name: string | null;
+    title: string | null;
+    liveness: string;
+};
+export type LoopIn = {
+    originator: string;
+};
+export type LoopInPick = {
+    kind: 'deliver';
+    originator: string;
+    session: Session;
+} | {
+    kind: 'none';
+};
+export declare function pickLoopIn(chain: (string | null)[], replier: string, sessions: Session[]): LoopInPick;
+export declare function notifyOriginator(chain: (string | null)[], replier: string, text: string, ctx: {
+    threadId: string;
+    node: string | null;
+}): Promise<LoopIn | null>;
+export declare const summarizeLoopIn: (loopIn?: LoopIn | null) => string;
+export {};

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

@@ -0,0 +1,117 @@
+// @@@ mentions - the shared in-text grammar: `[[node]]` and `@session` are references;
+// the exact @new token is the durable worker-creation action. Its dispatcher stays here
+// so every composer reaches the same creation owner after its own write has committed.
+const SESSION_RE = /(?:^|\s)@([\p{L}\p{N}_-]+(?::[\p{L}\p{N}_.-]+)?)/gu;
+const NODE_RE = /\[\[([^\]\s]+)\]\]/g;
+const uniq = (xs) => [...new Set(xs)];
+// In free text a sigil separates a reference from prose. A CLI argument is already a
+// reference, so it tolerates either sigil without widening its normal matching grammar.
+export function stripRefSigil(token) {
+    const wrapped = /^\[\[(.*)\]\]$/.exec(token);
+    if (wrapped)
+        return wrapped[1];
+    return token.startsWith('@') ? token.slice(1) : token;
+}
+export function parseMentions(text) {
+    const sessions = [];
+    const nodes = [];
+    for (const m of text.matchAll(SESSION_RE))
+        sessions.push(m[1]);
+    for (const m of text.matchAll(NODE_RE))
+        nodes.push(m[1]);
+    return { sessions: uniq(sessions), nodes: uniq(nodes) };
+}
+export function spawnParent(author, sessions) {
+    return sessions.some((session) => session.id === author) ? author : null;
+}
+export function newWorkerPrompt(threadId, node, author, text, status) {
+    const scope = node ? ` on node [[${node}]]` : '';
+    const settled = status && status !== 'open'
+        ? `NOTE: this thread is already resolved (status: ${status}). Verify main first; if it already satisfies the thread, report that finding instead of re-implementing.\n\n`
+        : '';
+    return `Issue thread "${threadId}"${scope} @-mentioned @new (by ${author}) for a fresh look:\n\n  ${text.trim()}\n\n` +
+        settled +
+        `Read the thread (\`spex issue ls --all\`, find ${threadId}) and act on it${node ? `; the relevant node is ${node}` : ''}.`;
+}
+export function commandWorkerPrompt(sessionId, text) {
+    return `Session "${sessionId}" opened a child worker from its Command Box:\n\n${text.trim()}`;
+}
+// Writes call this only after their durable append/commit succeeds. @session deliberately remains absent:
+// sending to an existing session is still the explicit `spex session send` operation.
+export async function dispatchNewMentions(text, ctx) {
+    const tokens = parseMentions(text).sessions;
+    const requested = tokens.flatMap((token) => {
+        const match = /^new(?::([\p{L}\p{N}_.-]+))?$/u.exec(token);
+        return match ? [{ token, launcher: match[1] }] : [];
+    });
+    if (!requested.length)
+        return [];
+    const { listSessions, sessionCreateRequest } = await import('./sessions.js');
+    const sessions = await listSessions();
+    const command = 'sessionId' in ctx;
+    const author = command ? ctx.sessionId : ctx.author;
+    const outcomes = [];
+    for (const request of requested) {
+        const settled = !command && ctx.status && ctx.status !== 'open' ? ctx.status : undefined;
+        try {
+            const created = await sessionCreateRequest({
+                prompt: command
+                    ? commandWorkerPrompt(ctx.sessionId, text)
+                    : newWorkerPrompt(ctx.threadId, ctx.node, ctx.author, text, ctx.status),
+                parent: spawnParent(author, sessions),
+                launcher: request.launcher,
+            });
+            if (created.status !== 201)
+                throw new Error(`${created.code || 'session_create_failed'}: ${created.error}`);
+            outcomes.push({ token: request.token, result: 'spawned', detail: created.session.id, ...(settled ? { note: `thread ${settled}` } : {}) });
+        }
+        catch (error) {
+            outcomes.push({ token: request.token, result: 'failed', detail: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return outcomes;
+}
+export const summarizeDispatch = (outcomes) => outcomes.length ? '@ ' + outcomes.map((outcome) => outcome.result === 'spawned'
+    ? `${outcome.token}->${outcome.detail}${outcome.note ? ` (${outcome.note})` : ''}`
+    : `${outcome.token}->failed (${outcome.detail})`).join('  |  ') : '';
+function resolveOnlineSession(token, sessions) {
+    const online = sessions.filter((session) => session.liveness === 'online');
+    const text = token.toLowerCase();
+    const label = (session) => (session.name || session.title || '').toLowerCase();
+    return online.find((session) => session.id === token)
+        || online.find((session) => session.id.startsWith(token))
+        || online.find((session) => label(session) === text)
+        || online.find((session) => label(session).startsWith(text) && text.length >= 2)
+        || null;
+}
+// A committed reply can notify its originator as a courtesy. This is not a mention
+// dispatch or assignment, and it never creates a worker or retries an offline session.
+export function pickLoopIn(chain, replier, sessions) {
+    const seen = new Set();
+    for (const originator of chain) {
+        if (!originator || originator === replier || seen.has(originator))
+            continue;
+        seen.add(originator);
+        const session = resolveOnlineSession(originator, sessions);
+        if (session)
+            return { kind: 'deliver', originator, session };
+    }
+    return { kind: 'none' };
+}
+function originatorPrompt(threadId, node, replier, text) {
+    const re = node ? ` (re: ${node})` : '';
+    return `A new reply landed on a thread you originated - "${threadId}"${re}, from ${replier}:\n\n  ${text.trim()}\n\n` +
+        `This is a courtesy heads-up, not an assignment. Look if it concerns you; ` +
+        `\`spex issue ls --all\` lists threads and \`spex issue reply ${threadId} --body -\` replies.`;
+}
+export async function notifyOriginator(chain, replier, text, ctx) {
+    if (!chain.some((candidate) => candidate && candidate !== replier))
+        return null;
+    const { sendText, listSessions } = await import('./sessions.js');
+    const pick = pickLoopIn(chain, replier, await listSessions());
+    if (pick.kind !== 'deliver')
+        return null;
+    const result = await sendText(pick.session.id, originatorPrompt(ctx.threadId, ctx.node, replier, text), 'issues');
+    return result.ok ? { originator: pick.originator } : null;
+}
+export const summarizeLoopIn = (loopIn) => loopIn ? `looped in originator @${loopIn.originator} (online)` : '';

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

@@ -0,0 +1,4 @@
+import { type DispatchResult, type HarnessDeliveryRecord } from './harness.js';
+export declare function opencodeHeadlessLaunchCommand(opencodeCmd?: string): string;
+export declare function opencodeHeadlessWakeCommand(opencodeCmd: string, harnessSessionId: string | null | undefined, text: string, outcomePath?: string): string;
+export declare function spawnOpenCodeHeadlessTurn(rec: HarnessDeliveryRecord, text: string, opencodeCmd: string, socketPath: string): Promise<DispatchResult>;