brainclaw 1.7.5 → 1.9.0

package/dist/core/loops/hooks/survey-signals-baseline.js

@@ -0,0 +1,36 @@
+import { runBootstrapProfile } from '../../bootstrap.js';
+const DEFAULT_MAX_SEEDS = 20;
+const DEFAULT_MAX_BYTES = 3800;
+export function buildSurveySignalsBaseline(cwd, opts = {}) {
+    const maxSeeds = opts.maxSeeds ?? DEFAULT_MAX_SEEDS;
+    const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+    const result = runBootstrapProfile({ cwd });
+    const baseline = {
+        generated_at: new Date().toISOString(),
+        source: 'deterministic_scanner',
+        summary: result.profile.summary,
+        workspace_kind: result.profile.workspace_kind,
+        onboarding_mode: result.profile.onboarding_mode,
+        confidence: result.profile.confidence,
+        sources_scanned: result.profile.sources_scanned,
+        native_instruction_files: result.profile.native_instruction_files,
+        gaps: result.profile.gaps,
+        seed_count: result.seeds.length,
+        seeds: result.seeds.slice(0, maxSeeds).map((seed) => ({
+            kind: seed.seed_kind,
+            text: seed.text,
+            source_kind: seed.source_kind,
+            source_ref: seed.source_ref,
+            confidence: seed.confidence,
+        })),
+        seeds_truncated: result.seeds.length > maxSeeds,
+    };
+    // Fit the byte budget by shedding seeds from the tail; the histogram-level
+    // fields are small and always kept.
+    while (baseline.seeds.length > 0 && Buffer.byteLength(JSON.stringify(baseline), 'utf8') > maxBytes) {
+        baseline.seeds.pop();
+        baseline.seeds_truncated = true;
+    }
+    return baseline;
+}
+//# sourceMappingURL=survey-signals-baseline.js.map

package/dist/core/loops/index.js

@@ -8,6 +8,7 @@ export { BOOTSTRAP_PRESET } from './presets/bootstrap.js';
 export { writeProjectMdSafe, } from './hooks/bootstrap-write.js';
 export { notifyOperatorOnInputRequested } from './hooks/notify-operator.js';
 export { readSurveySources, } from './hooks/survey-source-reader.js';
+export { buildSurveySignalsBaseline, } from './hooks/survey-signals-baseline.js';
 export { acquireLock, hashRequest, recordConflict, withLoopLock, DEFAULT_MAX_MUTATION_DURATION_MS, IDEMPOTENCY_TTL_MS, LEASE_GRACE_MS, LEASE_WINDOW_MS, IdempotencyKeyReusedError, IdempotencyOwnerMismatchError, LockLostError, LockTimeoutError, VersionConflictError, } from './lock.js';
 export { acquireBootstrapLoop, findExistingBootstrapLoop, BootstrapCoordinationInProgressError, } from './bootstrap-acquire.js';
 //# sourceMappingURL=index.js.map

package/dist/core/loops/presets/bootstrap.js

@@ -22,6 +22,13 @@ export const BOOTSTRAP_PRESET = {
         // is unchanged — see types.ts). Empirical motivation: TranslaVox cold-start
         // missed the actual GCP Speech+Translate pipeline because survey scanned only
         // topology + manifests (can_0160d6c4).
+        //
+        // pln#557 step 4 — the deterministic scanner (runBootstrapProfile) now
+        // seeds this phase: acquireBootstrapLoop attaches a `signals_baseline`
+        // artifact (toolchain, topology, native rules, top seeds) at open time.
+        // The champion enriches that baseline into its signals_report — survey
+        // quality stops depending on per-agent re-discovery, and bclaw_bootstrap
+        // becomes an internal helper of the loop rather than a competing door.
         {
             name: 'survey',
             context_filter: ['project_vision', 'decisions', 'plans', 'feedback'],

package/dist/core/loops/store.js

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { memoryDir, writeFileAtomic } from '../io.js';
 import { nowISO } from '../ids.js';
+import { convergeAssignmentToTerminal } from '../assignments.js';
 import { writeProjectMdSafe } from './hooks/bootstrap-write.js';
 import { notifyOperatorOnInputRequested } from './hooks/notify-operator.js';
 import { DEFAULT_PROTOCOLS, LoopArtifactSchema, LoopEventSchema, LoopThreadSchema, } from './types.js';
@@ -416,6 +417,22 @@ export function closeLoop(input, cwd) {
         reason: input.reason,
     }, cwd);
     writeThreadFile(next, cwd);
+    // pln#563: converge slot assignments so they don't fossilize in `offered`.
+    // A review-loop assignment exists only to drive the turn; closing the loop is
+    // the authoritative end of that work. File-based / sandboxed workers never
+    // report a terminal status themselves, and the coordinator can't cross-update
+    // a worker-owned assignment (trp#291) — so the loop close (a system action)
+    // is the right place. Best-effort: a missing or already-terminal assignment
+    // must never block the close.
+    const assignmentTerminal = input.final_status === 'completed' ? 'completed' : 'cancelled';
+    for (const slot of next.slots) {
+        if (!slot.assignment_id)
+            continue;
+        try {
+            convergeAssignmentToTerminal(slot.assignment_id, assignmentTerminal, `loop ${input.id} closed (${input.final_status})`, cwd);
+        }
+        catch { /* never block loop close on assignment convergence */ }
+    }
     return next;
 }
 //# sourceMappingURL=store.js.map

package/dist/core/loops/verbs.js

@@ -1,5 +1,6 @@
 import crypto from 'node:crypto';
 import { nowISO } from '../ids.js';
+import { convergeAssignmentToTerminal } from '../assignments.js';
 import { writeProjectMdSafe } from './hooks/bootstrap-write.js';
 import { appendEvent, closeLoop, generateMutationId, getLoop, listLoopEvents, writeThreadFile, } from './store.js';
 import { LoopArtifactSchema, PAUSE_REASONS, } from './types.js';
@@ -19,6 +20,17 @@ function loadLoopOrThrow(id, cwd) {
         throw new Error(`unknown loop_id ${id}`);
     return loop;
 }
+function convergeSlotAssignmentsForClosedLoop(thread, finalStatus, cwd) {
+    const assignmentTerminal = finalStatus === 'completed' ? 'completed' : 'cancelled';
+    for (const slot of thread.slots) {
+        if (!slot.assignment_id)
+            continue;
+        try {
+            convergeAssignmentToTerminal(slot.assignment_id, assignmentTerminal, `loop ${thread.id} closed (${finalStatus})`, cwd);
+        }
+        catch { /* never block loop close on assignment convergence */ }
+    }
+}
 /* ========================= Stop-condition evaluator ======================= */
 function isVerdictAccepted(artifact) {
     if (artifact.type !== 'verdict')
@@ -369,6 +381,7 @@ function commitClosedTransition(thread, final_status, actor, reason, cwd) {
         reason,
     }, cwd);
     writeThreadFile(next, cwd);
+    convergeSlotAssignmentsForClosedLoop(next, final_status, cwd);
     return next;
 }
 function resolveTurnSlot(thread, input) {
@@ -402,6 +415,7 @@ export function turn(input, cwd) {
             status: 'assigned',
             phase: current.current_phase,
             assignment_id: input.assignment_id ?? slot.assignment_id,
+            claim_id: input.claim_id ?? slot.claim_id,
         }
         : slot);
     const next = {
@@ -435,7 +449,13 @@ export function complete_turn(input, cwd) {
         throw new Error(`complete_turn: slot_id "${input.slot_id}" not in loop`);
     // Slot-bound auth. Only enforced when caller_agent_id is supplied (MCP entry path).
     if (input.caller_agent_id !== undefined && !input.admin_override) {
-        const ownerMatches = slot.agent_id !== undefined && slot.agent_id === input.caller_agent_id;
+        // Instance binding (pln#562 step 4): a claim-bound slot is owned by the
+        // INSTANCE holding that claim. When both sides carry claim info, claim
+        // equality decides; otherwise fall back to the legacy agent_id check.
+        const claimBound = slot.claim_id !== undefined && input.caller_claim_id !== undefined;
+        const ownerMatches = claimBound
+            ? slot.claim_id === input.caller_claim_id
+            : slot.agent_id !== undefined && slot.agent_id === input.caller_agent_id;
         const creatorMatches = current.created_by === input.caller_agent_id;
         if (!ownerMatches && !creatorMatches) {
             throw new Error('unauthorized_slot_write');
@@ -998,6 +1018,9 @@ export function provideInput(input, cwd) {
         }, cwd);
     }
     writeThreadFile(next, cwd);
+    if (fileApplyResolution !== undefined) {
+        convergeSlotAssignmentsForClosedLoop(next, 'completed', cwd);
+    }
     assertOpenQuestionsInvariant(next, 'provide_input');
     return { thread: next, artifact_id: newArtifact.artifact_id, duplicate: false };
 }

package/dist/core/markdown.js

@@ -1,12 +1,17 @@
-import { listClaims } from './claims.js';
 import { loadInstructions } from './instructions.js';
 import { memoryPath, writeFileAtomic } from './io.js';
 import { isTrapActive } from './traps.js';
 import { logger } from './logger.js';
 export function generateMarkdown(state, cwd) {
-    const lines = ['# Project Memory', ''];
+    const lines = [
+        '# Project Memory',
+        '',
+        '> Legacy derived summary generated from canonical Brainclaw memory.',
+        '> PROJECT.md at the workspace root is the durable project vision.',
+        '> For active claims, plans, handoffs, and agent state, use `brainclaw agent-board` or MCP board context.',
+        '',
+    ];
     const instructions = loadInstructions(cwd).filter((entry) => entry.active);
-    const claims = listClaims(cwd).filter((claim) => claim.status === 'active');
     lines.push('## Shared instructions');
     if (instructions.length === 0) {
         lines.push('- (none)');
@@ -19,50 +24,6 @@ export function generateMarkdown(state, cwd) {
         }
     }
     lines.push('');
-    lines.push('## Active claims');
-    if (claims.length === 0) {
-        lines.push('- (none)');
-    }
-    else {
-        for (const claim of claims) {
-            const meta = [claim.scope];
-            if (claim.plan_id)
-                meta.push(`plan: ${claim.plan_id}`);
-            if (claim.project)
-                meta.push(`project: ${claim.project}`);
-            lines.push(`- **[${claim.id}]** ${claim.agent} → ${claim.description} _(${meta.join(', ')})_`);
-        }
-    }
-    lines.push('');
-    lines.push('## Shared plan');
-    const activePlans = state.plan_items.filter((plan) => plan.status !== 'done' && plan.status !== 'dropped');
-    if (activePlans.length === 0) {
-        lines.push('- (none)');
-    }
-    else {
-        for (const plan of activePlans) {
-            const meta = [plan.status, plan.priority];
-            if (plan.assignee)
-                meta.push(`assignee: ${plan.assignee}`);
-            if (plan.project)
-                meta.push(`project: ${plan.project}`);
-            if (plan.steps && plan.steps.length > 0) {
-                const done = plan.steps.filter((s) => s.status === 'done').length;
-                meta.push(`${done}/${plan.steps.length} steps`);
-            }
-            const tags = plan.tags.length ? ` [${plan.tags.join(', ')}]` : '';
-            const paths = plan.related_paths?.length ? ` → ${plan.related_paths.join(', ')}` : '';
-            lines.push(`- **[${plan.id}]** ${plan.text} _(${meta.join(', ')})_${paths}${tags}`);
-            if (plan.steps && plan.steps.length > 0) {
-                for (const step of plan.steps) {
-                    const check = step.status === 'done' ? 'x' : ' ';
-                    const assign = step.assignee ? ` _(${step.assignee})_` : '';
-                    lines.push(`  - [${check}] [${step.id}] ${step.text}${assign}`);
-                }
-            }
-        }
-    }
-    lines.push('');
     lines.push('## Active constraints');
     if (state.active_constraints.length === 0) {
         lines.push('- (none)');
@@ -100,35 +61,6 @@ export function generateMarkdown(state, cwd) {
         }
     }
     lines.push('');
-    lines.push('## Open handoffs');
-    const MAX_HANDOFFS = 10;
-    const MAX_HANDOFF_TEXT = 500;
-    const activeHandoffs = state.open_handoffs
-        .filter((h) => h.status === 'open')
-        .sort((a, b) => b.created_at.localeCompare(a.created_at))
-        .slice(0, MAX_HANDOFFS);
-    const totalOpen = state.open_handoffs.filter((h) => h.status === 'open').length;
-    if (activeHandoffs.length === 0) {
-        lines.push('- (none)');
-    }
-    else {
-        for (const h of activeHandoffs) {
-            const tags = h.tags.length ? ` [${h.tags.join(', ')}]` : '';
-            const paths = h.related_paths?.length ? ` → ${h.related_paths.join(', ')}` : '';
-            const meta = [h.status];
-            if (h.plan_id)
-                meta.push(`plan: ${h.plan_id}`);
-            if (h.project)
-                meta.push(`project: ${h.project}`);
-            const text = h.text.length > MAX_HANDOFF_TEXT ? h.text.slice(0, MAX_HANDOFF_TEXT) + '...' : h.text;
-            lines.push(`- **[${h.id}]** ${h.from} → ${h.to}: ${text} _(${meta.join(', ')})_${paths}${tags}`);
-        }
-        const omitted = totalOpen - activeHandoffs.length;
-        if (omitted > 0) {
-            lines.push(`- _(${omitted} older handoffs omitted — use \`bclaw_read_handoff\` to inspect)_`);
-        }
-    }
-    lines.push('');
     return lines.join('\n');
 }
 /**

package/dist/core/mcp-command-resolution.js

@@ -0,0 +1,245 @@
+/**
+ * MCP command resolution + shared writer plumbing (pln#546 step 3 extraction).
+ *
+ * Extracted from agent-files.ts so the binary-resolution / shim-tracing logic
+ * can evolve independently of the per-agent writers. Three concerns live here:
+ *
+ *   1. Resolving the brainclaw MCP server invocation from any host shell
+ *      (which/where → cli.js shim → absolute node + cli.js pair). Falls back
+ *      to `npx brainclaw mcp` when nothing else resolves.
+ *   2. Building the `brainclawMcpEntry` JSON shape that every MCP writer emits
+ *      under `mcpServers.brainclaw` (or its agent-specific equivalent).
+ *   3. Hook-command rendering — `getBclawCliParts` + `buildHookCommand` for
+ *      writers that emit session-start / Stop / context-diff entries.
+ *
+ * The `_forceResolve` module flag is private to this file; callers toggle it
+ * via `withForcedResolve(cb)` so the next pair of `brainclawMcpEntry` calls
+ * overwrites existing absolute paths (used by `patchAllMcpConfigs` post-upgrade).
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+export function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Cached MCP command — resolved once per process. */
+let cachedMcpCommand;
+/** Module-level flag: when true, brainclawMcpEntry overwrites existing paths. */
+let _forceResolve = false;
+/**
+ * Resolve the brainclaw command for MCP configs.
+ * Returns `{ command: "<node>", args: ["<cli.js>", "mcp"] }` so the config
+ * works in non-login shells (VS Code Server, MCP subprocesses) on all OSes.
+ *
+ * Strategy:
+ * 1. Find the brainclaw bin via which/where
+ * 2. Trace from the bin/shim to the actual cli.js entry point
+ * 3. Pair it with the absolute node path
+ * Falls back to 'npx brainclaw mcp' if resolution fails.
+ */
+function resolveBrainclawMcpCommand() {
+    const nodeBin = process.execPath;
+    // 1. Try to resolve the cli.js from the installed brainclaw binary
+    const cliJs = resolveBrainclawCliJs();
+    if (cliJs) {
+        return { command: nodeBin, args: [cliJs, 'mcp'] };
+    }
+    // 2. Fallback: npx (relies on PATH, may resolve wrong version)
+    return { command: 'npx', args: ['brainclaw', 'mcp'] };
+}
+/**
+ * Trace from the brainclaw bin/shim to the actual dist/cli.js file.
+ * Works on Windows (.cmd shim), macOS/Linux (symlink to bin stub).
+ */
+function resolveBrainclawCliJs() {
+    // Strategy A: find via which/where and trace to cli.js
+    const whichCmd = os.platform() === 'win32' ? 'where' : 'which';
+    try {
+        const result = spawnSync(whichCmd, ['brainclaw'], { encoding: 'utf-8', timeout: 3000 });
+        if (result.status === 0) {
+            const resolved = result.stdout.trim().split(/\r?\n/)[0]?.trim();
+            if (resolved) {
+                const cliJs = traceToCliJs(resolved);
+                if (cliJs)
+                    return cliJs;
+            }
+        }
+    }
+    catch {
+        // Non-fatal — try next strategy
+    }
+    // Strategy B: resolve from this file's own package (we ARE brainclaw)
+    try {
+        const ownCliJs = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'cli.js');
+        if (fs.existsSync(ownCliJs))
+            return ownCliJs;
+    }
+    catch {
+        // Non-fatal
+    }
+    return undefined;
+}
+/**
+ * Given a bin path (shim or symlink), trace to the dist/cli.js entry point.
+ *
+ * Windows: .cmd shim contains a line like `"%_prog%" "%dp0%\node_modules\brainclaw\dist\cli.js" %*`
+ * Unix: bin is a symlink → resolve to real path → go up to package root → dist/cli.js
+ */
+function traceToCliJs(binPath) {
+    const isWindows = os.platform() === 'win32';
+    if (isWindows) {
+        // Read the .cmd shim and extract the cli.js path
+        const cmdPath = binPath.endsWith('.cmd') ? binPath : `${binPath}.cmd`;
+        try {
+            const content = fs.readFileSync(cmdPath, 'utf-8');
+            // Match patterns like: "%dp0%\node_modules\brainclaw\dist\cli.js"
+            const match = content.match(/%dp0%\\([^\s"]+cli\.js)/);
+            if (match) {
+                const shimDir = path.dirname(cmdPath);
+                const cliJs = path.resolve(shimDir, match[1]);
+                if (fs.existsSync(cliJs))
+                    return cliJs;
+            }
+        }
+        catch {
+            // Fall through
+        }
+    }
+    else {
+        // Unix: follow symlink chain to the real bin, then find cli.js
+        try {
+            const realBin = fs.realpathSync(binPath);
+            // Typical layout: .../node_modules/.bin/brainclaw → ../brainclaw/dist/cli.js
+            // Or: .../node_modules/brainclaw/dist/cli.js (direct)
+            if (realBin.endsWith('cli.js') && fs.existsSync(realBin))
+                return realBin;
+            // The bin stub typically lives at node_modules/brainclaw/dist/cli.js
+            // or node_modules/.bin/brainclaw → ../brainclaw/dist/cli.js
+            const packageRoot = findPackageRoot(realBin);
+            if (packageRoot) {
+                const cliJs = path.join(packageRoot, 'dist', 'cli.js');
+                if (fs.existsSync(cliJs))
+                    return cliJs;
+            }
+        }
+        catch {
+            // Fall through
+        }
+    }
+    return undefined;
+}
+/** Walk up from a file to find the nearest directory containing package.json with name "brainclaw". */
+function findPackageRoot(from) {
+    let dir = path.dirname(from);
+    for (let i = 0; i < 10; i++) {
+        const pkgPath = path.join(dir, 'package.json');
+        try {
+            if (fs.existsSync(pkgPath)) {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+                if (pkg.name === 'brainclaw')
+                    return dir;
+            }
+        }
+        catch { /* continue */ }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+export function getBrainclawMcpCommand() {
+    if (!cachedMcpCommand) {
+        cachedMcpCommand = resolveBrainclawMcpCommand();
+    }
+    return cachedMcpCommand;
+}
+/** Reset the cached MCP command so it gets re-resolved on next access. */
+export function resetMcpCommandCache() {
+    cachedMcpCommand = undefined;
+}
+/** Test/internal helper — read the current force-resolve state. */
+export function isForceResolveEnabled() {
+    return _forceResolve;
+}
+/**
+ * Run `cb` with force-resolve mode enabled, so `brainclawMcpEntry` overwrites
+ * any existing absolute paths in user MCP configs. Always restores the prior
+ * state, even when `cb` throws.
+ */
+export function withForcedResolve(cb) {
+    const previous = _forceResolve;
+    _forceResolve = true;
+    try {
+        return cb();
+    }
+    finally {
+        _forceResolve = previous;
+    }
+}
+/**
+ * Build a complete MCP server entry with relay model env injection.
+ * Merges with the existing entry to preserve manual edits (e.g. custom command
+ * path, additional env vars, extra args). Only sets defaults for missing fields.
+ *
+ * When `workspacePath` is provided, injects BRAINCLAW_CWD into the env so
+ * the MCP server resolves the correct workspace root regardless of the IDE's
+ * process.cwd() at launch time.
+ */
+export function brainclawMcpEntry(agentName, existing, workspacePath) {
+    const defaults = getBrainclawMcpCommand();
+    const ex = isJsonObject(existing) ? existing : {};
+    const exEnv = isJsonObject(ex.env) ? ex.env : {};
+    // When _forceResolve is true (post-upgrade), always use newly resolved paths.
+    // Otherwise preserve existing command if it's an absolute path (manual edit).
+    // CRITICAL: once we decide to preserve the command, we MUST also preserve
+    // the args. Previously args was always overwritten, which silently clobbered
+    // manual customizations (--cwd, --debug, etc.) and broke setups on DGX.
+    // See trp#12 + pln#450.
+    const useExisting = !_forceResolve && typeof ex.command === 'string' && ex.command !== 'npx';
+    const existingArgs = Array.isArray(ex.args) ? ex.args : undefined;
+    return {
+        command: useExisting ? ex.command : defaults.command,
+        args: useExisting && existingArgs ? existingArgs : defaults.args,
+        // Merge env: preserve user-added vars, ensure BRAINCLAW_AGENT is set
+        env: {
+            ...exEnv,
+            BRAINCLAW_AGENT: agentName,
+            ...(workspacePath ? { BRAINCLAW_CWD: workspacePath } : {}),
+        },
+        // Preserve timeout if set
+        ...(typeof ex.timeout === 'number' ? { timeout: ex.timeout } : {}),
+    };
+}
+export function quoteShellArg(arg) {
+    if (/^[A-Za-z0-9_./:=+-]+$/.test(arg))
+        return arg;
+    return `"${arg.replace(/"/g, '\\"')}"`;
+}
+/**
+ * Resolve the brainclaw CLI invocation for hook configs.
+ * Returns shell-safe parts like `["<node>", "<cli.js>"]` or `["npx", "brainclaw"]`.
+ */
+export function getBclawCliParts() {
+    const mcpCmd = getBrainclawMcpCommand();
+    if (mcpCmd.command === 'npx')
+        return ['npx', 'brainclaw'];
+    const argsWithoutMcp = [...mcpCmd.args];
+    if (argsWithoutMcp[argsWithoutMcp.length - 1] === 'mcp') {
+        argsWithoutMcp.pop();
+    }
+    return [
+        mcpCmd.command.replace(/\\/g, '/'),
+        ...argsWithoutMcp.map((arg) => arg.replace(/\\/g, '/')),
+    ];
+}
+export function buildHookCommand(args, shell = os.platform() === 'win32' ? 'powershell' : 'bash') {
+    const rendered = [...getBclawCliParts(), ...args].map(quoteShellArg).join(' ');
+    if (shell === 'powershell') {
+        return `& ${rendered} 2>$null`;
+    }
+    return `${rendered} 2>/dev/null`;
+}
+//# sourceMappingURL=mcp-command-resolution.js.map

package/dist/core/memory-compactor.js

@@ -17,7 +17,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { normalise, similarity } from './duplicates.js';
 import { resolveEntityDir } from './io.js';
-import { loadState, saveState } from './state.js';
+import { loadState, persistState } from './state.js';
 import { mutate } from './mutation-pipeline.js';
 import { logger } from './logger.js';
 const DEFAULT_SIMILARITY_THRESHOLD = 0.55;
@@ -118,7 +118,9 @@ export function analyzeAndApply(options = {}) {
         archivedCount = applied.archivedCount;
         mergedClusters = applied.mergedClusters;
         staleArchived = applied.staleArchived;
-        saveState(state, cwd);
+        // deleteMissing: archived items must have their live files unlinked; the RMW
+        // is atomic (loadState above runs under this mutate() lock).
+        persistState(state, cwd, { writeProjectMarkdown: false, deleteMissing: true });
     });
     return { report, result: { archivedCount, mergedClusters, staleArchived } };
 }
@@ -138,7 +140,7 @@ export function applyCompaction(report, options = {}) {
         archivedCount = applied.archivedCount;
         mergedClusters = applied.mergedClusters;
         staleArchived = applied.staleArchived;
-        saveState(state, cwd);
+        persistState(state, cwd, { writeProjectMarkdown: false, deleteMissing: true });
     });
     return { archivedCount, mergedClusters, staleArchived };
 }