@spexcode/spec-cli 0.6.5

package/dist/commit-surgery.d.ts

@@ -0,0 +1 @@
+export declare function commitSurgery(proj?: string): void;

package/dist/commit-surgery.js

@@ -0,0 +1,90 @@
+import { execFileSync } from 'node:child_process';
+import { relative } from 'node:path';
+import { materialize, stripSpexcodeBlock, GENERATED_MARK } from './materialize.js';
+import { HARNESSES } from './harness.js';
+import { gitBinary } from '@spexcode/spec-core';
+// GIT ENV, deliberately INVERTED from git.ts's git(): every call here PRESERVES the hook's environment —
+// GIT_INDEX_FILE must be honored so the surgery reads/writes the EXACT index this commit is being built
+// from (a `git commit <path>` pathspec commit and `git commit -a` both run hooks against a TEMPORARY index;
+// operating on the real one would silently miss them). git.ts strips that env for repo DISCOVERY reasons;
+// index surgery is the one place the env is the point.
+const raw = (args, input) => execFileSync(gitBinary(process.env), args, { input, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+function inHead(p) {
+    try {
+        raw(['cat-file', '-e', `HEAD:${p}`]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function stagedBlob(p) {
+    try {
+        return raw(['show', `:${p}`]);
+    }
+    catch {
+        return null;
+    }
+}
+function evict(p, why) {
+    raw(['update-index', '--force-remove', '--', p]);
+    console.error(`spexcode: unstaged ${p} (${why} — generated artifacts are never tracked; the file stays on disk)`);
+}
+function replaceBlob(p, content) {
+    const stage = raw(['ls-files', '--stage', '--', p]).trim(); // "100644 <sha> 0\t<p>"
+    const mode = stage.split(/\s/)[0] || '100644';
+    const sha = raw(['hash-object', '-w', '--stdin'], content).trim();
+    raw(['update-index', '--cacheinfo', `${mode},${sha},${p}`]);
+    console.error(`spexcode: stripped the <!-- spexcode --> block from staged ${p} (the block is working-tree context, never history)`);
+}
+export function commitSurgery(proj = process.cwd()) {
+    // (1) unconditional materialize — machine-fixable state (exclude entries, filter binding, kind flips)
+    // is repaired BEFORE the index is inspected, so the inspection below judges against fresh masks.
+    try {
+        materialize(proj);
+    }
+    catch (e) {
+        console.error(`spexcode: pre-commit materialize failed (${e.message}) — footprint may be stale this commit`);
+    }
+    const staged = raw(['diff', '--cached', '--name-only', '-z']).split('\0').filter(Boolean);
+    if (!staged.length)
+        return;
+    const rel = (f) => relative(proj, f);
+    const contracts = new Set(HARNESSES.flatMap((h) => h.contractFiles(proj)).map(rel));
+    const machine = new Set(['spexcode.local.json', '.session']);
+    for (const h of HARNESSES) {
+        machine.add(rel(h.shimFile(proj)));
+        const a = h.worktreeHookAnchor(proj);
+        if (a)
+            machine.add(rel(a));
+    }
+    const generatedDirs = HARNESSES.flatMap((h) => [h.skillDir(proj), h.agentDir(proj)])
+        .filter((d) => !!d).map((d) => `${rel(d)}/`);
+    for (const p of staged) {
+        if (contracts.has(p)) {
+            const blob = stagedBlob(p);
+            if (blob === null)
+                continue;
+            const stripped = stripSpexcodeBlock(blob);
+            if (stripped === blob)
+                continue; // no block staged — clean already did its job
+            if (!stripped.trim() && !inHead(p))
+                evict(p, 'wholly a spexcode materialized artifact');
+            else
+                replaceBlob(p, stripped);
+        }
+        else if (machine.has(p) || p.startsWith('.worktrees/')) {
+            if (!inHead(p))
+                evict(p, 'a machine-local spexcode file');
+            else
+                console.error(`spexcode: ${p} is a machine-local spexcode file but HEAD already tracks it — not touching a tracked file; untrack it yourself (git rm --cached ${p})`);
+        }
+        else if (generatedDirs.some((d) => p.startsWith(d))) {
+            if (inHead(p))
+                continue; // historically tracked — the host's call
+            const blob = stagedBlob(p);
+            if (blob !== null && blob.includes(GENERATED_MARK))
+                evict(p, 'a generated skill/agent artifact');
+        }
+    }
+}

package/dist/contract-filter.d.ts

@@ -0,0 +1,14 @@
+export type ContractFilterPayload = {
+    file: string;
+    content: string;
+};
+export type ContractFilterBinding = {
+    file: string;
+    start: string;
+    end: string;
+};
+export declare function plantContractFilter(proj: string, payloads: ContractFilterPayload[], bindings: ContractFilterBinding[], changedFiles?: readonly string[]): boolean;
+export declare function settleIndexStat(proj: string, files: string[]): void;
+export declare function clearContractFilterPayload(proj: string, files?: string[]): void;
+export declare function removeContractFilter(proj: string, files?: string[], final?: boolean): void;
+export declare function contractFilterPlanted(proj: string): boolean;

package/dist/contract-filter.js

@@ -0,0 +1,219 @@
+import { mkdirSync, readFileSync, rmSync, chmodSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { git, gitBinary } from '@spexcode/spec-core';
+import { writeManagedBlock, removeManagedBlock } from './harness.js';
+import { encodeProject, runtimeRoot, treeSlotDir } from '@spexcode/spec-core';
+import { writeFileIfChanged } from './file-write.js';
+// the three field-sharpened edges this module owes ([[content-filter]]):
+//   ① the configured command points at a STABLE shim path and degrades to `cat` (identity) when the shim is
+//     missing — a bare missing filter command makes git spray "cannot fork" fatals on EVERY operation;
+//   ② a changed contract does NOT propagate by itself (git re-smudges only on checkout) — materialize's
+//     re-materialize writes the managed block straight into the working file (writeManagedBlock IS the re-smudge),
+//     and this module refreshes the block file the shim reads so future checkouts agree;
+//   ③ unplanting must strip the block from the WORKING FILES before the config goes away, or the block
+//     residue surfaces as an uncommitted modification — the caller (dematerialize) removes the managed
+//     blocks first and only then calls removeContractFilter.
+function commonDirOf(proj) {
+    return git(['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim();
+}
+const filterDir = (common) => join(common, 'spexcode');
+const shimPath = (common) => join(filterDir(common), 'contract-filter.sh');
+const rootPath = (common) => join(filterDir(common), 'contract-filter-root');
+const bindingsPath = (common) => join(filterDir(common), 'contract-filter-bindings');
+const treeFilterDir = (proj) => join(treeSlotDir(proj), 'contract-filter');
+const attributesPath = (common) => join(common, 'info', 'attributes');
+// The common shim both filter directions run through. Pure shell/awk (no node boot on git's hot path), it
+// resolves the invoking checkout to that tree's payload before mirroring managed-block normalization:
+//   clean : drop the sentinel block (+ the blank line smudge printed before it) → the pristine host prose.
+//   smudge: clean first (a block already in the index can never double-inject), then append the tree payload.
+// Byte-exactness holds for text ending in exactly one newline (git's own well-formed-text shape); a pristine
+// file ending in zero or 2+ newlines is normalized to one on the first round-trip and stable after.
+const SHIM = `#!/usr/bin/env bash
+# spexcode managed-text filter (generated by spex materialize; see [[content-filter]]).
+# One common driver selects the payload belonging to the Git checkout that invoked it.
+set -u
+mode="\${1:?usage: contract-filter.sh smudge|clean <path>}"
+path="\${2:?usage: contract-filter.sh smudge|clean <path>}"
+here="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+binding="$(awk -F '\t' -v p="$path" '$1 == p { print $2 "\t" $3; exit }' "$here/contract-filter-bindings" 2>/dev/null)"
+[ -n "$binding" ] || { cat; exit 0; }
+start="\${binding%%$'\t'*}"; rest="\${binding#*$'\t'}"
+end="$rest"
+top="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+root="$(cat "$here/contract-filter-root" 2>/dev/null || true)"
+key="$(printf '%s' "$top" | sed 's#[/.]#-#g')"
+manifest="$root/trees/$key/contract-filter/manifest"
+payload="$(awk -F '\t' -v p="$path" '$1 == p { print $2; exit }' "$manifest" 2>/dev/null)"
+strip() {
+  awk -v sline="$start" -v eline="$end" 'BEGIN { n = 0 }
+    { lines[n++] = $0 }
+    END {
+      s = -1; e = -1
+      for (i = 0; i < n; i++) {
+        if (lines[i] == sline && s < 0) s = i
+        if (lines[i] == eline && s >= 0 && e < 0) e = i
+      }
+      if (s >= 0 && e >= s) {
+        a = s; while (a > 0 && lines[a-1] == "") a--
+        b = e; while (b + 1 < n && lines[b+1] == "") b++
+        j = 0
+        for (i = 0; i < n; i++) if (i < a || i > b) lines[j++] = lines[i]
+        n = j
+      }
+      for (i = 0; i < n; i++) print lines[i]
+    }'
+}
+case "$mode" in
+  clean) strip ;;
+  smudge)
+    if [ ! -r "$payload" ]; then strip; exit 0; fi
+    strip | awk -v b="$payload" -v sline="$start" -v eline="$end" 'BEGIN { n = 0 }
+      { lines[n++] = $0 }
+      END {
+        while (n > 0 && lines[n-1] == "") n--
+        for (i = 0; i < n; i++) print lines[i]
+        if (n > 0) print ""
+        print sline
+        while ((getline l < b) > 0) print l
+        print eline
+      }' ;;
+  *) echo "contract-filter.sh: unknown mode $mode" >&2; exit 1 ;;
+esac
+`;
+// edge ①: the command git runs is a tolerant wrapper — the shim path is an ARGUMENT ($0), and a missing/
+// unreadable shim degrades to `cat` (identity) instead of a per-operation fatal.
+const filterCmd = (shim, mode) => `sh -c 'test -r "$0" && exec bash "$0" ${mode} "$1" || exec cat' '${shim.replace(/'/g, `'\\''`)}' %f`;
+// plant (or refresh) the filter for the given contract files (tracked, or untracked-with-host-content —
+// pre-armed): the shim + the block content it smudges, the per-clone git config, and the attribute lines
+// binding each file to the filter. `contract` is the assembled block body (guide + surface:system).
+// settleIndexStat skips untracked entries (no index blob) by design and only runs after a real filter change.
+export function plantContractFilter(proj, payloads, bindings, changedFiles = []) {
+    const common = commonDirOf(proj);
+    mkdirSync(filterDir(common), { recursive: true });
+    let changed = writeFileIfChanged(shimPath(common), SHIM);
+    if (changed || (statSync(shimPath(common)).mode & 0o777) !== 0o755)
+        chmodSync(shimPath(common), 0o755);
+    const commands = new Map([
+        ['filter.spexcode.smudge', filterCmd(shimPath(common), 'smudge')],
+        ['filter.spexcode.clean', filterCmd(shimPath(common), 'clean')],
+    ]);
+    const configured = new Map();
+    try {
+        for (const row of git(['-C', proj, 'config', '--get-regexp', '^filter\\.spexcode\\.(smudge|clean)$']).trimEnd().split('\n')) {
+            const at = row.indexOf(' ');
+            if (at > 0)
+                configured.set(row.slice(0, at), row.slice(at + 1));
+        }
+    }
+    catch { }
+    for (const [key, command] of commands) {
+        if (configured.get(key) === command)
+            continue;
+        git(['-C', proj, 'config', key, command]);
+        changed = true;
+    }
+    changed = writeFileIfChanged(bindingsPath(common), bindings.map((b) => `${b.file}\t${b.start}\t${b.end}`).join('\n') + '\n') || changed;
+    const dir = treeFilterDir(proj);
+    mkdirSync(dir, { recursive: true });
+    const manifest = [];
+    const wanted = new Set(['manifest']);
+    for (const [i, payload] of payloads.entries()) {
+        const target = join(dir, String(i));
+        wanted.add(String(i));
+        changed = writeFileIfChanged(target, payload.content.endsWith('\n') ? payload.content : `${payload.content}\n`) || changed;
+        manifest.push(`${payload.file}\t${target}`);
+    }
+    for (const entry of readdirSync(dir)) {
+        if (!wanted.has(entry)) {
+            rmSync(join(dir, entry), { recursive: true, force: true });
+            changed = true;
+        }
+    }
+    const manifestPath = join(dir, 'manifest');
+    changed = writeFileIfChanged(manifestPath, manifest.join('\n') + (manifest.length ? '\n' : '')) || changed;
+    changed = writeFileIfChanged(rootPath(common), `${runtimeRoot(proj)}\n`) || changed;
+    // Attribute patterns are checkout-relative; the stable binding set is safe in the common git dir because
+    // the driver selects a payload from the invoking checkout's tree slot.
+    const entries = bindings.map((b) => `/${b.file} filter=spexcode`).sort().join('\n');
+    mkdirSync(join(common, 'info'), { recursive: true });
+    changed = writeManagedBlock(attributesPath(common), entries, ['# ', '']) || changed;
+    const settle = changed ? payloads.map((p) => join(proj, p.file)) : changedFiles;
+    if (settle.length)
+        settleIndexStat(proj, [...new Set(settle)]);
+    return changed;
+}
+// settle the index STAT for each file — the famous filtered-path phantom-`M`: git cannot verify a
+// clean-filtered path by stat alone (worktree size ≠ blob size by design), and `git status` reports such an
+// entry modified FOREVER without ever content-checking it (field-verified on git 2.43; `git diff` meanwhile
+// runs the filter and shows nothing; even `update-index --really-refresh` leaves it). The block-strip side of
+// a mode switch/backout leaves the same stale stat on the then-unfiltered path. `git add --renormalize`
+// re-cleans the file and refreshes the cached stat — run ONLY when the (possibly filtered) worktree already
+// EQUALS the index blob, so it is a pure stat refresh that can never stage a user's real unstaged edit (a
+// genuine edit keeps its honest `M`). Exported for dematerialize (the unplant side); plant calls it below.
+// Best-effort: an unsettled stat is cosmetic noise, never corruption.
+export function settleIndexStat(proj, files) {
+    const env = { ...process.env };
+    delete env.GIT_DIR;
+    delete env.GIT_WORK_TREE;
+    delete env.GIT_INDEX_FILE;
+    delete env.GIT_OBJECT_DIRECTORY;
+    for (const f of files) {
+        const rel = relative(proj, f);
+        try {
+            const indexBlob = git(['-C', proj, 'rev-parse', `:${rel}`]).trim();
+            const filtered = execFileSync(gitBinary(env), ['-C', proj, 'hash-object', '--path', rel, '--stdin'], { input: readFileSync(f), env, stdio: ['pipe', 'pipe', 'ignore'] }).toString().trim();
+            if (indexBlob === filtered)
+                git(['-C', proj, 'add', '--renormalize', '--', rel]);
+        }
+        catch { /* best-effort */ }
+    }
+}
+// the full inverse (edge ③ — call AFTER the managed blocks left the working files): attribute lines out,
+// config keys unset, shim + block content removed. `<common>/spexcode/` may host other spexcode data
+// (evidence blobs), so only OUR two files go, never the dir.
+export function clearContractFilterPayload(proj, files = []) {
+    try {
+        rmSync(treeFilterDir(proj), { recursive: true, force: true });
+    }
+    catch { /* inaccessible tree */ }
+    settleIndexStat(proj, files);
+}
+export function removeContractFilter(proj, files = [], final = false) {
+    let common;
+    try {
+        common = commonDirOf(proj);
+    }
+    catch {
+        return;
+    } // not a git repo → nothing was ever planted
+    clearContractFilterPayload(proj, files);
+    const anotherPayload = final ? false : (() => {
+        const rows = git(['-C', proj, 'worktree', 'list', '--porcelain', '-z']).split('\0');
+        const root = runtimeRoot(proj);
+        return rows
+            .filter((row) => row.startsWith('worktree '))
+            .map((row) => row.slice('worktree '.length))
+            .some((tree) => existsSync(join(root, 'trees', encodeProject(tree), 'contract-filter', 'manifest')));
+    })();
+    if (!final && anotherPayload)
+        return;
+    removeManagedBlock(attributesPath(common), ['# ', ''], true);
+    for (const key of ['filter.spexcode.smudge', 'filter.spexcode.clean']) {
+        try {
+            git(['-C', proj, 'config', '--unset-all', key]);
+        }
+        catch { /* not set — already clean */ }
+    }
+    for (const path of [shimPath(common), rootPath(common), bindingsPath(common)])
+        rmSync(path, { force: true });
+}
+// is the filter currently planted? (the assert-side probe tests use; cheap: one config read)
+export function contractFilterPlanted(proj) {
+    try {
+        return git(['-C', proj, 'config', 'filter.spexcode.clean']).trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/dashboard-assets.d.ts

@@ -0,0 +1,6 @@
+export type DashboardArtifact = 'dist' | 'dist-public';
+export declare class DashboardAssetError extends Error {
+    constructor(message: string);
+}
+export declare function dashboardArtifactDir(artifact: DashboardArtifact): string;
+export declare function ensureDashboardArtifact(artifact: DashboardArtifact): string;

package/dist/dashboard-assets.js

@@ -0,0 +1,50 @@
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+export class DashboardAssetError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DashboardAssetError';
+    }
+}
+const PACKAGE = '@spexcode/spec-dashboard';
+const INSTALL = `npm install ${PACKAGE}`;
+function dashboardRoot() {
+    try {
+        return dirname(createRequire(import.meta.url).resolve(`${PACKAGE}/package.json`));
+    }
+    catch {
+        throw new DashboardAssetError(`dashboard UI is not installed (${PACKAGE}). Install it with: ${INSTALL}`);
+    }
+}
+// Dashboard assets belong to the dashboard package. Resolving its manifest handles both an npm dependency
+// and a workspace link without teaching CLI code where either layout happens to live.
+export function dashboardArtifactDir(artifact) {
+    const root = dashboardRoot();
+    const dir = join(root, artifact);
+    if (existsSync(join(dir, 'index.html')))
+        return dir;
+    const repair = existsSync(join(root, 'src'))
+        ? `build the dashboard package before running this command`
+        : `reinstall ${PACKAGE}`;
+    throw new DashboardAssetError(`dashboard UI package is incomplete: missing ${artifact}/index.html at ${root}. To repair, ${repair}.`);
+}
+export function ensureDashboardArtifact(artifact) {
+    try {
+        return dashboardArtifactDir(artifact);
+    }
+    catch (error) {
+        if (!(error instanceof DashboardAssetError))
+            throw error;
+        const root = dashboardRoot();
+        if (!existsSync(join(root, 'src')))
+            throw error;
+        const script = artifact === 'dist' ? 'build' : 'build:public';
+        console.log(`[dashboard] ${artifact} is not built — running npm run ${script} in ${PACKAGE}…`);
+        const result = spawnSync('npm', ['run', script], { cwd: root, stdio: 'inherit' });
+        if (result.status === 0)
+            return dashboardArtifactDir(artifact);
+        throw new DashboardAssetError(`dashboard UI build failed for ${PACKAGE}. Repair it with: (cd ${root} && npm run ${script})`);
+    }
+}

package/dist/delivery-queue.d.ts

@@ -0,0 +1,23 @@
+export type PendingMessage = {
+    mid: string;
+    text: string;
+    from: string | null;
+    dispatch?: {
+        operation: 'merge';
+        requestDigest: string;
+    };
+};
+export declare function revokeSenderDelivery(id: string): void;
+export declare const senderDeliveryRevoked: (id: string) => boolean;
+export declare function pendingSnapshot(id: string): PendingMessage[];
+export declare function replacePendingWhileLocked(id: string, msgs: PendingMessage[]): void;
+export declare function revokePendingFromWhileLocked(id: string, sender: string): number;
+export declare function enqueue(id: string, msg: PendingMessage): void;
+export declare function ensurePendingWhileLocked(id: string, msg: PendingMessage): boolean;
+export declare const pendingMessages: (id: string) => PendingMessage[];
+export declare const owesDelivery: (id: string) => boolean;
+export declare function withDeliveryLocks<T>(rawIds: string[], body: () => Promise<T>, index?: number, ids?: string[]): Promise<T>;
+export declare function drain(id: string, insert: (msg: PendingMessage) => Promise<boolean>, timeoutMs?: number): Promise<{
+    delivered: number;
+    remaining: number;
+}>;

package/dist/delivery-queue.js

@@ -0,0 +1,179 @@
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+import { runtimeRoot, sessionArtifactPath, sessionStoreDir } from '@spexcode/spec-core';
+const queuePath = (id) => sessionArtifactPath(id, 'pending.json');
+const revokedSenderRoot = () => join(runtimeRoot(), '.revoked-senders');
+const revokedSenderPath = (id) => join(revokedSenderRoot(), id);
+// @@@ its own lock, deliberately NOT the record lock - the drain holds this across the adapter insert, which
+// is what makes "claim" real: two processes draining the same session cannot both hand over one message. The
+// record lock could never span that call — a native turn runs lifecycle hooks that re-enter the record writer,
+// and holding it there deadlocks the adapter's own confirmation. Nothing in the delivery path takes this one,
+// so spanning the insert costs no contention. PID liveness reclaims a lock whose holder died mid-insert.
+const lockRoot = () => join(runtimeRoot(), '.delivery-locks');
+const lockPath = (id) => join(lockRoot(), `${id}.lock`);
+const pause = (ms) => new Promise((r) => setTimeout(r, ms));
+async function acquire(id, timeoutMs) {
+    mkdirSync(lockRoot(), { recursive: true });
+    const path = lockPath(id), deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            const fd = openSync(path, 'wx');
+            writeSync(fd, String(process.pid));
+            closeSync(fd);
+            return () => { try {
+                unlinkSync(path);
+            }
+            catch { /* a liveness reclaim already removed it */ } };
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+            let owner = 0;
+            try {
+                owner = Number(readFileSync(path, 'utf8').trim()) || 0;
+            }
+            catch { /* race with creator/releaser */ }
+            if (owner && owner !== process.pid) {
+                try {
+                    process.kill(owner, 0);
+                }
+                catch {
+                    try {
+                        unlinkSync(path);
+                    }
+                    catch { /* race */ }
+                    ;
+                    continue;
+                }
+            }
+            // A drain is never urgent enough to fight for: whoever holds the lock is delivering these same messages,
+            // and the retry sweep will come back. Declining is not a lost message.
+            if (Date.now() >= deadline)
+                return null;
+            await pause(25);
+        }
+    }
+}
+function read(id) {
+    try {
+        const raw = JSON.parse(readFileSync(queuePath(id), 'utf8'));
+        if (!Array.isArray(raw))
+            return [];
+        return raw.filter((m) => !!m && typeof m === 'object'
+            && typeof m.mid === 'string'
+            && typeof m.text === 'string'
+            && (m.dispatch === undefined
+                || (m.dispatch?.operation === 'merge'
+                    && typeof m.dispatch?.requestDigest === 'string')));
+    }
+    catch {
+        return [];
+    } // absent, empty, or unparseable all mean the honest thing: nothing owed
+}
+// Written whole and atomically; an empty queue is REMOVED rather than left as `[]`, so "is anything owed?" is
+// one existsSync on the sweep's hot path.
+function write(id, msgs) {
+    const path = queuePath(id);
+    if (!msgs.length) {
+        try {
+            unlinkSync(path);
+        }
+        catch { /* already gone */ }
+        ;
+        return;
+    }
+    mkdirSync(sessionStoreDir(id), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(msgs, null, 2) + '\n');
+    renameSync(tmp, path);
+}
+// A closed sender may have left debt in many other sessions' queues. The marker is deliberately outside its
+// own store (which close removes) and is checked under the sender's record lock by dispatch: a close cannot
+// return while an old process can still append, and a later sweep cannot hand over what it sees here.
+export function revokeSenderDelivery(id) {
+    mkdirSync(revokedSenderRoot(), { recursive: true });
+    writeFileSync(revokedSenderPath(id), `${id}\n`);
+}
+export const senderDeliveryRevoked = (id) => existsSync(revokedSenderPath(id));
+export function pendingSnapshot(id) { return read(id); }
+// These two writes require the target's delivery lock. They are the queue half of a larger transaction
+// (currently reparent), which must be able to restore the exact previous debt if a later record write fails.
+export function replacePendingWhileLocked(id, msgs) { write(id, msgs); }
+export function revokePendingFromWhileLocked(id, sender) {
+    const current = read(id);
+    const next = current.filter((msg) => msg.from !== sender);
+    write(id, next);
+    return current.length - next.length;
+}
+// The enqueue rides the timeline append ([[dispatch]]): the caller holds the session's RECORD lock across
+// both, and the record is written first, so delivery is never unrecorded. A keyed dispatch also carries its
+// exact delivery bytes in the timeline receipt, letting its retry restore a queue write lost to a crash.
+export function enqueue(id, msg) {
+    write(id, [...read(id), msg]);
+}
+// Caller holds this target's delivery lock. A retry may reach this after either side of the receipt->queue
+// crash boundary; exact mid identity makes reconstruction idempotent without inspecting message text.
+export function ensurePendingWhileLocked(id, msg) {
+    const current = read(id);
+    if (current.some((pending) => pending.mid === msg.mid))
+        return false;
+    write(id, [...current, msg]);
+    return true;
+}
+export const pendingMessages = (id) => read(id);
+export const owesDelivery = (id) => existsSync(queuePath(id));
+// Record transitions and queue mutations take locks in the same direction: record locks first, then these
+// target queue locks. A batch reparent needs all child queues held at once so its pointer/watch/debt change
+// either commits together or restores together.
+export async function withDeliveryLocks(rawIds, body, index = 0, ids = [...new Set(rawIds)].sort()) {
+    if (index >= ids.length)
+        return body();
+    const release = await acquire(ids[index], 30_000);
+    if (!release)
+        throw new Error(`delivery queue ${ids[index]}: timed out waiting for transaction lock`);
+    try {
+        return await withDeliveryLocks(ids, body, index + 1, ids);
+    }
+    finally {
+        release();
+    }
+}
+// Hand over what is owed, in order, exactly once. `insert` reports whether the adapter took the message: only
+// then is the entry dropped. A refusal ENDS the pass with that entry still queued and everything behind it
+// still behind it — order is a property of a conversation, so a message is never skipped to deliver a later
+// one. Returns how many were handed over and how many are still owed.
+export async function drain(id, insert, timeoutMs = 5_000) {
+    const release = await acquire(id, timeoutMs);
+    if (!release)
+        return { delivered: 0, remaining: read(id).length };
+    let delivered = 0;
+    try {
+        for (;;) {
+            const queued = read(id);
+            if (!queued.length)
+                return { delivered, remaining: 0 };
+            if (queued[0].from && senderDeliveryRevoked(queued[0].from)) {
+                // Closing a sender voids its undelivered output, not the recipient's immutable conversation history.
+                // Drop a revoked head and continue so it cannot permanently block the messages behind it.
+                write(id, read(id).filter((m) => m.mid !== queued[0].mid));
+                continue;
+            }
+            let ok = false;
+            try {
+                ok = await insert(queued[0]);
+            }
+            catch {
+                ok = false;
+            }
+            if (!ok)
+                return { delivered, remaining: queued.length };
+            // Re-read before removing: a send that landed while this pass ran appended to the tail, and rewriting a
+            // stale snapshot minus the head would silently drop it.
+            write(id, read(id).filter((m) => m.mid !== queued[0].mid));
+            delivered++;
+        }
+    }
+    finally {
+        release();
+    }
+}

package/dist/doctor.d.ts

@@ -0,0 +1,9 @@
+export type HealthFinding = {
+    check: string;
+    spec: string;
+    summary: string;
+    evidence: string[];
+    repair: string;
+};
+export declare function specHealthDiagnosis(root: string): Promise<HealthFinding[]>;
+export declare function runDoctor(args: string[]): Promise<number>;