@north-light/crouter 0.3.303 → 0.3.304

package/dist/core/worktree-sweep.js

@@ -21,6 +21,7 @@ import { resolve } from 'node:path';
 import { getNode, updateNode } from './canvas/index.js';
 import { withExclusiveDirectoryLockAsync } from './exclusive-lock.js';
 import { gitAsync } from './git.js';
+import { proveBranchContained, upstreamTip } from './worktree-containment.js';
 import { parseStatusPorcelain, planLandIntoCheckout, refDeleteTransactionStdin } from './worktree-landing.js';
 import { WORKTREE_LOCK_WAIT_MS, checkoutPathForBranchInList, persistClosedWorktreeState, samePath, worktreeLockPathForCommonDir } from './worktree.js';
 /** Escalating recheck interval, in minutes, indexed by consecutive refusal. The
@@ -101,95 +102,32 @@ function registeredCheckoutPath(porcelain, path, branch) {
     }
     return null;
 }
-/** Refs that could prove delivery: the recorded local base, and the base's
- *  upstream (a branch delivered by push rather than by a local land). */
-async function containmentCandidates(cwd, wt) {
-    const candidates = [];
-    const localBaseRef = `refs/heads/${wt.base_ref}`;
-    const localBase = await revParseRef(cwd, localBaseRef);
-    if (localBase !== null)
-        candidates.push({ ref: localBaseRef, sha: localBase });
-    const upstream = await gitAsync(['rev-parse', '--symbolic-full-name', '--verify', `${wt.base_ref}@{upstream}`], cwd);
-    const upstreamRef = upstream.status === 0 && upstream.stdout.trim().startsWith('refs/')
-        ? upstream.stdout.trim()
-        : `refs/remotes/origin/${wt.base_ref}`;
-    const upstreamSha = await revParseRef(cwd, upstreamRef);
-    if (upstreamSha !== null)
-        candidates.push({ ref: upstreamRef, sha: upstreamSha });
-    return candidates;
-}
-/** Does removing this branch lose content the candidate does not already have?
- *
- *  The invariant is about CONTENT, not history. A rebase rewrites every SHA, so
- *  a fully-landed branch can look diverged; a squash-merge leaves no matching
- *  commit at all. An ancestry-only proof would refuse exactly the cases this
- *  sweep exists to clean up, so three layers run in increasing cost, and any one
- *  of them is sufficient:
- *
- *  1. ancestry     — the tip is already reachable from the candidate.
- *  2. patch identity — every commit not in the candidate by SHA has a
- *                      patch-equivalent commit there (`git cherry`). The rebase case.
- *  3. content no-op  — merging the branch in would change nothing. The
- *                      squash-merge case, and most remaining "looks bad but isn't" states.
- *
- *  Only when all three fail does the branch genuinely carry unlanded content.
- *  Every layer fails CLOSED: a Git version without `merge-tree --write-tree`, an
- *  unreadable object, any non-zero exit — none of them prove anything, so the
- *  branch survives. */
-async function proveContained(cwd, wt, branchSha) {
-    const candidates = await containmentCandidates(cwd, wt);
-    if (candidates.length === 0)
-        return null;
-    for (const candidate of candidates) {
-        if ((await gitAsync(['merge-base', '--is-ancestor', branchSha, candidate.sha], cwd)).status === 0) {
-            return { containingRef: candidate.ref, containingSha: candidate.sha, layer: 'ancestry' };
-        }
-    }
-    for (const candidate of candidates) {
-        const cherry = await gitAsync(['cherry', candidate.sha, branchSha], cwd);
-        if (cherry.status !== 0)
-            continue;
-        const lines = cherry.stdout.split('\n').map((l) => l.trim()).filter((l) => l !== '');
-        if (lines.every((line) => line.startsWith('-'))) {
-            return { containingRef: candidate.ref, containingSha: candidate.sha, layer: 'patch_identity' };
-        }
-    }
-    for (const candidate of candidates) {
-        const candidateTree = await revParseRef(cwd, `${candidate.sha}^{tree}`);
-        if (candidateTree === null)
-            continue;
-        const merged = await gitAsync(['merge-tree', '--write-tree', candidate.sha, branchSha], cwd);
-        if (merged.status !== 0)
-            continue; // conflict, or a Git too old for this flag
-        if (merged.stdout.split('\n')[0]?.trim() === candidateTree) {
-            return { containingRef: candidate.ref, containingSha: candidate.sha, layer: 'content_noop' };
-        }
-    }
-    return null;
-}
+// Content containment is shared with explicit close. A delivered branch is
+// never rebased onto a local base merely because that base later diverged.
 // Change detection
-/** Base tip, branch tip, and checkout state as they are right now. A pass that
- *  reads the same three values as the refusal that preceded it can stop there:
- *  nothing that decided the refusal has moved. An unreadable checkout records
- *  `null`, which never compares equal, so uncertainty always re-proves. */
+/** Base, upstream, and branch tips plus checkout state as they are right now.
+ *  A pass that reads the same values as the refusal that preceded it can stop
+ *  there: nothing that decided the refusal has moved. An unreadable checkout
+ *  records `null`, which never compares equal, so uncertainty always re-proves. */
 async function observe(wt) {
     const present = existsSync(wt.path);
     const cwd = present ? wt.path : wt.repo_root;
     const base = await revParseRef(cwd, `refs/heads/${wt.base_ref}`);
+    const upstream = await upstreamTip(cwd, wt.base_ref);
     const branch = await revParseRef(cwd, `refs/heads/${wt.branch}`);
     if (!present)
-        return { base, branch, checkout: 'absent' };
+        return { base, upstream: upstream?.sha ?? null, branch, checkout: 'absent' };
     const head = await gitAsync(['rev-parse', 'HEAD'], wt.path);
     const status = await gitAsync(['status', '--porcelain'], wt.path);
     const checkout = head.status !== 0 || status.status !== 0
         ? null
         : createHash('sha256').update(`${head.stdout.trim()}\n${status.stdout}`).digest('hex');
-    return { base, branch, checkout };
+    return { base, upstream: upstream?.sha ?? null, branch, checkout };
 }
 function sameObservation(a, b) {
     if (a.checkout === null || b.checkout === null)
         return false;
-    return a.base === b.base && a.branch === b.branch && a.checkout === b.checkout;
+    return a.base === b.base && a.upstream === b.upstream && a.branch === b.branch && a.checkout === b.checkout;
 }
 // Recording an unfinished pass
 /** Persist why this pass did not finish, with the fingerprint it decided
@@ -336,13 +274,13 @@ export async function reconcileManagedWorktree(nodeId, guard, now = Date.now())
         return { status: 'skipped', reason: 'already_reconciled' };
     const cwd = existsSync(wt.path) ? wt.path : wt.repo_root;
     if (!existsSync(cwd)) {
-        return persistComplete(nodeId, wt, guard);
+        return finish(nodeId, wt, { status: 'refused', reason: 'repo_unavailable', detail: `neither the recorded checkout nor repository root exists, so ${wt.branch} cannot be proved absent` }, { base: null, upstream: null, branch: null, checkout: null }, now, guard);
     }
     const commonDir = await commonGitDirAsync(cwd);
     if (commonDir === null) {
-        return finish(nodeId, wt, { status: 'failed', reason: 'git_dir_unreadable', detail: `could not resolve the git common dir from ${cwd}` }, { base: null, branch: null, checkout: null }, now, guard);
+        return finish(nodeId, wt, { status: 'failed', reason: 'git_dir_unreadable', detail: `could not resolve the git common dir from ${cwd}` }, { base: null, upstream: null, branch: null, checkout: null }, now, guard);
     }
-    let observed = { base: null, branch: null, checkout: null };
+    let observed = { base: null, upstream: null, branch: null, checkout: null };
     let outcome;
     try {
         outcome = await withExclusiveDirectoryLockAsync(worktreeLockPathForCommonDir(commonDir), async () => {
@@ -412,7 +350,7 @@ async function concludeAbsentCheckout(nodeId, wt, observed, guard) {
     if (elsewhere !== null) {
         return { status: 'refused', reason: 'branch_checked_out_elsewhere', detail: `${wt.branch} is checked out at ${elsewhere}` };
     }
-    const proof = await proveContained(admin, wt, observed.branch);
+    const proof = await proveBranchContained(admin, wt, observed.branch);
     if (proof === null) {
         return { status: 'refused', reason: 'unlanded_work', detail: `${wt.branch} carries content no base or upstream ref contains; its checkout is already gone, so the branch is the only copy` };
     }
@@ -477,7 +415,7 @@ async function reconcilePresentCheckout(nodeId, wt, guard) {
         // is preserved, never deleted, unlike the ordinary path below.
         return persistComplete(nodeId, wt, guard);
     }
-    let proof = await proveContained(wt.path, wt, branchSha);
+    let proof = await proveBranchContained(wt.path, wt, branchSha);
     let stash;
     if (proof === null && wt.land_intent !== undefined) {
         const landed = await finishBlockedLand(wt, list.stdout, guard);
@@ -485,7 +423,7 @@ async function reconcilePresentCheckout(nodeId, wt, guard) {
             return landed.ineligible === true ? NODE_REVIVED : { status: 'refused', reason: 'land_blocked', detail: landed.detail };
         branchSha = landed.landedSha;
         stash = landed.stash;
-        proof = await proveContained(wt.path, wt, branchSha);
+        proof = await proveBranchContained(wt.path, wt, branchSha);
     }
     if (proof === null) {
         return { status: 'refused', reason: 'unlanded_work', detail: `${wt.branch} carries commits its base does not contain, and this node never asked to land them` };

package/dist/core/worktree.d.ts

@@ -14,6 +14,7 @@ export declare function managedWorktreesRoot(): string;
 export declare function managedWorktreePath(nodeId: string): string;
 export declare function hasOpenManagedWorktree(node: NodeMeta | null | undefined): boolean;
 export declare function openManagedWorktreeForNode(nodeId: string): ManagedWorktree | null;
+export declare function isManagedWorktreeBase(repoRoot: string): boolean;
 /** Shared parse for a `git worktree list --porcelain` blob already in hand —
  *  callers that must not throw on a read failure (an absent-path proof that
  *  needs to fail closed rather than error) call `gitSync` themselves and pass

package/dist/core/worktree.js

@@ -51,7 +51,7 @@ function repoRootFor(cwd) {
     }
     return result.stdout.trim();
 }
-function isManagedWorktreeBase(repoRoot) {
+export function isManagedWorktreeBase(repoRoot) {
     const path = relative(canonicalPath(managedWorktreesRoot()), canonicalPath(repoRoot));
     return path !== '' && path !== '..' && !path.startsWith(`..${sep}`) && !isAbsolute(path);
 }

package/dist/daemon/__tests__/integration/api-startup-readiness.test.js

@@ -49,15 +49,17 @@ test('a Unix socket bind failure rejects readiness and releases daemon ownership
         assert.equal(existsSync(pidfile), false, 'failed readiness removes the pidfile mirror');
         assert.equal(existsSync(socketPath), true, 'the pre-existing directory was never mistaken for a serving socket');
         assert.match(readFileSync(join(canvasHome, 'crtrd.log'), 'utf8'), /api\.server\.failed/, 'the bind failure is recorded for cold-start diagnostics');
+        rmSync(socketPath, { recursive: true, force: true });
         writeFileSync(pidfile, String(process.pid));
-        assert.deepEqual(await spawnDaemon(), {
-            started: false,
-            existing_pid: process.pid,
-            running: true,
-            serving: false,
-            next: 'Run `crtr sys daemon stop` to release the non-serving daemon before starting it again.',
-        }, 'start distinguishes a live non-serving pidfile owner from a serving daemon');
-        rmSync(pidfile, { force: true });
+        try {
+            const result = await spawnDaemon();
+            assert.deepEqual({ started: result.started, existing_pid: result.existing_pid, running: result.running, serving: result.serving }, { started: false, existing_pid: process.pid, running: true, serving: false }, 'a live owner with an unavailable socket remains in place');
+            assert.match(result.probe_error ?? '', /ENOENT|ECONNREFUSED/, 'the result retains the actual failed probe');
+            process.kill(process.pid, 0);
+        }
+        finally {
+            rmSync(pidfile, { force: true });
+        }
         const retryClaim = claimDaemonOwnership('post-api-bind-failure');
         assert.equal(retryClaim.claimed, true, 'failed readiness releases the authoritative ownership claim');
         if (retryClaim.claimed) {

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/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

@@ -16,6 +16,7 @@ import { appendSituationalContext, formatSituationalProse } from '../../../core/
 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';
@@ -355,13 +356,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