@north-light/crouter 0.3.303 → 0.3.305

package/dist/daemon/api/__tests__/seam/api-server.test.js

@@ -26,7 +26,7 @@
 import { test, before, after } from 'node:test';
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
-import { statSync, existsSync, readFileSync, mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { chmodSync, statSync, existsSync, readFileSync, mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
 import WebSocket from 'ws';
@@ -133,6 +133,45 @@ test('A2: POST /nodes boots a live broker; GET /nodes/{id} shows active + live p
     assert.ok(meta?.pi_pid != null && isPidAlive(meta.pi_pid), 'row records a live broker pid');
     assert.ok(existsSync(h.brokerSock(id)), 'view.sock exists for the live broker');
 });
+function installBlockedStartHook(nodeId) {
+    const root = join(h.agentHome, '.crouter', 'plugins', `blocked-start-${nodeId}`);
+    const started = join(root, 'started');
+    const release = join(root, 'release');
+    mkdirSync(join(root, '.crouter-plugin'), { recursive: true });
+    writeFileSync(join(root, '.crouter-plugin', 'plugin.json'), JSON.stringify({
+        name: `blocked-start-${nodeId}`,
+        version: '0.1.0',
+        description: 'message acknowledgment fixture',
+        hooks: 'hooks.json',
+        hookExecutable: 'bin/hook.js',
+    }));
+    writeFileSync(join(root, 'hooks.json'), JSON.stringify({
+        schemaVersion: 2,
+        lifecycle: [{ event: 'node:start', phase: 'on', op: 'block', description: 'block target launch', effects: ['waits for test release'] }],
+    }));
+    const executable = join(root, 'bin', 'hook.js');
+    mkdirSync(join(root, 'bin'), { recursive: true });
+    writeFileSync(executable, `#!/usr/bin/env node
+const { existsSync, writeFileSync } = require('node:fs');
+let input = '';
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  const request = JSON.parse(input);
+  if (request.node.id !== ${JSON.stringify(nodeId)}) {
+    process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: true }));
+    return;
+  }
+  writeFileSync(${JSON.stringify(started)}, 'started');
+  const timer = setInterval(() => {
+    if (!existsSync(${JSON.stringify(release)})) return;
+    clearInterval(timer);
+    process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: true }));
+  }, 10);
+});
+`);
+    chmodSync(executable, 0o755);
+    return { started, release };
+}
 // A3 — POST .../messages appends inbox.jsonl; POST .../reports {tier:'final'}
 //      writes the report, notifies subscribers, transitions the row
 test('A3: messages append inbox.jsonl; final report writes + notifies subscriber + transitions row', async () => {
@@ -153,6 +192,36 @@ test('A3: messages append inbox.jsonl; final report writes + notifies subscriber
     assert.equal(h.node(B)?.status, 'done', 'row status is done after final');
     await assert.rejects(() => client.pushReport(B, { tier: 'final', delivery_tier: 'deferred', body: 'invalid tiered final' }), (error) => error instanceof ApiError && error.code === 'usage' && error.message === 'delivery_tier is only valid for update reports', 'the API rejects a delivery tier on final before it can alter final delivery');
 });
+test('A3b: a durable send acknowledges while the lifecycle tick is blocked launching its idle target', async () => {
+    const target = h.fabricateBrokerNode({ lifecycle: 'resident', status: 'idle', intent: 'idle-release' });
+    const hook = installBlockedStartHook(target);
+    const inboxFile = inboxPath(target);
+    const before = countLines(inboxFile);
+    const sending = client.sendMessage(target, { body: 'wake after durable acknowledgment' });
+    let tick;
+    try {
+        await h.waitFor(() => countLines(inboxFile) === before + 1, { label: 'durable inbox append' });
+        assert.equal(h.node(target)?.cycles ?? 0, 0, 'the send has not launched the target');
+        tick = h.tick();
+        await h.waitFor(() => existsSync(hook.started), { label: 'blocked lifecycle launch' });
+        const acknowledged = await Promise.race([
+            sending,
+            new Promise((_, reject) => setTimeout(() => reject(new Error('durable send waited for recipient launch')), 500)),
+        ]);
+        assert.equal(acknowledged.delivered, true, 'the API acknowledges the durable append');
+        assert.equal(acknowledged.revived, false, 'the response honestly reports no synchronous revive');
+        assert.equal(countLines(inboxFile), before + 1, 'exactly one inbox entry is durable while launch is blocked');
+        writeFileSync(hook.release, 'release');
+        await tick;
+        assert.equal(h.node(target)?.cycles, 1, 'the one queued entry drove lifecycle revival');
+        assert.equal(countLines(inboxFile), before + 1, 'revival did not append a second inbox entry');
+    }
+    finally {
+        if (!existsSync(hook.release))
+            writeFileSync(hook.release, 'release');
+        await tick;
+    }
+});
 // A4 — WS attach reconstructs the same settled broker snapshot as a direct
 //      ViewSocketClient; ?revive=0 on a dormant node → 409 without launching a broker
 test('A4a: WS attach welcome.snapshot is byte-identical to a direct ViewSocketClient snapshot', async () => {

package/dist/daemon/api/__tests__/seam/leaf-api-parity.test.js

@@ -19,7 +19,7 @@
 // in-process server exactly as a real `crtr push` CLI process would.
 import { test, before, after } from 'node:test';
 import assert from 'node:assert/strict';
-import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createHeadlessHarness } from '../../../../core/__tests__/helpers/harness.js';
@@ -87,16 +87,19 @@ async function runPushAs(caller, tier, body, input = {}) {
     }
 }
 // The `node worktree close` leaf, resolved from the real command tree exactly as
-// the CLI dispatcher would, and driven as the given caller node.
-async function runCloseAs(caller) {
+// the CLI dispatcher would.
+function closeLeaf() {
     const worktree = registerNode().children.find((c) => c.name === 'worktree');
     assert.ok(worktree !== undefined && worktree.kind === 'branch', 'node worktree branch resolves');
     const close = worktree.children.find((c) => c.name === 'close');
     assert.ok(close !== undefined && close.kind === 'leaf', 'node worktree close leaf resolves');
+    return close;
+}
+async function runCloseAs(caller) {
     const prev = process.env['CRTR_NODE_ID'];
     process.env['CRTR_NODE_ID'] = caller;
     try {
-        return (await close.run({}));
+        return (await closeLeaf().run({}));
     }
     finally {
         if (prev === undefined)
@@ -300,6 +303,35 @@ test('`crtr push final` keeps an absent managed worktree open when its branch is
         rmSync(repo, { recursive: true, force: true });
     }
 });
+test('`crtr node worktree close` warns with the retained stash SHA when base-checkout changes conflict (#1066)', async () => {
+    const repo = initRepo();
+    try {
+        writeFileSync(join(repo, 'conflict.txt'), 'base\n');
+        writeFileSync(join(repo, 'disjoint.txt'), 'base\n');
+        git(['add', '.'], repo);
+        git(['commit', '-m', 'tracked base files'], repo);
+        const id = 'wt-close-stash-warning';
+        const wt = createManagedWorktree(repo, id);
+        createNode(worktreeNode(id, wt.path, wt));
+        writeFileSync(join(wt.path, 'conflict.txt'), 'child\n');
+        git(['add', 'conflict.txt'], wt.path);
+        git(['commit', '-m', 'child conflict'], wt.path);
+        writeFileSync(join(repo, 'conflict.txt'), 'base live edit\n');
+        writeFileSync(join(repo, 'disjoint.txt'), 'disjoint live edit\n');
+        const out = await runCloseAs(id);
+        const stashSha = gitSync(['rev-parse', 'refs/stash'], repo).stdout.trim();
+        const rendered = closeLeaf().render?.(out) ?? '';
+        assert.match(out['base_checkout_stash'], new RegExp(`stash ${stashSha}`), 'the API result identifies the exact retained stash');
+        assert.match(rendered, new RegExp(`stash ${stashSha}`), 'the CLI output identifies the exact retained stash');
+        assert.match(rendered, new RegExp(`git -C '${realpathSync(repo)}' stash apply ${stashSha}`), 'the CLI output gives the exact recovery command');
+        assert.match(rendered, /shared base checkout was reset to landed commit/, 'the CLI output states that the shared checkout was reset');
+        assert.doesNotMatch(rendered, /nothing was lost/i, 'the CLI does not claim all concurrent work was preserved');
+        assert.equal(readFileSync(join(repo, 'disjoint.txt'), 'utf8'), 'base\n', 'the reset removes the disjoint live edit from the checkout but leaves it in the reported stash');
+    }
+    finally {
+        rmSync(repo, { recursive: true, force: true });
+    }
+});
 // `node worktree close` error parity — the SPECIFIC WorktreeError code + its
 // `next` remediation round-trip verbatim through the server → ApiError → the
 // bespoke CLI mapper in node-worktree.ts, instead of collapsing to a generic

package/dist/daemon/api/handlers/bash-jobs.js

@@ -59,7 +59,7 @@ async function handleStop(ctx) {
         throw new ApiError(404, 'job_not_found', `background job ${jobId} for ${nodeId} is no longer running`, { log_path: stopped.logPath });
     }
     if (stopped.kind === 'not-stoppable') {
-        throw new ApiError(409, 'job_not_stoppable', `job ${jobId} recorded no process group`, { log_path: stopped.logPath });
+        throw new ApiError(409, 'job_not_stoppable', `job ${jobId} recorded no trusted process identity`, { log_path: stopped.logPath });
     }
     // Match `crtr node bash kill`: retire the job, then send an urgent durable
     // notice to the owning node. The terminal path sends that notice through the

package/dist/daemon/api/handlers/messages.js

@@ -1,6 +1,7 @@
 // Message handler (spec §6.2). `POST /v1/nodes/{id}/messages` delivers an
 // inbox message now (201) or fresh-revives with no inbox entry. `{id}` is the
 // target node.
+import { join } from 'node:path';
 import { appendInbox, cancelPendingHumanMessages } from '../../../core/feed/inbox.js';
 import { reviveNode } from '../../../core/runtime/revive.js';
 import { BrokerUnreachableError } from '../../../core/runtime/broker-request.js';
@@ -8,14 +9,16 @@ import { isBrokerLive } from '../../../core/runtime/model-swap.js';
 import { deliverLive, interruptLive } from '../../../core/runtime/interactive-deliver.js';
 import { isProfilePaused } from '../../../core/profiles/manifest.js';
 import { getNode, withFreshTerminalGuard } from '../../../core/canvas/canvas.js';
+import { reportsDir } from '../../../core/canvas/paths.js';
 import { withCanvasWrite } from '../../../core/canvas/db.js';
 import { cancelCronsOnWake } from '../../../core/canvas/crons.js';
-import { assertNotFinalized, assertFinalizedForReopen, commitReopen, commitReopenResident, } from '../../../core/runtime/reopen.js';
+import { assertNotFinalized, assertFinalizedForReopen, commitReopenResident, } from '../../../core/runtime/reopen.js';
 import { writeOutputSchema } from '../../../core/runtime/structured-output.js';
 import { appendSituationalContext, formatSituationalProse } from '../../../core/runtime/situational-context.js';
 import { formatDataCard } from '../../../shared/generated-context.js';
 import { hasNoNaturalCycle } from '../../../core/runtime/revive-all.js';
 import { recordPendingParkActivity } from '../../park-pending.js';
+import { wantsExecution } from '../../reconcilers/node-lifecycle/wants-execution.js';
 import { hasFreshGroundState } from '../../../core/runtime/revive.js';
 import { notFound, usage } from '../../../core/errors.js';
 import { InputError } from '../../../core/io.js';
@@ -161,6 +164,12 @@ function parseSchema(raw) {
 function label(text) {
     return text.split('\n')[0].slice(0, 120);
 }
+function previousFinalReportCard(nodeId, finalReport) {
+    if (finalReport === null)
+        return '';
+    const path = join(reportsDir(nodeId), finalReport);
+    return formatDataCard('reopen-final-report', { path }, 'This node previously completed work. Read this final report before acting on the new instruction.');
+}
 /** The fail-loud rejection for a deferred immediate message aimed at a
  *  target with no natural cycle ahead of it (done/canceled/finalized). Thrown as
  *  an InputError so `toErrorBody` round-trips the FULL structured payload
@@ -211,7 +220,7 @@ async function handleMessage(ctx) {
         ? parseSchema(req.output_schema)
         : null;
     // Fresh revive: no inbox entry, resume:false (spec §7.7).
-    // Mirrors the CLI's immediate --fresh: validate/clear the finalization latch
+    // Mirrors the CLI's immediate --fresh: validate the finalization latch
     // (--reopen) and upsert the situational sidecar BEFORE the revive, so the
     // fresh kickoff picks up the update. The goal/roadmap recoverable-state guard
     // stays a pure CLI-side pre-check.
@@ -223,7 +232,7 @@ async function handleMessage(ctx) {
         if (hasSidecar)
             appendSituationalContext(id, sidecar);
         if (req.reopen)
-            commitReopen(id, expectedFinalReport);
+            commitReopenResident(id, expectedFinalReport);
         // A fresh revive appends no inbox entry, so nothing survives a freeze for
         // the daemon to act on later: at the cap the caller is told, not ignored.
         const result = await reviveNode(id, { resume: false, capacity: 'refuse' });
@@ -242,8 +251,9 @@ async function handleMessage(ctx) {
     // An interactive reopen commits before even choosing its engine-or-inbox
     // route. A live transport race then falls back with this same committed state.
     let reopenCommitted = false;
+    let previousFinalCard = '';
     if (req.delivery === 'interactive' && req.reopen) {
-        commitReopenResident(id);
+        previousFinalCard = previousFinalReportCard(id, commitReopenResident(id));
         reopenCommitted = true;
     }
     // --- Interactive delivery: route via the LIVE broker's serialized frame
@@ -257,7 +267,11 @@ async function handleMessage(ctx) {
             if (hasSidecar)
                 appendSituationalContext(id, sidecar);
             await deliverLive(id, req.body, {
-                cards: [...(hasSidecar ? [sidecar] : []), ...oneShotCards],
+                cards: [
+                    ...(previousFinalCard === '' ? [] : [previousFinalCard]),
+                    ...(hasSidecar ? [sidecar] : []),
+                    ...oneShotCards,
+                ],
                 // Same authorship the durable route would record for this send, so a
                 // reader cannot tell live from inbox delivery by the stamp.
                 origin: from === 'human'
@@ -294,9 +308,13 @@ async function handleMessage(ctx) {
         if (hasSidecar)
             appendSituationalContext(id, sidecar);
         if (req.reopen && !reopenCommitted) {
-            commitReopenResident(id);
+            previousFinalCard = previousFinalReportCard(id, commitReopenResident(id));
         }
-        const cards = oneShotCards.length > 0 ? { cards: oneShotCards } : {};
+        const cards = [
+            ...(previousFinalCard === '' ? [] : [previousFinalCard]),
+            ...oneShotCards,
+        ];
+        const cardData = cards.length > 0 ? { cards } : {};
         if (hasBody || schema !== null) {
             const messageBody = hasBody
                 ? req.body
@@ -306,7 +324,7 @@ async function handleMessage(ctx) {
                 tier,
                 kind: 'message',
                 label: label(messageBody),
-                data: { body: messageBody, ...(hasSidecar ? { situational: true } : {}), ...cards },
+                data: { body: messageBody, ...(hasSidecar ? { situational: true } : {}), ...cardData },
             });
         }
         // Context-only: a hidden wake marker excluded from the visible digest. Its
@@ -317,7 +335,7 @@ async function handleMessage(ctx) {
             tier,
             kind: 'message',
             label: hasSidecar ? '(ambient context updated)' : '(context delivered)',
-            data: { ...(hasSidecar ? { situational: true } : {}), situationalOnly: true, ...cards },
+            data: { ...(hasSidecar ? { situational: true } : {}), situationalOnly: true, ...cardData },
         });
     };
     // Deferred guard: a done/canceled/finalized target has no natural
@@ -355,13 +373,14 @@ async function handleMessage(ctx) {
     // owes a thaw; consume its deadline when that durable future wake arrives.
     if (entry.tier !== 'deferred' || meta.frozen_at !== null)
         cancelCronsOnWake(id);
-    // A wake-capable tier revives a dormant target so its inbox-watcher delivers
-    // this; deferred never wakes — it rides the target's next natural cycle. The
-    // APPENDED entry's tier decides, because a terminal target's deferred was
-    // already raised to a wake-capable tier by the append.
+    // A wake-capable entry for an active or idle target is admitted by the
+    // lifecycle tick. Reopen delivery preserves this handler's synchronous wake
+    // authority; a terminal-lifecycle row also needs it because it has no later
+    // natural cycle to consume the entry.
     let revived = false;
     let frozen = false;
-    if (entry.tier !== 'deferred' && !paused && !isBrokerLive(current)) {
+    const needsSynchronousWake = req.reopen || current.lifecycle === 'terminal' || !wantsExecution(current);
+    if (needsSynchronousWake && entry.tier !== 'deferred' && !paused && !isBrokerLive(current)) {
         try {
             // The entry is already durable, so a wake denied for capacity is only
             // delayed: the row freezes and the tick relaunches it — at which point

package/dist/daemon/api/handlers/reports.js

@@ -15,7 +15,8 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { getNode } from '../../../core/canvas/canvas.js';
 import { push, FinalizationError } from '../../../core/feed/feed.js';
-import { autoDropCleanManagedWorktree, branchIsPushedAtCurrentTip, hasOpenManagedWorktree, missingWorktreeRecoveryHint } from '../../../core/worktree.js';
+import { branchIsPushedAtCurrentTip, hasOpenManagedWorktree, missingWorktreeRecoveryHint } from '../../../core/worktree.js';
+import { autoDropCleanManagedWorktreeAsync } from '../../../core/worktree-mutation-async.js';
 import { reportsDir } from '../../../core/canvas/paths.js';
 import { notFound, usage } from '../../../core/errors.js';
 import { InputError } from '../../../core/io.js';
@@ -89,7 +90,7 @@ async function handlePush(ctx) {
 async function guardFinalWorktree(id) {
     if (!hasOpenManagedWorktree(getNode(id)))
         return undefined;
-    const dropped = autoDropCleanManagedWorktree(id);
+    const dropped = await autoDropCleanManagedWorktreeAsync(id);
     if (dropped !== null)
         return dropped.worktree_path;
     if (await branchIsPushedAtCurrentTip(getNode(id).managed_worktree))

package/dist/daemon/api/handlers/worktree.js

@@ -12,21 +12,22 @@
 // all of that onto `CrtrError` for every route that can raise it — so the CLI
 // leaf can reconstruct the original agent-facing contract instead of collapsing
 // to a generic status code.
-import { abandonManagedWorktree, closeManagedWorktree } from '../../../core/worktree.js';
+import { closeManagedWorktreeAsync } from '../../../core/worktree-close.js';
+import { abandonManagedWorktreeAsync } from '../../../core/worktree-mutation-async.js';
 import { listQuarantinedManagedWorktrees } from '../../../core/worktree-quarantine.js';
 import { usage } from '../../../core/errors.js';
-function handleWorktreeClose(ctx) {
+async function handleWorktreeClose(ctx) {
     const id = ctx.params['id'];
-    // No requireMeta: closeManagedWorktree already throws the precise
+    // No requireMeta: closeManagedWorktreeAsync already throws the precise
     // `unknown_node` / `no_managed_worktree` WorktreeError for a bad id.
-    return { status: 200, body: closeManagedWorktree(id) };
+    return { status: 200, body: await closeManagedWorktreeAsync(id) };
 }
-function handleWorktreeAbandon(ctx) {
+async function handleWorktreeAbandon(ctx) {
     const rawBy = ctx.body?.['by'];
     const by = typeof rawBy === 'string' ? rawBy.trim() : '';
     if (by === '')
         throw usage('abandon requires a non-empty invoking identity', { received: ctx.body, next: 'Pass the invoking node id or human identity.' });
-    return { status: 200, body: abandonManagedWorktree(ctx.params['id'], by) };
+    return { status: 200, body: await abandonManagedWorktreeAsync(ctx.params['id'], by) };
 }
 async function handleQuarantinedWorktrees() {
     return { status: 200, body: await listQuarantinedManagedWorktrees() };

package/dist/daemon/fleet.d.ts

@@ -2,7 +2,7 @@ import { type NodeMeta } from '../core/canvas/index.js';
 import { type FleetEntry, type FleetExitStatus, type FleetRegistry } from '../core/runtime/fleet.js';
 import type { NodeOutcomeDetailV1, TerminalReason } from '../core/canvas/types.js';
 import type { HostHandle } from '../core/runtime/host.js';
-export declare function surfaceBootFailure(meta: NodeMeta): Promise<void>;
+export declare function surfaceBootFailure(meta: NodeMeta, exitStatus?: FleetExitStatus): Promise<void>;
 /** Whether a dead relaunch should resume the saved session strictly, or retry
  *  as a fresh cycle instead. A cycling attempt (cycle_pending) that dies before
  *  session_start must retry AS a cycle: the fresh branch it was opening is not

package/dist/daemon/fleet.js

@@ -34,16 +34,18 @@ import { brokerThresholdsForDaemon } from '../core/runtime/fleet.js';
  *  When the daemon observes that death it errors LOUDLY up the spine: an
  *  urgent push so the parent learns the child failed to launch instead of just
  *  seeing a silent `dead`. */
-function bootFailureBody(meta) {
+function bootFailureBody(meta, exitStatus) {
+    const status = exitStatus === undefined
+        ? 'The daemon did not observe an exit status.'
+        : `The observed exit status was code ${exitStatus.code ?? 'null'}, signal ${exitStatus.signal ?? 'null'}.`;
     return (`⚠ Spawn failed — \`${meta.name}\` (${meta.kind}) never started.\n\n` +
         `Its pi vehicle exited before the session came up (no pi_session_id was ever ` +
-        `recorded), so the node produced no output. This is almost always a transient ` +
-        `launch failure — e.g. resource pressure when several nodes boot at once — not ` +
-        `a fault in the task itself.\n\n` +
-        `If the work still needs doing, re-spawn it; if spawns keep dying, spawn fewer at a time.`);
+        `recorded), so the node produced no output. ${status}\n\n` +
+        `Inspect canonical event diagnostics with \`crtr sys logs --node ${meta.node_id}\`.\n\n` +
+        `If the work still needs doing, re-spawn it.`);
 }
-export async function surfaceBootFailure(meta) {
-    await pushUrgent(meta.node_id, bootFailureBody(meta), { from: meta.node_id });
+export async function surfaceBootFailure(meta, exitStatus) {
+    await pushUrgent(meta.node_id, bootFailureBody(meta, exitStatus), { from: meta.node_id });
 }
 async function surfaceCrashLoop(meta) {
     const transportPoison = readTransportPoisonVerdict(meta.node_id);
@@ -137,6 +139,8 @@ export class DaemonFleet {
     /** Brokers deliberately interrupted by profile pause. This belongs to the
      * exact child, so a resume cannot turn its later SIGTERM exit into a crash. */
     #profilePauseInterruptions = new Set();
+    /** Exit status held only until dead-row policy surfaces this broker's boot failure. */
+    #exitStatuses = new Map();
     #lastCapacityLogAt = Number.NEGATIVE_INFINITY;
     constructor(opts) {
         this.#epoch = opts.epoch;
@@ -155,6 +159,7 @@ export class DaemonFleet {
             throw new Error(`fleet: refusing to register ${nodeId} with no pid`);
         }
         this.#reservations.delete(nodeId);
+        this.#exitStatuses.delete(nodeId);
         this.#map.set(nodeId, { pid: handle.pid, handle });
     }
     has(nodeId) {
@@ -215,6 +220,7 @@ export class DaemonFleet {
     forget(nodeId) {
         this.#map.delete(nodeId);
         this.#reservations.delete(nodeId);
+        this.#exitStatuses.delete(nodeId);
     }
     onChildExit(nodeId, status) {
         // The real child exit is the liveness boundary. Its queued observation only
@@ -225,6 +231,10 @@ export class DaemonFleet {
         const uptimeMs = Number.isFinite(launchedMs) ? Math.max(0, this.#now() - launchedMs) : null;
         const consecutiveFailures = meta?.respawn_failures ?? 0;
         this.#map.delete(nodeId);
+        if (meta?.status === 'done' || meta?.status === 'canceled' || meta?.status === 'dead')
+            this.#exitStatuses.delete(nodeId);
+        else
+            this.#exitStatuses.set(nodeId, status);
         this.#enqueue(() => this.#emitExitObserved(nodeId, status, uptimeMs, consecutiveFailures));
     }
     deliverExit(nodeId, status) {
@@ -232,7 +242,14 @@ export class DaemonFleet {
     }
     /** The node-lifecycle tick's enactment entry. */
     async applyDeadRowPolicy(nodeId) {
-        await this.#applyPolicy(nodeId);
+        const exitStatus = this.#exitStatuses.get(nodeId);
+        try {
+            await this.#applyPolicy(nodeId, exitStatus);
+        }
+        finally {
+            if (this.#exitStatuses.get(nodeId) === exitStatus)
+                this.#exitStatuses.delete(nodeId);
+        }
     }
     /** A revive refusal before its launch try/catch leaves the row active but
      *  with no fleet entry. Convert that otherwise-silent strand into the same
@@ -267,10 +284,10 @@ export class DaemonFleet {
             },
         });
     }
-    async #applyPolicy(nodeId) {
-        return this.#decideAndEnact(nodeId);
+    async #applyPolicy(nodeId, exitStatus) {
+        return this.#decideAndEnact(nodeId, exitStatus);
     }
-    async #decideAndEnact(nodeId) {
+    async #decideAndEnact(nodeId, exitStatus) {
         const meta = getNode(nodeId);
         if (meta !== null && isProfilePaused(meta.profile_id)) {
             clearRespawnPolicy(nodeId);
@@ -319,9 +336,10 @@ export class DaemonFleet {
                 await this.#terminalize(nodeId, meta, {
                     event: 'broker.boot.failed',
                     reason: 'boot_failed',
-                    detail: { schema: 'crtr.node-outcome-detail/v1', message: bootFailureBody(meta) },
+                    detail: { schema: 'crtr.node-outcome-detail/v1', message: bootFailureBody(meta, exitStatus) },
                     wake: `Child crashed — ${fullName(meta)} (${nodeId}) exited before its session ever came up and is now dead. ` +
                         `It stays dead until you revive it — \`crtr node lifecycle revive ${nodeId}\`.`,
+                    surface: () => surfaceBootFailure(meta, exitStatus),
                 });
                 break;
             case 'respawn-fresh':

package/dist/daemon/manage.d.ts

@@ -50,12 +50,14 @@ export interface SpawnDaemonResult {
     running?: true;
     /** Present with `running:true` when the Unix API socket is not serving. */
     serving?: false;
-    /** Recovery instruction for a live but non-serving daemon. */
-    next?: string;
+    /** The final `/healthz` probe failure when a live owner misses readiness. */
+    probe_error?: string;
 }
-/** True only when the mandatory Unix API socket answers `/healthz`. This is
- * deliberately separate from `isDaemonRunning()`: a pidfile remains useful for
- * identifying the process an operator must stop, but it is not readiness. */
+/** Make one `/healthz` observation without client-side recovery. The caller
+ * owns the availability window, so this probe cannot extend it. */
+export declare function probeDaemonServing(timeoutMs?: number): Promise<void>;
+/** True only when one mandatory Unix API socket probe answers `/healthz`.
+ * A pidfile identifies an owner; it is never readiness. */
 export declare function isDaemonServing(): Promise<boolean>;
 export interface DaemonWaitDeps {
     readPidfile?: () => number | null;
@@ -69,6 +71,7 @@ export interface DaemonStartupDeps extends DaemonWaitDeps {
         signal: NodeJS.Signals | null;
     } | null;
     isDaemonServing?: () => Promise<boolean>;
+    probeDaemonServing?: (timeoutMs: number) => Promise<void>;
 }
 /** Thrown when the spawned daemon exited on `DAEMON_EXIT_STARTUP_BLOCKED` — a
  *  standing condition (a blocked on-disk migration) that the very next spawn

package/dist/daemon/manage.js

@@ -19,7 +19,7 @@ import { clearDaemonStartupBlocked, daemonStartupBlocked } from './startup-block
 import { exclusiveLockOwnerPid } from '../core/exclusive-lock.js';
 import { onDiskMigrationLockPath } from '../core/canvas/paths.js';
 import { envNoDaemonAutostart } from '../shared/env.js';
-import { CrtrClient } from '../api/index.js';
+import { CrtrClient, waitForDaemonAvailability } from '../api/index.js';
 // Daemon env sanitization
 /** Env keys that must NEVER reach the daemon process. Restarting crtrd is
  *  overwhelmingly done from inside an agent node's own bash tool (`crtr sys
@@ -208,16 +208,20 @@ const DAEMON_VERIFY_POLL_MS = 10;
 /** A status/start readiness probe must not hang behind a daemon that accepts a
  * Unix connection but never answers it. */
 const DAEMON_HEALTH_PROBE_TIMEOUT_MS = 1_000;
-/** True only when the mandatory Unix API socket answers `/healthz`. This is
- * deliberately separate from `isDaemonRunning()`: a pidfile remains useful for
- * identifying the process an operator must stop, but it is not readiness. */
+/** Make one `/healthz` observation without client-side recovery. The caller
+ * owns the availability window, so this probe cannot extend it. */
+export async function probeDaemonServing(timeoutMs = DAEMON_HEALTH_PROBE_TIMEOUT_MS) {
+    const probeTimeoutMs = Math.min(timeoutMs, DAEMON_HEALTH_PROBE_TIMEOUT_MS);
+    const health = await CrtrClient.forLocalSocket({ autostart: false, timeoutMs: probeTimeoutMs }).probeHealthz(probeTimeoutMs);
+    if (!health.ok)
+        throw new Error('crtrd health check reported not ready');
+}
+/** True only when one mandatory Unix API socket probe answers `/healthz`.
+ * A pidfile identifies an owner; it is never readiness. */
 export async function isDaemonServing() {
     try {
-        const health = await CrtrClient.forLocalSocket({
-            autostart: false,
-            timeoutMs: DAEMON_HEALTH_PROBE_TIMEOUT_MS,
-        }).healthz();
-        return health.ok;
+        await probeDaemonServing();
+        return true;
     }
     catch {
         return false;
@@ -255,32 +259,47 @@ export async function verifyDaemonStartup(pid, timeoutMs = DAEMON_STARTUP_WINDOW
     const read = deps.readPidfile ?? readPidfile;
     const alive = deps.isPidAlive ?? isPidAlive;
     const exited = deps.childExited;
-    const serving = deps.isDaemonServing ?? isDaemonServing;
+    const serving = deps.isDaemonServing;
+    const probeServing = deps.probeDaemonServing ?? (async (remainingMs) => {
+        if (serving !== undefined) {
+            if (await serving())
+                return;
+            throw new Error('crtrd health check reported not ready');
+        }
+        await probeDaemonServing(remainingMs);
+    });
     const sleep = deps.sleepMs ?? sleepMs;
     const now = deps.now ?? Date.now;
-    const deadline = now() + timeoutMs;
-    while (now() <= deadline) {
-        const owner = read();
-        if (owner !== null && alive(owner) && await serving())
-            return owner === pid ? null : owner;
-        const exitState = exited?.();
-        if (exitState !== null && exitState !== undefined) {
-            if (exitState.signal !== null) {
-                throw new Error(`daemon ${pid} exited before becoming ready (by ${exitState.signal})`);
-            }
-            if (exitState.code === DAEMON_EXIT_STARTUP_BLOCKED) {
-                throw new DaemonStartupBlockedError(pid);
-            }
-            if (exitState.code !== 0) {
-                throw new Error(`daemon ${pid} exited before becoming ready (with exit code ${exitState.code ?? '?'})`);
+    let owner = null;
+    let terminalError = null;
+    await waitForDaemonAvailability({
+        windowMs: timeoutMs,
+        pollIntervalMs: DAEMON_VERIFY_POLL_MS,
+        now,
+        sleep,
+        retry: (error) => error !== terminalError,
+        probe: async (remainingMs) => {
+            const candidate = read();
+            if (candidate === null || !alive(candidate)) {
+                const exitState = exited?.();
+                if (exitState !== null && exitState !== undefined) {
+                    if (exitState.signal !== null)
+                        terminalError = new Error(`daemon ${pid} exited before becoming ready (by ${exitState.signal})`);
+                    else if (exitState.code === DAEMON_EXIT_STARTUP_BLOCKED)
+                        terminalError = new DaemonStartupBlockedError(pid);
+                    else if (exitState.code !== 0)
+                        terminalError = new Error(`daemon ${pid} exited before becoming ready (with exit code ${exitState.code ?? '?'})`);
+                    // A clean exit can have lost the ownership claim, so keep observing.
+                    if (terminalError !== null)
+                        throw terminalError;
+                }
+                throw new Error(`daemon ${pid} has no live pidfile owner`);
             }
-            // Clean code-0 exit: a possible ownership-claim loser, not readiness.
-            // Keep polling the same deadline for a different live pidfile owner; the
-            // loop's timeout throw below fires if none appears.
-        }
-        await sleep(DAEMON_VERIFY_POLL_MS);
-    }
-    throw new Error(`daemon ${pid} did not become ready within ${timeoutMs}ms`);
+            await probeServing(remainingMs);
+            owner = candidate;
+        },
+    });
+    return owner === pid ? null : owner;
 }
 /** Wait until a signaled daemon has exited and relinquished its pidfile. This
  *  makes a following start safe to claim the singleton rather than racing its
@@ -355,15 +374,19 @@ export async function stopDaemonProcess(pid, timeoutMs = DAEMON_SHUTDOWN_WINDOW_
 export async function spawnDaemon() {
     const recordedPid = readPidfile();
     if (recordedPid !== null && isPidAlive(recordedPid)) {
-        if (await isDaemonServing())
+        try {
+            await probeDaemonServing();
             return { started: false, existing_pid: recordedPid };
-        return {
-            started: false,
-            existing_pid: recordedPid,
-            running: true,
-            serving: false,
-            next: 'Run `crtr sys daemon stop` to release the non-serving daemon before starting it again.',
-        };
+        }
+        catch (error) {
+            return {
+                started: false,
+                existing_pid: recordedPid,
+                running: true,
+                serving: false,
+                probe_error: error.message,
+            };
+        }
     }
     // Ensure the canvas home directory exists so the daemon can write its pidfile.
     mkdirSync(crtrHome(), { recursive: true });