@north-light/crouter 0.3.252 → 0.3.254

package/dist/commands/memory/delete.js

@@ -37,6 +37,7 @@ export const deleteLeaf = defineLeaf({
             selectorParam('dir', {}, 'Deletes from that one store, including a non-winning duplicate no target view resolves to.'),
         ],
         output: [
+            { name: 'name', type: 'string', required: true, constraint: 'Full canonical name of the document that was deleted, as resolution settled it.' },
             { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was deleted from: node, user, project, or profile.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path of the file that was removed.' },
             { name: 'log_path', type: 'string', required: true, constraint: 'Absolute path to the document’s revision log, which OUTLIVES the document — the delete is appended to it as a tombstone carrying the full final text, still readable with `crtr memory history`.' },
@@ -87,6 +88,7 @@ export const deleteLeaf = defineLeaf({
         // this same log — one log per physical path over its whole life.
         appendHistoryRecord(logPath, buildHistoryRecord({ op: 'delete', before, after: '' }));
         return {
+            name: doc.name,
             scope: doc.scope,
             path: doc.path,
             log_path: logPath,

package/dist/commands/node/lifecycle.js

@@ -109,15 +109,15 @@ const nodeClose = defineLeaf({
         return `Closed ${r['node_id']} and its exclusive subtree — ${r['count']} node(s) closed${spared > 0 ? `, ${spared} spared (still managed from outside the subtree)` : ''}.`;
     },
 });
-// node config — reconfigure a node's settings headlessly (model/lifecycle/kind/mode/name)
+// node config — reconfigure a node's settings headlessly (model/lifecycle/kind/mode/name/cwd repair)
 const NODE_CONFIG_MODEL_EFFECT = 'Model change first: a live broker switches immediately over its socket; a dormant node persists the durable model override and launch recipe for its next revive.';
 export const nodeConfig = defineLeaf({
     name: 'config',
-    description: 'reconfigure a node\'s settings headlessly — model, lifecycle (terminal/resident), kind, mode, name',
-    whenToUse: 'you want to reconfigure a node\'s settings headlessly after spawn — swap its model/provider, flip it terminal↔resident (interactable), respecialize its kind, switch base↔orchestrator mode, or rename it — without opening its viewer. The durable attribute setter; reuses the same recipes a revive reads. Use `node promote` for the opinionated self-promotion path, and `node lifecycle` for teardown actions (recycle/close/demote).',
+    description: 'reconfigure a node\'s settings headlessly — model, lifecycle (terminal/resident), kind, mode, name; repair a missing cwd',
+    whenToUse: 'you want to reconfigure a node\'s settings headlessly after spawn — swap its model/provider, flip it terminal↔resident (interactable), respecialize its kind, switch base↔orchestrator mode, or rename it — without opening its viewer. It also repairs a dormant node whose recorded cwd is gone, starting its next revive in a fresh conversation. The durable attribute setter; reuses the same recipes a revive reads. Use `node promote` for the opinionated self-promotion path, and `node lifecycle` for teardown actions (recycle/close/demote).',
     help: {
         name: 'node config',
-        summary: 'reconfigure a node\'s settings headlessly — model, lifecycle, kind, mode, name',
+        summary: 'reconfigure a node\'s settings headlessly — model, lifecycle, kind, mode, name; repair a missing cwd',
         params: [
             { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Target node id. Defaults to the node in --pane, else CRTR_NODE_ID.' },
             { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id to resolve the node from. Defaults to $TMUX_PANE.' },
@@ -140,20 +140,23 @@ export const nodeConfig = defineLeaf({
             { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Persona kind. The <kinds> list below names every top-level installable kind and when to use each; a registered sub-kind is valid too by exact path but not listed here.' },
             { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, constraint: 'Set persona mode headlessly. base is hands-on; orchestrator holds a roadmap and delegates. orchestrator seeds a roadmap scaffold if absent.' },
             { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Rename the node; if the node has a live window, also rename that viewer window.' },
+            { kind: 'flag', name: 'cwd', type: 'string', required: false, constraint: 'Repair-only replacement launch directory. Must be a non-empty absolute existing directory and used alone; the daemon accepts it only for a dormant, non-forked node with no open managed worktree whose recorded cwd is gone. Clears the saved Pi session, so the next revive starts fresh while durable node work remains.' },
         ],
         output: [
-            { name: 'node_id', type: 'string', required: true, constraint: 'The reconfigured node.' },
+            { name: 'node_id', type: 'string', required: false, constraint: 'The reconfigured node, present for ordinary config changes.' },
             { name: 'model', type: 'string', required: false, constraint: 'The resolved model, present only when --model changed it.' },
             { name: 'lifecycle', type: 'string', required: false, constraint: 'The new lifecycle, present only when --lifecycle changed it.' },
             { name: 'kind', type: 'string', required: false, constraint: 'The new kind, present only when --kind changed it.' },
             { name: 'mode', type: 'string', required: false, constraint: 'The new mode, present only when --mode changed it.' },
             { name: 'name', type: 'string', required: false, constraint: 'The new name, present only when --name changed it.' },
+            { name: 'cwd', type: 'string', required: false, constraint: 'The lexically resolved replacement directory, present only after a cwd repair.' },
         ],
         outputKind: 'object',
         effects: [
             NODE_CONFIG_MODEL_EFFECT,
             'Kind, mode, and lifecycle changes rebuild the launch spec from the fresh node meta; setting mode to orchestrator seeds a roadmap scaffold if absent.',
             'Name changes update the row and, when the node already has a live window, rename that viewer window to the new full name.',
+            'A cwd repair writes only the lexically resolved cwd and clears saved Pi session pointers; the old transcript and durable node work remain untouched.',
         ],
         dynamicState: () => kindsStateBlock(),
     },
@@ -165,6 +168,10 @@ export const nodeConfig = defineLeaf({
         // kind is validated against the caller's installed personas here for the
         // clean listing error, and re-validated server-side against the TARGET
         // node's scope as a backstop.
+        const cwdSpec = input['cwd'];
+        if (cwdSpec !== undefined && ['model', 'kind', 'lifecycle', 'mode', 'name'].some((flag) => input[flag] !== undefined)) {
+            throw new InputError({ error: 'cwd_not_exclusive', message: 'cwd repair cannot be combined with another config flag', field: 'cwd', next: 'Pass --cwd alone.' });
+        }
         const modelSpec = input['model']?.trim();
         if (modelSpec === '') {
             throw new InputError({ error: 'empty_spec', message: 'a model spec is required', field: 'model', next: 'Run `crtr node config --model -h` and read the focused contract before retrying.' });
@@ -203,12 +210,18 @@ export const nodeConfig = defineLeaf({
             patch.name = nameSpec;
             applied.push('name');
         }
+        if (cwdSpec !== undefined) {
+            patch.cwd = cwdSpec;
+            applied.push('cwd');
+        }
         if (applied.length === 0) {
-            throw new InputError({ error: 'no_change', message: 'no config changes requested', next: 'Pass at least one of --model, --lifecycle, --kind, --mode, --name.' });
+            throw new InputError({ error: 'no_change', message: 'no config changes requested', next: 'Pass at least one of --model, --lifecycle, --kind, --mode, --name, --cwd.' });
         }
         const detail = await cliClient()
             .patchConfig(nodeId, patch)
             .catch((err) => rethrowAsCliError(err, 'List nodes with `crtr node inspect list`.'));
+        if (cwdSpec !== undefined)
+            return { cwd: detail.cwd };
         const result = { node_id: nodeId };
         if (applied.includes('model'))
             result.model = detail.model_override ?? modelSpec;
@@ -223,6 +236,8 @@ export const nodeConfig = defineLeaf({
         return result;
     },
     render: (r) => {
+        if (r['cwd'] !== undefined)
+            return `Repaired cwd: ${r['cwd']}.`;
         const bits = [];
         if (r['model'] !== undefined)
             bits.push(`model=${r['model']}`);

package/dist/core/__tests__/daemon-boot.test.js

@@ -193,17 +193,17 @@ test('verifyDaemonStartup waits for pidfile, live pid, and serving socket before
     assert.equal(socketServing, true, 'the Unix API socket must serve before success');
     assert.equal(slept >= 40, true, 'the guard must actually poll through socket readiness');
 });
-test('runDaemon awaits activation before ownership and readiness', () => {
+test('runDaemon claims ownership before activation and readiness', () => {
     const source = readFileSync(fileURLToPath(new URL('../../daemon/crtrd.ts', import.meta.url)), 'utf8');
     const runDaemonAt = source.indexOf('export async function runDaemon');
     const activationAt = source.indexOf('await ensureOnDiskMigrations();', runDaemonAt);
     const ownershipAt = source.indexOf('claimDaemonOwnership(', runDaemonAt);
     const readinessAt = source.indexOf('writePidfile();', runDaemonAt);
     assert.ok(runDaemonAt >= 0, 'runDaemon exists');
-    assert.ok(activationAt > runDaemonAt, 'runDaemon awaits on-disk activation');
-    assert.equal(source.slice(runDaemonAt, activationAt).includes('await '), false, 'activation is the first awaited operation');
-    assert.ok(activationAt < ownershipAt, 'activation precedes the ownership claim that opens canvas.db');
-    assert.ok(ownershipAt < readinessAt, 'ownership follows activation before readiness is published');
+    assert.ok(ownershipAt > runDaemonAt, 'runDaemon claims ownership');
+    assert.equal(source.slice(runDaemonAt, ownershipAt).includes('await '), false, 'ownership is claimed before startup can await');
+    assert.ok(ownershipAt < activationAt, 'ownership precedes on-disk activation');
+    assert.ok(activationAt < readinessAt, 'activation completes before readiness is published');
 });
 // Regression for the cold-guest recreate blocker: the production startup window
 // must tolerate a slower cold start than the old 500ms bound.

package/dist/core/__tests__/preview-mirror-cap.test.js

@@ -3,6 +3,9 @@
 // this channel — bypassing pi's 50 KB stdout truncation entirely — and five
 // such calls made a 16 MB transcript that Northlight could no longer open.
 // The writer is the one choke point, so the writer is what this pins.
+//
+// The file accumulates one record per crtr invocation in a bash call, so the
+// bound is on the file total: chaining commands must not be a way past it.
 import { strict as assert } from 'node:assert';
 import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -35,3 +38,16 @@ test('a bounded record still mirrors verbatim', () => {
     assert.equal(record.path, 'integration run');
     assert.equal(record.result.output, 'small');
 });
+test('chained invocations accumulate as JSONL, and stop at the file budget', () => {
+    const resultPath = join(dir, 'chained.json');
+    process.env[PREVIEW_RESULT_PATH_ENV] = resultPath;
+    const quarter = 'x'.repeat(Math.floor(PREVIEW_RESULT_MAX_BYTES / 4));
+    for (let i = 0; i < 6; i += 1) {
+        beginPreview('memory read');
+        publishPreviewResult({ i, output: quarter });
+    }
+    const lines = readFileSync(resultPath, 'utf8').split('\n').filter((line) => line !== '');
+    assert.equal(lines.length, 3, 'records land in order until the budget is spent, then are dropped whole');
+    assert.deepEqual(lines.map((line) => JSON.parse(line).result.i), [0, 1, 2]);
+    assert.ok(readFileSync(resultPath).byteLength <= PREVIEW_RESULT_MAX_BYTES, 'the accumulated file stays within the bound');
+});

package/dist/core/exclusive-lock.js

@@ -1,9 +1,16 @@
 import { existsSync, mkdirSync, readdirSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 const MARKER_PREFIX = 'owner.';
+// Contention backoff. The first polls stay tight so an uncontended hand-off is
+// still effectively immediate; the interval then doubles to a ceiling so a lock
+// held across a long operation (a corpus migration, say) cannot turn a crowd of
+// waiters into a filesystem hot loop — N waiters at a fixed 10ms is N*100
+// tryAcquire() syscall bursts per second on one directory.
 const POLL_MS = 10;
+const POLL_MAX_MS = 250;
 const DEFAULT_STALE_MS = 30_000;
 const DEFAULT_TIMEOUT_MS = 5_000;
+function nextPollMs(current) { return Math.min(current * 2, POLL_MAX_MS); }
 function pause(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
 function pauseAsync(ms) { return new Promise((resolve) => setTimeout(resolve, ms)); }
 function markerPath(path, token) { return `${path}/${MARKER_PREFIX}${token}`; }
@@ -107,12 +114,14 @@ function tryAcquire(path, staleMs) {
 export function withExclusiveDirectoryLock(path, operation, options = {}) {
     const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
     const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    let pollMs = POLL_MS;
     let lock = tryAcquire(path, staleMs);
     while (lock === null) {
         if (Date.now() >= deadline) {
             throw options.timeoutError?.() ?? new Error(`timed out waiting for the exclusive lock: ${path}`);
         }
-        pause(POLL_MS);
+        pause(Math.min(pollMs, Math.max(0, deadline - Date.now())));
+        pollMs = nextPollMs(pollMs);
         lock = tryAcquire(path, staleMs);
     }
     try {
@@ -127,12 +136,14 @@ export function withExclusiveDirectoryLock(path, operation, options = {}) {
 export async function withExclusiveDirectoryLockAsync(path, operation, options = {}) {
     const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
     const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    let pollMs = POLL_MS;
     let lock = tryAcquire(path, staleMs);
     while (lock === null) {
         if (Date.now() >= deadline) {
             throw options.timeoutError?.() ?? new Error(`timed out waiting for the exclusive lock: ${path}`);
         }
-        await pauseAsync(Math.min(POLL_MS, Math.max(0, deadline - Date.now())));
+        await pauseAsync(Math.min(pollMs, Math.max(0, deadline - Date.now())));
+        pollMs = nextPollMs(pollMs);
         lock = tryAcquire(path, staleMs);
     }
     try {

package/dist/core/io.d.ts

@@ -3,7 +3,12 @@ import { type ExitCodeValue } from '../types.js';
 import { ApiError } from '../api/index.js';
 /** The private result mirror for one crtr CLI invocation launched by the
  * canvas bash-preview extension. This deliberately never enters stdout: bash
- * text is model context, while Pi tool-result details are viewer-only. */
+ * text is model context, while Pi tool-result details are viewer-only.
+ *
+ * One bash tool call may run several crtr invocations (`read a && read b`), so
+ * the mirror file is JSONL: one record per invocation, appended in order. Each
+ * invocation is its own process and `beginPreview` resets this module's state,
+ * so the appends compose across them with no shared state or locking. */
 export interface CrtrPreviewRecord {
     path: string;
     result?: Record<string, unknown>;
@@ -17,7 +22,11 @@ export interface CrtrPreviewRecord {
  * stdout truncation never sees this channel. The mirror write is the one
  * choke point every record passes, so the bound lives here: an oversized
  * record is dropped, and the viewer falls back to rendering the agent-facing
- * stdout text, which pi bounds itself. */
+ * stdout text, which pi bounds itself.
+ *
+ * Because records accumulate, this bounds the FILE TOTAL, not one line: a
+ * record that would overrun the remaining budget is dropped whole, so every
+ * line on disk stays valid JSON. */
 export declare const PREVIEW_RESULT_MAX_BYTES: number;
 /** Begin collecting the current leaf's structured response, if its caller
  * supplied the private per-tool-call result path. */

package/dist/core/io.js

@@ -3,7 +3,7 @@
 // the model, not data it parses); structured errors; stderr is diagnostics only
 // and never carries the result. The raw JSON object is available behind the
 // `--json` global for tooling. See the cli-design reference.
-import { renameSync, writeFileSync } from 'node:fs';
+import { appendFileSync, statSync } from 'node:fs';
 import { CrtrError } from './errors.js';
 import { ExitCode } from '../types.js';
 import { PREVIEW_RESULT_PATH_ENV } from './preview-result-path.js';
@@ -19,7 +19,11 @@ let preview;
  * stdout truncation never sees this channel. The mirror write is the one
  * choke point every record passes, so the bound lives here: an oversized
  * record is dropped, and the viewer falls back to rendering the agent-facing
- * stdout text, which pi bounds itself. */
+ * stdout text, which pi bounds itself.
+ *
+ * Because records accumulate, this bounds the FILE TOTAL, not one line: a
+ * record that would overrun the remaining budget is dropped whole, so every
+ * line on disk stays valid JSON. */
 export const PREVIEW_RESULT_MAX_BYTES = 256 * 1024;
 /** Begin collecting the current leaf's structured response, if its caller
  * supplied the private per-tool-call result path. */
@@ -32,20 +36,15 @@ function publishPreview(record) {
     if (resultPath === undefined || resultPath === '')
         return;
     const line = `${JSON.stringify({ path: preview?.path ?? '', ...record })}\n`;
-    if (Buffer.byteLength(line, 'utf8') > PREVIEW_RESULT_MAX_BYTES)
-        return;
-    const tempPath = `${resultPath}.${process.pid}.tmp`;
     try {
-        writeFileSync(tempPath, line, 'utf8');
-        renameSync(tempPath, resultPath);
+        const spent = statSync(resultPath, { throwIfNoEntry: false })?.size ?? 0;
+        if (spent + Buffer.byteLength(line, 'utf8') > PREVIEW_RESULT_MAX_BYTES)
+            return;
+        appendFileSync(resultPath, line, 'utf8');
     }
     catch {
         // Preview transport is optional UI metadata. Its failure must never alter
         // the CLI's stdout/error contract.
-        try {
-            writeFileSync(tempPath, '', 'utf8');
-        }
-        catch { /* nothing to clean */ }
     }
 }
 /** Publish the single-object or collected JSONL result after leaf dispatch. */

package/dist/core/runtime/revive.js

@@ -230,10 +230,15 @@ function launchRevive(nodeId, meta, opts) {
     // fail deep inside the crash/doctrine-wake catch below, where it would
     // surface as an opaque `internal error` (toErrorBody masks every 5xx).
     if (!existsSync(meta.cwd)) {
+        const next = meta.fork_from != null
+            ? `Restore ${meta.cwd}, then revive the fork normally with \`crtr node lifecycle revive ${nodeId}\`.`
+            : meta.managed_worktree?.state === 'open'
+                ? 'Restore or reconcile the recorded checkout, then use the managed-worktree close or abandon recovery.'
+                : `Recreate ${meta.cwd}, or repair it with \`crtr node config --cwd <path> --node ${nodeId}\`; durable node work resumes in a fresh conversation. Then retry \`crtr node lifecycle revive ${nodeId}\`.`;
         throw new InputError({
             error: 'cwd_missing',
             message: `${nodeId} cannot be revived — its recorded cwd no longer exists: ${meta.cwd}`,
-            next: `Recreate ${meta.cwd}, or update the node's cwd, then retry \`crtr node lifecycle revive ${nodeId}\`.`,
+            next,
         });
     }
     // Lazy host_kind coerce (§C): every launch now uses the broker host. Persist

package/dist/core/substrate/surface-match.js

@@ -102,6 +102,10 @@ export function matchesMemoryReadEntry(entry, routingAnchor, subject, name) {
         return false;
     return entry.match.some((g) => memoryReadGlobMatches(g, routingAnchor, name));
 }
+/** Split a command into shell segments on unquoted `;`, newline, `&&`, `||`,
+ *  and `|`. A single `&`, subshell parentheses, and backticks are left inside
+ *  their segment — this is a best-effort guardrail, not a shell parser.
+ *  Heredoc bodies are a separate pre-match concern (see `stripHeredocs`). */
 function splitCommandSegments(command) {
     const segments = [];
     let current = '';
@@ -152,6 +156,7 @@ function splitCommandSegments(command) {
     finish();
     return segments;
 }
+/** Tokenize one segment into shell words, marking quoted spans opaque. */
 function tokenizeCommandSegment(segment) {
     const tokens = [];
     let text = '';
@@ -207,6 +212,8 @@ function tokenizeCommandSegment(segment) {
     finish();
     return tokens;
 }
+/** Every non-empty command segment as its env-stripped token list: leading
+ *  `VAR=value` assignments are dropped so `tokens[0]` is the executable. */
 function commandSegments(command) {
     return splitCommandSegments(command)
         .map(tokenizeCommandSegment)

package/dist/daemon/__tests__/autostart-storm.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/daemon/__tests__/autostart-storm.test.js

@@ -0,0 +1,166 @@
+import { test, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { DaemonStartupBlockedError, daemonAutostartSuppression, ensureDaemon, resetDaemonAutostart, verifyDaemonStartup, } from '../manage.js';
+import { DAEMON_EXIT_STARTUP_BLOCKED } from '../startup-policy.js';
+import { withExclusiveDirectoryLockAsync } from '../../core/exclusive-lock.js';
+// REGRESSION (daemon respawn storm): a daemon whose startup hit a STANDING
+// condition — a blocked on-disk migration — exited, its attach clients saw a
+// cold socket, autostarted a replacement, and that replacement hit the same
+// wall. Nothing tracked the repeat and nothing reaped the losers, so failed
+// starts accumulated into a pile that pegged the machine. Three properties keep
+// that from recurring: the terminal exit is TYPED, a typed failure SUPPRESSES
+// further autostarts, and an ordinary failure at least BACKS OFF.
+const settle = async () => { await new Promise((resolve) => setImmediate(resolve)); };
+// The test lane exports CRTR_NO_DAEMON_AUTOSTART=1 so no suite ever spawns a
+// real daemon. These tests drive ensureDaemon through injected deps — nothing
+// is spawned — so the guard has to come off for the gate under test to be
+// reachable at all.
+const autostartEnv = process.env['CRTR_NO_DAEMON_AUTOSTART'];
+beforeEach(() => {
+    delete process.env['CRTR_NO_DAEMON_AUTOSTART'];
+    resetDaemonAutostart();
+});
+after(() => {
+    if (autostartEnv === undefined)
+        delete process.env['CRTR_NO_DAEMON_AUTOSTART'];
+    else
+        process.env['CRTR_NO_DAEMON_AUTOSTART'] = autostartEnv;
+    resetDaemonAutostart();
+});
+test('the blocked-startup exit code surfaces as a typed terminal error, not a generic exit', async () => {
+    let exited = null;
+    const child = spawn(process.execPath, ['-e', `process.exit(${DAEMON_EXIT_STARTUP_BLOCKED})`], { stdio: 'ignore' });
+    child.once('exit', (code, signal) => {
+        exited = { code, signal };
+    });
+    await assert.rejects(async () => verifyDaemonStartup(77, 2_000, {
+        readPidfile: () => null,
+        isPidAlive: () => false,
+        isDaemonServing: async () => false,
+        childExited: () => exited,
+    }), (error) => {
+        assert.ok(error instanceof DaemonStartupBlockedError, 'must be typed, so the spawner can stop retrying');
+        assert.match(error.message, /crtr sys migrate/);
+        return true;
+    });
+});
+test('a blocked start suppresses every later autostart instead of respawning into the same wall', async () => {
+    let spawns = 0;
+    const deps = {
+        isDaemonRunning: () => false,
+        spawnDaemon: async () => {
+            spawns += 1;
+            throw new DaemonStartupBlockedError(4242);
+        },
+    };
+    ensureDaemon(deps);
+    await settle();
+    assert.equal(spawns, 1);
+    assert.match(daemonAutostartSuppression() ?? '', /crtr sys migrate/);
+    // The storm: every redial of every attach client lands here. None may spawn.
+    for (let i = 0; i < 50; i++)
+        ensureDaemon(deps);
+    await settle();
+    assert.equal(spawns, 1, 'a standing failure must never be retried');
+});
+test('an ordinary spawn failure backs off, then retries once the window passes', async () => {
+    let spawns = 0;
+    let now = 1_000_000;
+    const deps = {
+        isDaemonRunning: () => false,
+        now: () => now,
+        spawnDaemon: async () => {
+            spawns += 1;
+            throw new Error('dist/daemon/crtrd-cli.js missing');
+        },
+    };
+    ensureDaemon(deps);
+    await settle();
+    assert.equal(spawns, 1);
+    for (let i = 0; i < 20; i++)
+        ensureDaemon(deps);
+    await settle();
+    assert.equal(spawns, 1, 'retries inside the backoff window must be dropped');
+    now += 5_000;
+    ensureDaemon(deps);
+    await settle();
+    assert.equal(spawns, 2, 'the window expiring re-opens exactly one attempt');
+    // Backoff grows, so the second failure buys a longer quiet period than the first.
+    now += 5_000;
+    ensureDaemon(deps);
+    await settle();
+    assert.equal(spawns, 2, 'the second failure must back off further than the first');
+});
+test('a spawn already in flight blocks a concurrent autostart', async () => {
+    let spawns = 0;
+    let release = () => { };
+    const gate = new Promise((resolve) => { release = resolve; });
+    const deps = {
+        isDaemonRunning: () => false,
+        spawnDaemon: async () => {
+            spawns += 1;
+            await gate;
+            return { started: true, pid: 1 };
+        },
+    };
+    ensureDaemon(deps);
+    for (let i = 0; i < 10; i++)
+        ensureDaemon(deps);
+    await settle();
+    assert.equal(spawns, 1, 'concurrent callers must not each spawn a daemon');
+    release();
+    await settle();
+});
+test('a success clears the backoff so the next cold socket starts immediately', async () => {
+    let spawns = 0;
+    let fail = true;
+    let now = 1_000_000;
+    const deps = {
+        isDaemonRunning: () => false,
+        now: () => now,
+        spawnDaemon: async () => {
+            spawns += 1;
+            if (fail)
+                throw new Error('transient');
+            return { started: true, pid: 1 };
+        },
+    };
+    ensureDaemon(deps);
+    await settle();
+    fail = false;
+    now += 5_000;
+    ensureDaemon(deps);
+    await settle();
+    assert.equal(spawns, 2);
+    ensureDaemon(deps);
+    await settle();
+    assert.equal(spawns, 3, 'a healthy start must not leave a backoff behind');
+});
+// The pile pegged the machine because each waiter re-probed the lock every 10ms
+// with no backoff. Backing off must not make an uncontended hand-off sluggish.
+test('a contended lock waiter still acquires promptly once the holder releases', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'crtr-lock-backoff-'));
+    const lockPath = join(home, 'contended.lock');
+    try {
+        let released = 0;
+        const holder = withExclusiveDirectoryLockAsync(lockPath, async () => {
+            await new Promise((resolve) => setTimeout(resolve, 300));
+            released = Date.now();
+        }, { timeoutMs: 5_000 });
+        await new Promise((resolve) => setTimeout(resolve, 20));
+        let acquired = 0;
+        const waiter = withExclusiveDirectoryLockAsync(lockPath, async () => {
+            acquired = Date.now();
+        }, { timeoutMs: 5_000 });
+        await Promise.all([holder, waiter]);
+        assert.ok(acquired >= released, 'the waiter must not enter before the holder leaves');
+        assert.ok(acquired - released < 1_000, `hand-off took ${acquired - released}ms — backoff ceiling is too coarse`);
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});

package/dist/daemon/__tests__/integration/migration-startup.test.js

@@ -1,5 +1,5 @@
 import assert from 'node:assert/strict';
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, watch, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync, watch, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import test from 'node:test';
 import { onDiskMigrationIdentity } from '../../../migrations/registry.js';
@@ -52,7 +52,7 @@ test('source daemon migrates the pre-migration corpus and writes its marker befo
         assert.deepEqual(JSON.parse(readFileSync(markerPath, 'utf8')), onDiskMigrationIdentity());
         assert.equal(existsSync(fixture.pidfile), true, 'health readiness follows the pidfile readiness mirror');
         assert.equal(existsSync(fixture.socket), true, 'the unique unix API listener is bound at readiness');
-        assert.equal(existsSync(dbPath), true, 'daemon ownership opens canvas.db only after migration');
+        assert.equal(existsSync(dbPath), true, 'daemon ownership has opened canvas.db by readiness');
         assert.ok(statSync(markerPath).mtimeMs <= statSync(fixture.pidfile).mtimeMs, 'the completion marker is written no later than the readiness pidfile');
         assert.ok(statSync(markerPath).mtimeMs <= statSync(fixture.socket).mtimeMs, 'the completion marker is written no later than the API listener');
     }
@@ -62,7 +62,7 @@ test('source daemon migrates the pre-migration corpus and writes its marker befo
         assert.deepEqual(exit, { code: 0, signal: null }, `daemon must stop cleanly; stderr:\n${daemon.stderr()}`);
     }
 });
-test('a real migration blocker exits before database, pidfile, listeners, or broker effects', { timeout: 30_000 }, async () => {
+test('a real migration blocker exits before pidfile, listeners, or broker effects', { timeout: 30_000 }, async () => {
     const fixture = await createSourceDaemonFixture();
     const blockerPath = writeUserMemory(fixture.home, 'blocked.md', `---\nkind: knowledge\nbroken: [\n---\n# Blocked\n`);
     const effectNames = new Set();
@@ -82,14 +82,11 @@ test('a real migration blocker exits before database, pidfile, listeners, or bro
         assert.match(daemon.stderr(), new RegExp(blockerPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
         assert.match(daemon.stderr(), /Repair: crtr sys migrate/);
         assert.equal(wasReady, false, 'the unique TCP endpoint never answered health');
-        const databaseFiles = readdirSync(fixture.canvasHome).filter((name) => name.startsWith('canvas.db'));
-        assert.deepEqual(databaseFiles, [], 'canvas.db and its journals were never created');
         assert.equal(existsSync(fixture.pidfile), false, 'readiness pidfile was never created');
         assert.equal(existsSync(fixture.socket), false, 'unix API listener was never created');
         assert.equal(existsSync(join(fixture.canvasHome, 'on-disk-migrations.json')), false, 'blocker never gets a completion marker');
-        assert.equal(existsSync(join(fixture.canvasHome, 'nodes')), false, 'no node/broker state was created');
         assert.deepEqual(brokerPidsForCanvas(fixture.canvasHome), [], 'no broker process declares the isolated canvas');
-        assert.deepEqual([...effectNames].filter((name) => name.startsWith('canvas.db') || name === 'ready.pid' || name === 'crtrd.sock' || name === 'nodes'), [], `filesystem watcher saw no transient daemon effects (all events: ${[...effectNames].join(', ')})`);
+        assert.deepEqual([...effectNames].filter((name) => name === 'ready.pid' || name === 'crtrd.sock'), [], `filesystem watcher saw no transient readiness or broker effects (all events: ${[...effectNames].join(', ')})`);
     }
     finally {
         fixture.dispose();