@north-light/crouter 0.3.253 → 0.3.255

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/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/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();

package/dist/daemon/crtrd-cli.js

@@ -3,6 +3,8 @@
 // raw fatal boundary; a winning daemon stays alive through its scheduled loop.
 import '../suppress-experimental-warnings.js';
 import { runDaemon } from './crtrd.js';
+import { MigrationBlockedError } from '../migrations/activation.js';
+import { DAEMON_EXIT_STARTUP_BLOCKED } from './startup-policy.js';
 import { envCrtrdTcp } from '../shared/env.js';
 /** Extract `--tcp <host:port>` (or `--tcp=<host:port>`) from argv; falls back to
  *  `CRTRD_TCP`. Absent → unix socket only (§4.1). */
@@ -16,4 +18,16 @@ function parseTcpArg(argv) {
     }
     return envCrtrdTcp();
 }
-await runDaemon({ tcp: parseTcpArg(process.argv.slice(2)) });
+// A blocked migration is the one startup failure that is guaranteed to recur.
+// Exit on its own code — with the repair line intact on stderr — so the
+// spawner suppresses further autostarts rather than respawning into the same
+// wall. Every other failure keeps reaching Node's raw fatal boundary.
+try {
+    await runDaemon({ tcp: parseTcpArg(process.argv.slice(2)) });
+}
+catch (error) {
+    if (!(error instanceof MigrationBlockedError))
+        throw error;
+    process.stderr.write(`[crtrd] startup blocked\n${error.message}\n`);
+    process.exit(DAEMON_EXIT_STARTUP_BLOCKED);
+}

package/dist/daemon/crtrd.js

@@ -316,7 +316,6 @@ export async function superviseTick(now = Date.now(), lifecycle = directTickLife
  *  quiesces admitted work, removes its readiness mirror, and releases its exact
  *  claim. */
 export async function runDaemon(opts = {}) {
-    await ensureOnDiskMigrations();
     const ownership = claimDaemonOwnership(randomBytes(16).toString('hex'));
     if (!ownership.claimed) {
         // A losing claim isn't always a singleton race: `own_identity_indeterminate`
@@ -338,6 +337,20 @@ export async function runDaemon(opts = {}) {
         return async () => { };
     }
     const claim = ownership.claim;
+    try {
+        await ensureOnDiskMigrations();
+    }
+    catch (migrationError) {
+        try {
+            const { released } = releaseDaemonOwnership(claim);
+            if (!released)
+                throw new Error('daemon ownership claim was not released');
+        }
+        catch (cleanupError) {
+            throw new AggregateError([migrationError, cleanupError], 'daemon startup failed and cleanup also failed');
+        }
+        throw migrationError;
+    }
     let admissionOpen = true;
     let interval;
     let laneTail = Promise.resolve();

package/dist/daemon/manage.d.ts

@@ -70,6 +70,13 @@ export interface DaemonStartupDeps extends DaemonWaitDeps {
     } | null;
     isDaemonServing?: () => Promise<boolean>;
 }
+/** Thrown when the spawned daemon exited on `DAEMON_EXIT_STARTUP_BLOCKED` — a
+ *  standing condition (a blocked on-disk migration) that the very next spawn
+ *  would hit identically. Callers must stop retrying and surface the repair;
+ *  the daemon has already written the detail to `crtrd.err`. */
+export declare class DaemonStartupBlockedError extends Error {
+    constructor(pid: number);
+}
 /** Tiny bounded post-spawn guard: wait for the daemon pidfile and live pid to
  *  appear before reporting success. This catches the "started:true but not yet
  *  plausibly alive" race without turning startup into a retry loop.
@@ -124,8 +131,22 @@ export declare function spawnDaemon(): Promise<SpawnDaemonResult>;
  *  explicit `crtr sys daemon start` calls `spawnDaemon` directly and is
  *  deliberately unaffected. */
 export declare function autostartDisabled(): boolean;
-/** Start the daemon if it is not already running. No-op if already up, or if
- *  autostart is suppressed for this invocation.
+/** Why implicit autostart is currently suppressed, or null when it is free to
+ *  run. Set only by a `DaemonStartupBlockedError`, which no retry can clear —
+ *  an explicit `crtr sys daemon start` still calls `spawnDaemon` directly and
+ *  reports the failure in full. */
+export declare function daemonAutostartSuppression(): string | null;
+/** Clear the suppression and the backoff — for a caller that has repaired the
+ *  standing condition and wants autostart live again without a new process. */
+export declare function resetDaemonAutostart(): void;
+export interface EnsureDaemonDeps {
+    isDaemonRunning?: () => boolean;
+    spawnDaemon?: () => Promise<SpawnDaemonResult>;
+    now?: () => number;
+}
+/** Start the daemon if it is not already running. No-op if already up, if
+ *  autostart is suppressed for this invocation, while an attempt is in flight,
+ *  or while backing off from a recent failure.
  *  Silently swallows spawn errors (the canvas still works without the daemon;
  *  nodes just won't be auto-revived). */
-export declare function ensureDaemon(): void;
+export declare function ensureDaemon(deps?: EnsureDaemonDeps): void;