@north-light/crouter 0.3.303 → 0.3.304

package/dist/core/__tests__/seam/broker-startup-diagnostics.test.js

@@ -0,0 +1,82 @@
+// Run with: npm run build && node --test --test-timeout=180000 dist/core/__tests__/seam/broker-startup-diagnostics.test.js
+//
+// A refused broker launch, a broker fatal emitted before session_start, and a
+// SIGKILL all surface through canonical diagnostics. broker.log remains raw
+// stdout/stderr residue, so a canonical fatal need not write anything there.
+import { after, before, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { subscribe } from '../../canvas/canvas.js';
+import { resolveRef } from '../../canvas/history.js';
+import { readLogSnapshot } from '../../events/read.js';
+import { spawnChild } from '../../runtime/spawn.js';
+import { FAIL_BEFORE_SESSION_START } from '../fixtures/fake-engine.js';
+import { createHeadlessHarness } from '../helpers/harness.js';
+let h;
+let root;
+function eventsFor(nodeId) {
+    return readLogSnapshot({ nodeId }, false).items.flatMap((item) => item.kind === 'event' ? [item.envelope] : []);
+}
+function reportBody(entry) {
+    assert.ok(entry.ref, 'the boot-failure notification has a report reference');
+    const report = resolveRef(entry.ref);
+    assert.ok(report, 'the boot-failure notification report resolves');
+    return report.body;
+}
+before(async () => {
+    h = await createHeadlessHarness({ sessionPrefix: 'crtr-broker-startup-diagnostics' });
+    root = h.spawnRoot('broker startup diagnostics seam root');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+test('broker startup failures name canonical diagnostics, preserve launch errors, and report the observed exit status', { timeout: 60_000 }, async () => {
+    const refusedId = 'launch-refused';
+    const missingCwd = join(h.home, 'missing-cwd');
+    await assert.rejects(spawnChild({
+        kind: 'general',
+        cwd: missingCwd,
+        prompt: 'this launch must be refused by the operating system',
+        parent: root,
+        nodeId: refusedId,
+    }), (error) => {
+        const details = error.details;
+        assert.match(String(details?.next), new RegExp(`crtr sys logs --node ${refusedId}`));
+        return true;
+    });
+    const launchFailure = await h.waitFor(() => eventsFor(refusedId).find((event) => event.event === 'broker.launch.failed') ?? null, { label: 'canonical launch refusal' });
+    assert.match(launchFailure.error?.message ?? '', /ENOENT/, 'the canonical event preserves the operating-system launch error');
+    const refusedLog = join(h.home, 'nodes', refusedId, 'job', 'broker.log');
+    assert.equal(existsSync(refusedLog), true, 'the raw broker log exists for the refused launch');
+    assert.equal(readFileSync(refusedLog, 'utf8'), '', 'a launch refusal writes its diagnostic canonically, not as raw broker output');
+    const fatal = await spawnChild({
+        kind: 'general',
+        cwd: h.node(root).cwd,
+        prompt: `canonical fatal ${FAIL_BEFORE_SESSION_START}`,
+        parent: root,
+    });
+    const fatalId = fatal.node.node_id;
+    await h.awaitFleetExit(fatalId);
+    await h.tick();
+    const fatalEvent = eventsFor(fatalId).find((event) => event.event === 'broker.runtime.fatal');
+    assert.ok(fatalEvent, 'a pre-session broker fatal is available in canonical node diagnostics');
+    assert.match(fatalEvent.error?.message ?? '', /simulated pre-session_start boot failure/);
+    const fatalLog = join(h.home, 'nodes', fatalId, 'job', 'broker.log');
+    assert.equal(readFileSync(fatalLog, 'utf8'), '', 'a successfully emitted canonical fatal leaves raw broker.log empty');
+    const fatalNotice = h.inbox(root).find((entry) => entry.from === fatalId && entry.tier === 'urgent');
+    assert.ok(fatalNotice, 'the parent receives the fatal broker boot-failure notification');
+    assert.match(reportBody(fatalNotice), /code 1, signal null/);
+    assert.match(reportBody(fatalNotice), new RegExp(`crtr sys logs --node ${fatalId}`));
+    const exited = spawnSync(process.execPath, ['-e', ''], { stdio: 'ignore' });
+    assert.ok(exited.pid !== undefined, 'the fabricated boot failure has a recorded, dead pid');
+    const killedId = h.fabricateBrokerNode({ id: 'killed-before-session', parent: root, pi_pid: exited.pid });
+    subscribe(root, killedId, true);
+    await h.deliverExit(killedId, { code: null, signal: 'SIGKILL' });
+    await h.tick();
+    const killNotice = h.inbox(root).find((entry) => entry.from === killedId && entry.tier === 'urgent');
+    assert.ok(killNotice, 'the parent receives the SIGKILL boot-failure notification');
+    assert.match(reportBody(killNotice), /code null, signal SIGKILL/);
+});

package/dist/core/bash-jobs.d.ts

@@ -12,6 +12,9 @@ export interface BashJobPaths {
      * Inspector's cancel) — without it on disk, only the agent's own handoff
      * notice knows the group to signal. */
     jobPgid: string;
+    /** Launch-time identity of the detached supervisor, used to refuse a PID that
+     * has since been reused by an unrelated process. */
+    jobPgidIdentity: string;
     /** Human-readable label supplied with the bash call, when any. */
     jobPurpose: string;
     /** Epoch-ms cancel deadline for an AUTO-backgrounded job. Present only when
@@ -33,6 +36,9 @@ export declare function bashJobPaths(contextDir: string, jobId: string): BashJob
 /** The job's supervisor process group, or undefined for a job started before
  * pgid was persisted (or a partially-written dir). */
 export declare function readJobPgid(contextDir: string, jobId: string): number | undefined;
+/** Launch-time identity of the supervisor. Missing for jobs created before
+ * process-identity persistence, which are deliberately not safe to signal. */
+export declare function readJobPgidIdentity(contextDir: string, jobId: string): string | undefined;
 /** The optional human-readable job label. Jobs created before labels existed
  * have no file and deliberately project null. */
 export declare function readJobPurpose(contextDir: string, jobId: string): string | null;
@@ -73,6 +79,12 @@ export declare function clearJobDeadline(paths: BashJobPaths): void;
  *  means the group exists but cannot be signaled by this process; it is still
  *  live for the status surface. */
 export declare function isBashJobProcessGroupAlive(pgid: number): boolean;
+/** Best-effort cancellation for a detached bash supervisor. It snapshots the
+ * observable descendant tree while the supervisor is still alive, signals its
+ * leaves before their parents, then uses the shared identity-guarded KILL
+ * escalation. A descendant that detached and reparented before this snapshot
+ * is outside this guarantee. */
+export declare function cancelBashJobProcessTree(pgid: number, expectedIdentity: string): Promise<boolean>;
 export type StopBackgroundBashJobResult = {
     kind: 'stopped';
     signaled: boolean;
@@ -87,15 +99,15 @@ export type StopBackgroundBashJobResult = {
     kind: 'not-stoppable';
     logPath: string;
 };
-/** Stop one live background job using the same process-group and sentinel
- *  semantics as `crtr node bash kill`. The caller owns the user-facing
- *  notification; this primitive owns only the job control-plane mutation.
+/** Stop one live background job using the same best-effort tree cancellation
+ * semantics as inline abort and timeout. The caller owns the user-facing
+ * notification; this primitive owns only the job control-plane mutation.
  *
- *  Only a job in the live-background state the roster projects (job.bg
- *  present, job.exit absent) may be signaled. Job directories persist after
- *  the supervisor exits, so a retired, still-foreground, or already-stopped
- *  job would otherwise have its recorded pgid signaled long after the OS
- *  could have reused that id for an unrelated process group. */
+ * Only a job in the live-background state the roster projects (job.bg present,
+ * job.exit absent) may be signaled. Job directories persist after the
+ * supervisor exits, so a retired, still-foreground, or already-stopped job
+ * would otherwise have its recorded pgid signaled long after the OS could have
+ * reused that id for an unrelated process group. */
 export declare function stopBackgroundBashJob(contextDir: string, jobId: string): Promise<StopBackgroundBashJobResult>;
 /** Last `count` lines of a job log, cheaply: read at most the trailing 64 KiB
  * rather than the whole file, which for a long-running job can be enormous. */

package/dist/core/bash-jobs.js

@@ -5,6 +5,7 @@
 import { randomBytes } from 'node:crypto';
 import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { captureTeardownSnapshot, isAnyPidAlive, killProcessTreePids } from './canvas/pid.js';
 const MAX_BASH_JOB_PURPOSE_BYTES = 280;
 /** A purpose is display text, never shell input. Keep the file-backed control
  * plane to one bounded, visible line so old or hand-written job directories
@@ -41,6 +42,7 @@ export function bashJobPaths(contextDir, jobId) {
         jobBg: join(dir, 'job.bg'),
         jobDone: join(dir, 'job.done'),
         jobPgid: join(dir, 'job.pgid'),
+        jobPgidIdentity: join(dir, 'job.pgid-identity'),
         jobPurpose: join(dir, 'purpose'),
         jobDeadline: join(dir, 'job.deadline'),
     };
@@ -56,6 +58,17 @@ export function readJobPgid(contextDir, jobId) {
         return undefined;
     }
 }
+/** Launch-time identity of the supervisor. Missing for jobs created before
+ * process-identity persistence, which are deliberately not safe to signal. */
+export function readJobPgidIdentity(contextDir, jobId) {
+    try {
+        const identity = readFileSync(bashJobPaths(contextDir, jobId).jobPgidIdentity, 'utf8').trim();
+        return identity === '' ? undefined : identity;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** The optional human-readable job label. Jobs created before labels existed
  * have no file and deliberately project null. */
 export function readJobPurpose(contextDir, jobId) {
@@ -143,15 +156,31 @@ export function isBashJobProcessGroupAlive(pgid) {
         return err.code === 'EPERM';
     }
 }
-/** Stop one live background job using the same process-group and sentinel
- *  semantics as `crtr node bash kill`. The caller owns the user-facing
- *  notification; this primitive owns only the job control-plane mutation.
+/** Best-effort cancellation for a detached bash supervisor. It snapshots the
+ * observable descendant tree while the supervisor is still alive, signals its
+ * leaves before their parents, then uses the shared identity-guarded KILL
+ * escalation. A descendant that detached and reparented before this snapshot
+ * is outside this guarantee. */
+export async function cancelBashJobProcessTree(pgid, expectedIdentity) {
+    const snapshot = captureTeardownSnapshot(pgid, expectedIdentity);
+    if (snapshot.reused || snapshot.tree.length === 0)
+        return false;
+    const tree = [...snapshot.tree].reverse();
+    const signaled = isAnyPidAlive(tree);
+    killProcessTreePids(tree, 'SIGTERM', snapshot.identities);
+    await new Promise((resolve) => setTimeout(resolve, 400));
+    killProcessTreePids(tree, 'SIGKILL', snapshot.identities);
+    return signaled;
+}
+/** Stop one live background job using the same best-effort tree cancellation
+ * semantics as inline abort and timeout. The caller owns the user-facing
+ * notification; this primitive owns only the job control-plane mutation.
  *
- *  Only a job in the live-background state the roster projects (job.bg
- *  present, job.exit absent) may be signaled. Job directories persist after
- *  the supervisor exits, so a retired, still-foreground, or already-stopped
- *  job would otherwise have its recorded pgid signaled long after the OS
- *  could have reused that id for an unrelated process group. */
+ * Only a job in the live-background state the roster projects (job.bg present,
+ * job.exit absent) may be signaled. Job directories persist after the
+ * supervisor exits, so a retired, still-foreground, or already-stopped job
+ * would otherwise have its recorded pgid signaled long after the OS could have
+ * reused that id for an unrelated process group. */
 export async function stopBackgroundBashJob(contextDir, jobId) {
     const paths = bashJobPaths(contextDir, jobId);
     if (!existsSync(paths.dir))
@@ -159,7 +188,8 @@ export async function stopBackgroundBashJob(contextDir, jobId) {
     if (!existsSync(paths.jobBg) || existsSync(paths.jobExit))
         return { kind: 'retired', logPath: paths.jobLog };
     const pgid = readJobPgid(contextDir, jobId);
-    if (pgid === undefined)
+    const pgidIdentity = readJobPgidIdentity(contextDir, jobId);
+    if (pgid === undefined || pgidIdentity === undefined)
         return { kind: 'not-stoppable', logPath: paths.jobLog };
     // Claim the stop by creating job.exit exclusively, before signaling. The
     // loser of two concurrent stops — and a stop that races the supervisor's own
@@ -179,18 +209,7 @@ export async function stopBackgroundBashJob(contextDir, jobId) {
             return { kind: 'retired', logPath: paths.jobLog };
         throw err;
     }
-    let signaled = true;
-    try {
-        process.kill(-pgid, 'SIGTERM');
-    }
-    catch {
-        signaled = false;
-    }
-    await new Promise((resolve) => setTimeout(resolve, 400));
-    try {
-        process.kill(-pgid, 'SIGKILL');
-    }
-    catch { /* already gone */ }
+    const signaled = await cancelBashJobProcessTree(pgid, pgidIdentity);
     return { kind: 'stopped', signaled, pgid, logPath: paths.jobLog };
 }
 /** Last `count` lines of a job log, cheaply: read at most the trailing 64 KiB

package/dist/core/canvas/types.d.ts

@@ -76,11 +76,13 @@ export interface LaunchSpec {
     env: Record<string, string>;
 }
 /** The repository fingerprint a refusal was decided against. An examination
- *  that reads the same three values can skip the whole proof cascade: nothing
- *  about the refusal can have changed. */
+ *  that reads the same values can skip the whole proof cascade: nothing about
+ *  the refusal can have changed. */
 export interface ManagedWorktreeObservation {
     /** Tip of `refs/heads/<base_ref>`, or null when it no longer resolves. */
     base: string | null;
+    /** Tip of the base branch's upstream (or `origin/<base_ref>` fallback). */
+    upstream: string | null;
     /** Tip of `refs/heads/<branch>`, or null when the branch is gone. */
     branch: string | null;
     /** `absent`, or a hash of the checkout's HEAD plus `git status --porcelain`. */

package/dist/core/command.js

@@ -403,7 +403,7 @@ export async function parseArgv(params, tokens, options) {
                 continue;
             }
             const rawVal = inlineValue !== undefined ? inlineValue : tokens[++i];
-            if (rawVal === undefined || rawVal.startsWith('--')) {
+            if (rawVal === undefined || (inlineValue === undefined && rawVal.startsWith('--'))) {
                 const focusedNext = flagDef.focusedHelp !== undefined && (options?.leafPath?.length ?? 0) > 0
                     ? `Run \`crtr ${options.leafPath.join(' ')} --${flagName} -h\` and read the focused value contract before retrying.`
                     : undefined;

package/dist/core/fault-classifier.d.ts

@@ -1,5 +1,5 @@
 import type { ErrorClass, OperationId } from './events/types.js';
-export type FaultLink = 'pi→provider' | 'viewer↔broker' | 'relay↔broker' | 'viewer↔crtrd' | 'daemon→node' | 'crtr→pi';
+export type FaultLink = 'pi→provider' | 'viewer↔broker' | 'relay↔broker' | 'viewer↔crtrd' | 'broker↔crtrd' | 'daemon→node' | 'crtr→pi';
 export type FaultKind = 'rate-limit' | 'overloaded' | 'connection' | 'auth' | 'protocol' | 'context-overflow' | 'other' | 'wedged' | 'model-not-found';
 export type FaultRetryDisposition = 'auto' | 'manual' | 'fatal';
 export type FaultRetryOwner = 'sdk' | 'daemon' | 'client';

package/dist/core/runtime/broker/event-projection.d.ts

@@ -11,8 +11,6 @@ type EventProjectionDeps = {
     notifyTurnAccepted: () => void;
     emitStartupMilestone: (event: string, model: string | null) => void;
     formatModelSpec: (model: BrokerSession['model'], thinkingLevel?: string) => string | null;
-    refreshIntent: () => Promise<boolean>;
-    onRefreshIntentError: (error: unknown) => void;
 };
 /** Projects one live engine event stream to broker viewers and owns its relay timers. */
 export declare class EventProjection {
@@ -40,7 +38,6 @@ export declare class EventProjection {
     private flushPendingUpdate;
     private invalidatePendingBroadcasts;
     private broadcast;
-    private broadcastMessageEnd;
     private setPendingBroadcast;
 }
 export {};

package/dist/core/runtime/broker/event-projection.js

@@ -128,8 +128,8 @@ export class EventProjection {
             return;
         }
         this.flushPendingUpdate();
-        if (type === 'message_end') {
-            this.broadcastMessageEnd(event);
+        if (type === 'message_end' && generation.stagedRefreshAbort) {
+            this.broadcast({ ...event, message: withoutYieldAbort(event.message) });
             return;
         }
         this.broadcast(event);
@@ -183,19 +183,6 @@ export class EventProjection {
             this.deps.registry.broadcast(frame);
         }));
     }
-    broadcastMessageEnd(event) {
-        const preceding = this.pendingBroadcast ?? Promise.resolve();
-        const generation = this.broadcastGeneration;
-        this.setPendingBroadcast(preceding.then(async () => {
-            const refresh = await this.deps.refreshIntent();
-            if (this.broadcastGeneration !== generation)
-                return;
-            this.deps.registry.broadcast(refresh ? { ...event, message: withoutYieldAbort(event.message) } : event);
-        }).catch((error) => {
-            if (this.broadcastGeneration === generation)
-                this.deps.onRefreshIntentError(error);
-        }));
-    }
     setPendingBroadcast(work) {
         this.pendingBroadcast = work;
         void work.then(() => {

package/dist/core/runtime/broker/fault-retry.js

@@ -71,6 +71,14 @@ export class FaultRetry {
         // admitted retry therefore carries from its durable episode, while an
         // initial provider failure still reads from the ordinary marker.
         const prior = readFault(this.deps.nodeId);
+        // A persona gate runs before Pi contacts a provider. It records a typed
+        // local API transport failure, then Pi represents that thrown error as a
+        // generic provider-looking agent_end. Keep its actual boundary instead of
+        // turning it into a fatal pi→provider `other` fault.
+        if (prior?.link === 'broker↔crtrd' && prior.kind === 'connection') {
+            clearProviderRetryEpisode(this.deps.nodeId);
+            return;
+        }
         const durableEpisode = readProviderRetryEpisode(this.deps.nodeId);
         const episodeFault = this.isActiveAutoFault(prior) && prior.link === 'pi→provider'
             ? prior

package/dist/core/runtime/broker-persona-guidance.js

@@ -1,5 +1,7 @@
 import { contextDir } from '../canvas/paths.js';
+import { isDaemonTransportApiError } from '../../api/errors.js';
 import { emitEvent } from '../events/emit.js';
+import { clearFault, recordFault } from './fault.js';
 import { brokerExtensionState, commitBrokerPersonaAck } from './broker/daemon-ops.js';
 import { readRoadmap, roadmapPath } from './roadmap.js';
 import { buildSubPersonaMenu, renderConfigChangeDelta } from '../substrate/render.js';
@@ -137,9 +139,19 @@ export function installPersonaTransitionGate(nodeId, session) {
                 for (const context of new Set([active, messages, transformed]))
                     context.push(message);
             });
+            clearFault(nodeId, { link: 'broker↔crtrd' });
             return transformed;
         }
         catch (error) {
+            if (isDaemonTransportApiError(error)) {
+                recordFault(nodeId, {
+                    link: 'broker↔crtrd',
+                    op: 'persona transition',
+                    kind: 'connection',
+                    retry: { disposition: 'manual' },
+                    message: error.message,
+                });
+            }
             emitEvent({
                 event: 'broker.daemon.operation.failed',
                 level: 'error',

package/dist/core/runtime/broker.js

@@ -375,11 +375,6 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
         notifyTurnAccepted: () => notifyTurnAccepted(),
         emitStartupMilestone,
         formatModelSpec,
-        refreshIntent: async () => (await brokerExtensionState(nodeId)).node.intent === 'refresh',
-        onRefreshIntentError: (error) => {
-            emitEvent({ level: 'error', event: 'broker.daemon_state.read_failed', error });
-            disposeAndExit('daemon-state-read-failed', 1);
-        },
     });
     const buildSnapshot = (client) => {
         const liveSession = rebind.session();

package/dist/core/runtime/fault.js

@@ -31,7 +31,7 @@ function faultPriority(fault) {
         return 2;
     return 1;
 }
-const faultLinks = ['pi→provider', 'viewer↔broker', 'relay↔broker', 'viewer↔crtrd', 'daemon→node', 'crtr→pi'];
+const faultLinks = ['pi→provider', 'viewer↔broker', 'relay↔broker', 'viewer↔crtrd', 'broker↔crtrd', 'daemon→node', 'crtr→pi'];
 const faultKinds = ['rate-limit', 'overloaded', 'connection', 'auth', 'protocol', 'context-overflow', 'other', 'wedged', 'model-not-found'];
 function parseFault(raw) {
     try {

package/dist/core/runtime/host.js

@@ -319,7 +319,16 @@ export const headlessBrokerHost = {
                     });
                     finish({ code, signal });
                 });
-                spawned.once('error', () => finish({ code: null, signal: null }));
+                spawned.once('error', (error) => {
+                    emitEvent({
+                        level: 'error',
+                        event: 'broker.launch.failed',
+                        node_id: nodeId,
+                        error,
+                        fields: { uptime_ms: Date.now() - launchedAt },
+                    });
+                    finish({ code: null, signal: null });
+                });
             });
             spawned.unref();
             const handle = { pid: spawned.pid ?? null, exited };

package/dist/core/runtime/spawn.js

@@ -15,7 +15,7 @@ import { spawnNode, currentNodeContext, rootOfSpine, newNodeId, preflightNodeId
 import { resolveProfileOperand } from '../profiles/manifest.js';
 import { selectProfileForCwd, selectProfileForCwdReadOnly } from '../profiles/select.js';
 import { buildLaunchSpecAsync, buildPiArgv } from './launch.js';
-import { createManagedWorktree, rollbackManagedWorktree } from '../worktree.js';
+import { createManagedWorktreeAsync, rollbackManagedWorktreeAsync } from '../worktree-mutation-async.js';
 import { usage, brokerLaunchFailed } from '../errors.js';
 import { writeGoal } from './kickoff.js';
 import { appendSituationalContext, formatSituationalProse } from './situational-context.js';
@@ -25,7 +25,6 @@ import { encodeKickoffOrigin, KICKOFF_ORIGIN_ENV } from './stamp/protocol.js';
 import { canonicalSessionFile, contextDir, findNodeBySessionFile, getNode, fullName, recordPid, setFrozen } from '../canvas/index.js';
 import { boundFleet, brokerThresholdsForDaemon } from './fleet.js';
 import { emitEvent } from '../events/emit.js';
-import { jobDir } from '../canvas/paths.js';
 import { openViewerWindow, focusOf, windowOfPane, } from './placement.js';
 import { waitForBrokerViewSocket } from './placement-tmux.js';
 import { transition } from './lifecycle.js';
@@ -259,7 +258,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
     let spawnCwd = opts.cwd;
     try {
         if (wantsWorktree) {
-            managedWorktree = createManagedWorktree(opts.worktreeCwd ?? opts.cwd, nodeId, opts.worktreeBase);
+            managedWorktree = await createManagedWorktreeAsync(opts.worktreeCwd ?? opts.cwd, nodeId, opts.worktreeBase);
             spawnCwd = managedWorktree.path;
         }
         // Spine: a managed child reports up to its spawner (has a manager); an
@@ -409,7 +408,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
         if (placed.pid === null) {
             const error = new Error(`broker host returned no pid for ${meta.node_id}`);
             transition(meta.node_id, 'crash', { reason: 'launch_failed', outcome: launchFailureOutcome(error) });
-            throw brokerLaunchFailed(`failed to launch the broker engine for ${meta.node_id} (${meta.name}) — the node was not started.`, `Inspect the broker log for the underlying cause (${jobDir(meta.node_id)}/broker.log) and verify the pi engine can start in this environment.`);
+            throw brokerLaunchFailed(`failed to launch the broker engine for ${meta.node_id} (${meta.name}) — the node was not started.`, `Inspect canonical event diagnostics with \`crtr sys logs --node ${meta.node_id}\`, then verify the pi engine can start in this environment.`);
         }
         recordPid(meta.node_id, placed.pid);
         // A root created through `node new --root` must accept viewers before the
@@ -425,7 +424,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
                 ? `the root broker ${meta.node_id} could not start — ${why}`
                 : `the root broker ${meta.node_id} never bound its view socket — it was not started.`, why !== null
                 ? 'Resolve the cause named above, then retry.'
-                : `The broker engine exited before binding its view socket. Inspect ${jobDir(meta.node_id)}/broker.log for the underlying cause (a missing dependency, model auth, or a crash), then retry.`);
+                : `The broker engine exited before binding its view socket. Inspect canonical event diagnostics with \`crtr sys logs --node ${meta.node_id}\`, then retry.`);
         }
         // A --root opens NO viewer from here. spawnChild runs daemon-side only, and
         // the daemon is paneless by construction (manage.ts strips TMUX/TMUX_PANE
@@ -484,7 +483,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
         // worktree — the node stays alive (crashed, if the launch itself failed)
         // with its worktree intact rather than pinned to a deleted path.
         if (managedWorktree !== undefined && nodeId !== undefined && getNode(nodeId) === null) {
-            rollbackManagedWorktree(managedWorktree);
+            await rollbackManagedWorktreeAsync(managedWorktree);
         }
         throw err;
     }

package/dist/core/worktree-close.d.ts

@@ -0,0 +1,4 @@
+import { type CloseManagedWorktreeResult } from './worktree.js';
+/** Async daemon executor for explicit close. The lock wait and every Git
+ * subprocess yield to the daemon event loop. */
+export declare function closeManagedWorktreeAsync(nodeId: string): Promise<CloseManagedWorktreeResult>;