@north-light/api 0.3.579 → 0.3.587

package/dist/core/runtime/spawn.js

@@ -0,0 +1,699 @@
+// The spawn orchestration — the one place that turns "I want a node here" into
+// a running pi process on the canvas. Composes canvas (birth + spine), persona
+// (resolve), launch (pi argv), and tmux (placement).
+//
+//   spawnChild — a node spawned by a live node (`crtr node new`). A managed,
+//                terminal background worker by default; with `root`, an
+//                INDEPENDENT root (no subscription back to the spawner,
+//                provenance via spawned_by) — resident and brought forefront for
+//                direct driving, or, with `rootLifecycle: 'terminal'`, an
+//                unattended parentless worker that still owes a final (so it
+//                reaps) and is never placed on screen.
+import { accessSync, constants } from 'node:fs';
+import { isAbsolute, resolve, join } from 'node:path';
+import { appSpace } from '../layout.js';
+import { ApiError } from '../../api/errors.js';
+import { spawnNode, forkSourceNode, currentNodeContext, rootOfSpine, newNodeId, preflightNodeId } from './nodes.js';
+import { resolveProfileOperand } from '../profiles/manifest.js';
+import { selectProfileForCwd, selectProfileForCwdReadOnly } from '../profiles/select.js';
+import { buildLaunchSpecAsync, buildPiArgv } from './launch.js';
+import { runsOnBlaxel, sandboxWorktreeRequest } from '../../daemon/api/environment-of.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';
+import { ensureRoadmap } from './roadmap.js';
+import { buildWakeBearings } from './bearings.js';
+import { encodeKickoffOrigin, KICKOFF_ORIGIN_ENV } from './stamp/protocol.js';
+import { ExecutionCapReached, beginExecution, crtrHome, getNode, fullName, jobDir, recordExecutionPid, abortExecution, setFrozen } from '../canvas/index.js';
+import { contextDir, nodeAgentDir } from '../canvas/node-agent-paths.js';
+import { copyTreeBeneath } from '../spaces/open-beneath.js';
+import { conversationIdFromPath, conversationStore } from '../conversation-store/index.js';
+import { appMemoryTooSmall, boundFleet, brokerThresholdsForDaemon } from './fleet.js';
+import { admitBrokerMemory } from './memory-admission.js';
+import { emitEvent } from '../events/emit.js';
+import { blaxelEnvironmentOf } from './blaxel-environment.js';
+import { openViewerWindow, focusOf, windowOfPane, } from './placement.js';
+import { awaitBrokerViewSocket } from './view-socket.js';
+import { readLogSnapshot } from '../events/read.js';
+import { transition } from './lifecycle.js';
+import { beginBootFaultAttempt } from '../canvas/recovery.js';
+import { headlessBrokerHost } from './host.js';
+import { ensureDaemon } from '../../daemon/manage.js';
+import { readConfig } from '../config.js';
+import { modelRequestFromConfig, unregisteredConcreteModel, unroutableConcreteModel } from '../model-routes.js';
+import { openModelRegistry } from './model-registry.js';
+import { MODEL_SPEC_NEXT } from './model-selection.js';
+import { forkNodeLedger } from './ledger.js';
+import { appRungForGrant } from '../llm/app-rungs.js';
+import { APP_FAMILY } from '../model-routes.js';
+import { discoverLifecycleHookRegistry } from '../command-hooks/discovery.js';
+import { invokeLifecycleHooks } from '../command-hooks/transport/exec-lifecycle.js';
+import { someAsync } from '../async-array.js';
+import { checkStart } from './start-check.js';
+// Shared broker-launch wrapper — catch launch/preflight failures at the call
+// site, mark the node crashed, then rethrow a clear error.
+function launchFailureOutcome(error) {
+    return {
+        detail: {
+            schema: 'crtr.node-outcome-detail/v1',
+            message: error instanceof Error ? error.message : String(error),
+        },
+    };
+}
+async function launchBrokerOrCrash(nodeId, inv, opts) {
+    try {
+        return await headlessBrokerHost.launch(nodeId, inv, opts);
+    }
+    catch (error) {
+        try {
+            await transition(nodeId, 'crash', { reason: 'launch_failed', outcome: launchFailureOutcome(error) });
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        // A named error (not a bare `new Error`): this is the ONLY signal the
+        // preflight cause (bad engine resolve, missing session file, extension
+        // rejection) has to travel up. Left as a plain Error it collapses to a
+        // causeless 500 `internal` across crtrd; named, it surfaces verbatim.
+        // The underlying messages (from host.ts preflight) already carry the
+        // `[broker] refusing to launch <id>:` lead, so re-surface them as-is
+        // rather than double-prefixing the now caller-visible text.
+        const cause = error.message;
+        throw brokerLaunchFailed(cause.startsWith('[broker]') ? cause : `[broker] refusing to launch ${nodeId}: ${cause}`, 'Inspect the cause above, fix the launch recipe or environment, then retry.');
+    }
+}
+/** The last `broker.startup.*` step a freshly created root broker logged, or null when it logged none (it never got
+ *  as far as binding its event source). */
+function lastStartupStep(nodeId) {
+    const steps = readLogSnapshot({ nodeId, component: 'broker', pattern: 'broker.startup.' }, false).items
+        .flatMap((item) => item.kind === 'event' && item.envelope.event.startsWith('broker.startup.') && item.envelope.event !== 'broker.startup.warning'
+        ? [item.envelope.event.slice('broker.startup.'.length)]
+        : []);
+    return steps.at(-1) ?? null;
+}
+/** Say how a root broker's readiness wait ended: who ended it (the broker's own exit, or the launcher's deadline) and
+ *  the last startup step the broker logged before that. */
+function notReadyDescription(nodeId, wait) {
+    const step = lastStartupStep(nodeId);
+    const reached = step === null ? 'it had logged no startup step' : `the last startup step it logged was \`${step}\``;
+    if (wait.reason === 'exited') {
+        const { code, signal } = wait.status;
+        return {
+            text: `exited (code ${code ?? 'null'}, signal ${signal ?? 'null'}) before binding its view socket; ${reached}`,
+            fields: { reason: 'exited', code, signal, last_startup_step: step },
+        };
+    }
+    return {
+        text: `was still starting after ${Math.round(wait.waitedMs / 1000)} s without binding its view socket, so the launcher stopped it; ${reached}`,
+        fields: { reason: 'timeout', waited_ms: wait.waitedMs, last_startup_step: step },
+    };
+}
+/** A readiness failure must never leave a broker able to bind behind a dead row. */
+async function crashAndTearDown(nodeId, error) {
+    try {
+        // Mark dead before touching the process so daemon supervision cannot revive it.
+        await transition(nodeId, 'crash', { reason: 'launch_failed', outcome: launchFailureOutcome(error) });
+    }
+    catch {
+        /* preserve teardown even if lifecycle reconciliation already happened */
+    }
+    try {
+        void headlessBrokerHost.teardown(nodeId);
+    }
+    catch {
+        /* host teardown is best-effort; the launch failure remains authoritative */
+    }
+}
+/** Resolve a bare/partial pi session uuid to its ABSOLUTE `.jsonl` path by
+ *  scanning pi's sessions store the way pi's own CLI does (exact id, else a
+ *  unique prefix). The broker fork seam (`SessionManager.forkFrom`) loads a FILE
+ *  and does NOT resolve a uuid, so a bare id must be resolved here or the fork
+ *  throws at boot. Session files are `<sessions>/<project>/<ts>_<id>.jsonl`. */
+async function resolveSessionUuid(uuid) {
+    const matches = (await conversationStore().list()).map(({ conversation_id, path }) => ({ id: conversation_id, path }));
+    const exact = matches.filter((m) => m.id === uuid);
+    const hit = exact.length > 0 ? exact : matches.filter((m) => m.id.startsWith(uuid));
+    if (hit.length === 0) {
+        throw usage(`--fork-from '${uuid}': no pi session with that id found.`, {
+            next: 'Pass a live node id, a real session uuid/prefix, or an absolute .jsonl session path.',
+        });
+    }
+    if (hit.length > 1) {
+        throw usage(`--fork-from '${uuid}': ambiguous — ${hit.length} sessions match that id prefix; pass the full id or the .jsonl path.`, {
+            next: 'Pass the full session uuid or an absolute .jsonl path to disambiguate.',
+        });
+    }
+    return hit[0].path;
+}
+/** Resolve a `--fork-from` value to an ABSOLUTE `.jsonl` source path for the
+ *  broker fork (`SessionManager.forkFrom`, which loads a file — never a bare id).
+ *  A live node id resolves to its captured session FILE (absolute, cwd-immune); a
+ *  relative path is made absolute; a bare/partial uuid is resolved against pi's
+ *  sessions store. Throws when a known node has no captured session file, or when
+ *  a uuid resolves to zero or multiple sessions. */
+export async function resolveForkSource(value) {
+    const v = value.trim();
+    if (v === '')
+        throw usage('--fork-from requires a node id, session file, or session uuid.', { next: 'Pass a live node id, an absolute .jsonl session path, or a session uuid/prefix.' });
+    // A path (contains `/` or ends `.jsonl`) is a session file — ensure it is
+    // ABSOLUTE so the broker, launched in a different cwd, still resolves it.
+    if (v.includes('/') || v.endsWith('.jsonl')) {
+        const id = conversationIdFromPath(isAbsolute(v) ? v : resolve(process.cwd(), v));
+        if (id === null)
+            throw usage(`--fork-from '${v}': invalid conversation path.`, { next: 'Pass a conversation file path or id.' });
+        return (await conversationStore().header(id)).path;
+    }
+    // A live node id — fork from the conversation it has accumulated. Its captured
+    // session FILE is absolute; the broker cannot fork a bare session id.
+    const n = await getNode(v);
+    if (n !== null) {
+        const src = n.pi_session_file;
+        if (src === undefined || src === null || src === '') {
+            throw usage(`node ${v} has no pi session yet — it has not captured a session FILE to fork from (the broker forks a .jsonl path, not a bare id).`, {
+                next: 'Pick a node that has captured a session, or drop --fork-from.',
+            });
+        }
+        const id = conversationIdFromPath(src);
+        if (id === null)
+            throw usage(`node ${v} has no valid conversation id.`, { next: 'Pick a node with a captured conversation.' });
+        return (await conversationStore().header(id)).path;
+    }
+    // Not a known node — a bare/partial pi session uuid; resolve it to an absolute
+    // .jsonl (the broker fork won't resolve a uuid).
+    return await resolveSessionUuid(v);
+}
+/** Resolve the profile a spawned child runs under: an explicit `--profile`
+ *  operand (id, name, or closest match) resolved through `resolveProfileOperand`, else INHERIT
+ *  the spawner's current `profile_id` (null when the spawner has none). `--root`
+ *  never resets this to null on its own; only an explicit override does. When
+ *  there is NO spawner at all — `crtr node new --root` run directly from a
+ *  shell, not from inside a node — there is no profile to inherit, so this runs
+ *  the same startup selector the front door uses (MRU covering `cwd`, else the
+ *  root-profile prompt/default). */
+export async function resolveProfileId(explicit, spawner, cwd, options = {}) {
+    if (explicit === null)
+        return null;
+    if (explicit !== undefined && explicit !== '') {
+        // `explicit` originates as a user-typed `--profile`, so tolerate a near
+        // miss. The CLI normally resolves it to an id first; this covers callers
+        // that reach the daemon with a name.
+        return resolveProfileOperand(explicit).profileId;
+    }
+    if (spawner !== null)
+        return (await getNode(spawner))?.profile_id ?? null;
+    return options.readOnlySelection === true
+        ? selectProfileForCwdReadOnly(cwd)
+        : selectProfileForCwd(cwd);
+}
+function requestFromLaunch(launch) {
+    const intent = launch.modelIntent === undefined
+        ? undefined
+        : `${launch.modelIntent.family}/${launch.modelIntent.strength}`;
+    return modelRequestFromConfig(launch.model, intent, launch.modelExact === true);
+}
+/** Under an app-paid grant (RT-RTE-24) the node's model is the app rung resolver's choice, never the owner's ladder: the
+ *  recipe records the rung's catalog model and the intent `app/<strength>`. A user-paid grant leaves the recipe as built. */
+export async function appPaidLaunch(launch, grantId, requested) {
+    const ask = requested ?? (launch.modelIntent ? `${launch.modelIntent.family}/${launch.modelIntent.strength}` : launch.model);
+    const rung = await appRungForGrant(grantId, ask, launch.modelExact === true);
+    if (rung === null)
+        return launch;
+    const { CRTR_MODEL_INTENT: _owner, ...env } = launch.env ?? {};
+    return { ...launch, model: rung.model, modelIntent: { family: APP_FAMILY, strength: rung.strength }, modelExact: undefined, env: { ...env, CRTR_MODEL_INTENT: `${APP_FAMILY}/${rung.strength}` } };
+}
+/** Reject a permanently invalid launch recipe against the registry that will
+ * serve it. Registered-but-unauthenticated/cooling requests intentionally pass
+ * this authoring check so broker policy for transient availability is unchanged. */
+export async function assertLaunchModelRegistered(request, options, registry) {
+    if (request === undefined)
+        return;
+    // An app-paid recipe is logical (`app/<strength>`) but names a catalog model: the catalog entry is the whole check.
+    if (request.kind === 'logical' && request.family !== APP_FAMILY)
+        return;
+    const unknown = await unregisteredConcreteModel(request.kind === 'logical' ? { kind: 'concrete', spec: request.spec } : request, registry ?? await openModelRegistry(), options);
+    if (unknown !== undefined) {
+        throw usage(`model '${unknown.request.spec}' is not registered in this daemon.`, {
+            received: unknown.request.spec,
+            next: MODEL_SPEC_NEXT,
+        });
+    }
+    const unroutable = await unroutableConcreteModel(request, options);
+    if (unroutable !== undefined) {
+        throw usage(`model '${unroutable.spec}' is registered but no configured model route offers it, so no turn could be served.`, {
+            received: unroutable.spec,
+            next: `Pick a model from your configured routes (\`crtr sys config get modelLadders\`), or add this one to a ladder or route.`,
+        });
+    }
+}
+/** Resolve who a spawn is attributed to. A managed child needs a spine parent
+ *  (explicit `--parent` or the calling node's CRTR_NODE_ID). A --root spawn
+ *  does not: it is top-level by definition and the spawner identity is
+ *  provenance only — a human shell with no CRTR_NODE_ID is a legitimate root
+ *  spawner, so `crtr node new --root` from outside a node must not throw. */
+export function resolveSpawner(parent, ctxNodeId, root) {
+    const spawner = parent ?? ctxNodeId ?? null;
+    if (!root && spawner === null) {
+        throw new Error('spawnChild requires a calling node (CRTR_NODE_ID) or an explicit parent');
+    }
+    return spawner;
+}
+export async function spawnChildPrepared(opts, beforeBrokerLaunch, afterNodeCreated) {
+    try {
+        ensureDaemon();
+    }
+    catch { /* daemon is best-effort */ }
+    const ctx = currentNodeContext();
+    const root = opts.root === true;
+    const spawner = resolveSpawner(opts.parent, ctx.nodeId ?? null, root);
+    const mode = opts.mode ?? 'base';
+    // Roots are resident by default; managed children are terminal workers by
+    // default. The one lifecycle option deliberately applies to both shapes so a
+    // child can be born as a standing, wakeable conversation too.
+    const lifecycle = opts.rootLifecycle ?? (root ? 'resident' : 'terminal');
+    const attendedRoot = root && lifecycle === 'resident';
+    // Born WITHOUT a name — the canvas-goal-capture extension names it async from
+    // its first message (the kickoff task) inside its own pi process, so spawn
+    // never blocks on the LLM naming round-trip (a 2-3s freeze).
+    const spawnerNode = spawner === null ? null : await getNode(spawner);
+    const creatorNode = opts.creator === undefined || opts.creator === null ? null : await getNode(opts.creator);
+    if (opts.nodeId !== undefined)
+        await preflightNodeId(opts.nodeId);
+    const forkFrom = opts.forkFrom !== undefined ? await resolveForkSource(opts.forkFrom) : undefined;
+    const forkSourceMeta = forkFrom === undefined ? null : await forkSourceNode(forkFrom);
+    const isolatedAncestor = (await someAsync([spawnerNode, creatorNode, forkSourceMeta], async (source) => source?.isolated === true ||
+        (source?.run_id != null && (await getNode(source.run_id))?.isolated === true)));
+    if (isolatedAncestor && opts.isolated === false) {
+        throw new ApiError(403, 'isolated_run', 'isolation cannot be turned off under an isolated run', { param: 'isolated' });
+    }
+    const isolated = isolatedAncestor || opts.isolated === true;
+    if (isolated && opts.worktree === true) {
+        throw new ApiError(400, 'invalid_request', 'isolated nodes cannot use a worktree', { param: 'worktree' });
+    }
+    const wantsWorktree = opts.worktree === true;
+    const nodeId = isolated || wantsWorktree ? (opts.nodeId ?? await newNodeId()) : opts.nodeId;
+    // Isolation pins each node to its own folder before resolving the launch
+    // recipe; the application files directory must never become its cwd.
+    const birthCwd = isolated
+        ? (opts.run !== undefined && root && !isolatedAncestor ? opts.cwd : join(appSpace(opts.run?.grantee ?? spawnerNode?.grantee ?? 'app:terminal').nodes, nodeId))
+        : opts.cwd;
+    // Preflight: resolve every fallible input BEFORE creating the worktree or the
+    // node. `--fork-from <bad>` (resolveForkSource), an invalid `--profile`
+    // (resolveProfileId), and an unregistered concrete `--model` must fail HERE,
+    // before anything exists to clean up or
+    // strand — catching them later (after the worktree/node are created) is what
+    // let `--worktree --fork-from <bad>` leave an active node pinned to a deleted
+    // cwd with an open managed_worktree. A caller-supplied `--node-id` joins this
+    // preflight for the same reason: a malformed or already-taken id must fail
+    // BEFORE createManagedWorktree runs below, or a duplicate/bad id leaks a
+    // registered worktree that the failure catch below then can't clean up
+    // (getNode(nodeId) already resolves non-null for the pre-existing conflicting
+    // node, which the catch's cleanup guard reads as "keep it"). This is a
+    // best-effort check only — spawnNode's synchronous check-then-create right
+    // before node creation remains the sole authoritative race decider.
+    const profileId = await resolveProfileId(opts.profile, spawner, birthCwd);
+    const launchGrant = opts.run?.grant_id ?? spawnerNode?.grant_id ?? null;
+    const preflightLaunch = await appPaidLaunch((await buildLaunchSpecAsync(opts.kind, mode, {
+        lifecycle, hasManager: !root, model: opts.model, modelOverride: opts.model !== undefined, cwd: birthCwd, profileId,
+    })).launch, launchGrant, opts.model);
+    await assertLaunchModelRegistered(requestFromLaunch(preflightLaunch), { cwd: birthCwd, profileId });
+    // The start check, before any worktree or node row exists: a refusal leaves nothing behind. The payer is the identity the
+    // node will carry (a run's own, else its creator's or spawner's, else the terminal person).
+    const payerSource = opts.run ?? creatorNode ?? spawnerNode ?? forkSourceMeta;
+    await checkStart({ grantee: payerSource?.grantee ?? 'app:terminal', sub: payerSource?.sub, grant_id: payerSource?.grant_id });
+    const forkSourceNodeId = forkSourceMeta?.node_id ?? null;
+    let managedWorktree;
+    let spawnCwd = birthCwd;
+    // On Blaxel the node's sandbox is its worktree (D102): the request rides in the launch recipe and no checkout is made here.
+    const sandboxWorktree = wantsWorktree && await runsOnBlaxel(profileId) ? await sandboxWorktreeRequest(profileId, opts.worktreeCwd ?? opts.cwd, nodeId, opts.worktreeBase) : undefined;
+    try {
+        if (wantsWorktree && sandboxWorktree === undefined) {
+            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
+        // independent root sits top-of-spine with nobody to push to. Mirrors the
+        // `parent` set below (root ? null : spawner), so hasManager === parent!==null.
+        // Built HERE — after profile + worktree cwd are resolved — so the kind's
+        // model/tools resolve against the CHILD's own profile + project stack, not
+        // this process's ambient scope (a front-door shell has no CRTR_PROFILE_ID,
+        // which silently hid every profile-scope kind override).
+        const launch = wantsWorktree
+            ? await appPaidLaunch((await buildLaunchSpecAsync(opts.kind, mode, {
+                lifecycle, hasManager: !root, model: opts.model, modelOverride: opts.model !== undefined, cwd: spawnCwd, profileId,
+            })).launch, launchGrant, opts.model)
+            : preflightLaunch;
+        if (sandboxWorktree !== undefined)
+            launch.worktree = sandboxWorktree;
+        if (wantsWorktree) {
+            await assertLaunchModelRegistered(requestFromLaunch(launch), { cwd: spawnCwd, profileId });
+        }
+        const meta = await spawnNode({
+            kind: opts.kind,
+            mode,
+            lifecycle,
+            cwd: spawnCwd,
+            name: opts.name ?? opts.kind,
+            description: opts.description,
+            // A root has no spine parent (top-level, nobody subscribes); it still
+            // records spawned_by=spawner when a node (not a human shell) spawned it.
+            // A child's parent IS its manager.
+            parent: root ? null : spawner,
+            creator: opts.creator,
+            ...(opts.actor === undefined ? {} : { actor: opts.actor }),
+            forkSourceNode: forkSourceNodeId,
+            spawnedBy: root ? (spawner ?? undefined) : undefined,
+            profile_id: profileId,
+            ...(opts.scopes === undefined ? {} : { scopes: opts.scopes }),
+            isolated,
+            ...(opts.run === undefined ? {} : { run: opts.run }),
+            ...(opts.causedBy === undefined ? {} : { causedBy: opts.causedBy }),
+            ...(opts.withinCreate === undefined ? {} : { withinCreate: opts.withinCreate }),
+            forkFrom: opts.forkFrom,
+            forkSourceFile: forkFrom,
+            modelOverride: opts.model === undefined ? undefined : launch.model,
+            ...(managedWorktree !== undefined ? { managedWorktree } : {}),
+            ...(nodeId !== undefined ? { nodeId } : {}),
+            ...(opts.reviewBinding === undefined ? {} : { reviewBinding: opts.reviewBinding }),
+            ...(opts.deadlineAt === undefined ? {} : { deadlineAt: opts.deadlineAt }),
+            ...(opts.outcomeDelivery === undefined ? {} : { outcomeDelivery: opts.outcomeDelivery }),
+            launch,
+        });
+        afterNodeCreated?.(meta.node_id);
+        if (opts.forkFrom !== undefined) {
+            try {
+                await forkNodeLedger(meta.node_id, forkSourceNodeId ?? null);
+            }
+            catch (error) {
+                await transition(meta.node_id, 'crash', { reason: 'launch_failed', outcome: launchFailureOutcome(error) });
+                throw error;
+            }
+        }
+        // Persist the task as the child's goal for a fresh revive to re-read.
+        await writeGoal(meta.node_id, opts.prompt);
+        // Hidden ambient context, written BEFORE the engine launches so canvas-
+        // context-intro's session_start bearings carry it from the first turn.
+        if (opts.situationalContext !== undefined) {
+            await appendSituationalContext(meta.node_id, formatSituationalProse(opts.situationalContext));
+        }
+        // Compound births such as `node fork` may need durable state in place after
+        // the row and context directory exist but before the broker can observe it.
+        // A preparation failure leaves the row crashed and never launches a partial
+        // node.
+        if (beforeBrokerLaunch !== undefined) {
+            try {
+                beforeBrokerLaunch(meta.node_id);
+            }
+            catch (error) {
+                await transition(meta.node_id, 'crash', { reason: 'launch_failed', outcome: launchFailureOutcome(error) });
+                throw error;
+            }
+        }
+        // A scheduled birth prepends its clock provenance to the real task. Fork
+        // identity is owned exclusively by the session-start bearings message, which
+        // lands after copied history and before this prompt. An empty prompt starts
+        // the broker idle and carries neither a task nor wake provenance.
+        const hasKickoff = opts.prompt !== '';
+        const wakeBlock = hasKickoff && opts.wakeOrigin !== undefined ? `${buildWakeBearings(opts.wakeOrigin)}\n\n` : '';
+        const kickoff = `${wakeBlock}${opts.prompt}`;
+        // A child created DIRECTLY as an orchestrator (mode='orchestrator') boots
+        // with the orchestrator persona but bypasses promote(), which is where a
+        // roadmap scaffold would normally be seeded. Lay one down here (goal
+        // pre-filled from the task) so the orchestrator has its roadmap from
+        // birth, instead of waking without one. Guarded so it never clobbers.
+        if (mode === 'orchestrator')
+            await ensureRoadmap(meta.node_id, { goal: opts.prompt.trim() });
+        await invokeBirthLifecycleHooks(meta);
+        // The daemon owns both conversations at birth. Fork before launch so the
+        // new broker resumes its own copy instead of opening the source node's
+        // conversation through the node-only store socket.
+        let forkSessionPath;
+        if (forkFrom !== undefined) {
+            try {
+                const sourceId = conversationIdFromPath(forkFrom);
+                if (sourceId === null)
+                    throw new Error(`invalid fork source ${forkFrom}`);
+                const forkId = await conversationStore().fork(sourceId, meta.node_id);
+                forkSessionPath = (await conversationStore().header(forkId)).path;
+            }
+            catch (error) {
+                await transition(meta.node_id, 'crash', { reason: 'launch_failed', outcome: launchFailureOutcome(error) });
+                throw error;
+            }
+        }
+        const inv = buildPiArgv(meta, { prompt: kickoff, resumeSessionPath: forkSessionPath });
+        // CRTR_SUBTREE (the spine root) rides the detached broker's env so it can group
+        // the subtree; the host sets CRTR_FRONT_DOOR itself.
+        inv.env = { ...inv.env, CRTR_SUBTREE: await rootOfSpine(meta.node_id) };
+        // The kickoff's provenance rides the same env: it is composed here but sent
+        // by the broker process, which stamps it against the message pi persists.
+        if (hasKickoff) {
+            const kickoffOrigin = opts.wakeOrigin !== undefined
+                ? { type: 'runtime', kind: 'wake', wake: opts.wakeOrigin }
+                : {
+                    type: 'runtime',
+                    kind: 'kickoff',
+                    ...(meta.spawned_by != null && meta.spawned_by !== '' ? { spawnedBy: meta.spawned_by } : {}),
+                };
+            inv.env[KICKOFF_ORIGIN_ENV] = encodeKickoffOrigin(kickoffOrigin);
+        }
+        // Snapshot the boot-fault attempt the instant before launch — see
+        // beginBootFaultAttempt — so a later diagnostic read (root+await only, below)
+        // can only ever surface a fault THIS launch recorded, never a stale one.
+        // Claim the slot BEFORE the launch: `launchBrokerOrCrash` turns any launch
+        // failure — including the ledger's refusal — into a crashed row, and a birth
+        // that merely has to wait for capacity must not be crashed. Consulting the
+        // ledger here keeps the freeze decision ahead of that conversion. The
+        // reservation is consumed by the fleet's own `register` on a successful
+        // launch, so the release below is a no-op then and a give-back on any path
+        // that never registered a handle.
+        const fleet = boundFleet();
+        // A node whose profile points at a Blaxel environment is never launched here: it is born dormant with its goal kept, and the
+        // node-lifecycle lane wakes it through `reviveNode`, the one launch path that chooses the Blaxel runner and runs the bill check.
+        if (await blaxelEnvironmentOf(meta.profile_id ?? null) !== null) {
+            await setFrozen(meta.node_id, new Date().toISOString());
+            emitEvent({ level: 'info', event: 'broker.frozen', node_id: meta.node_id, fields: { reason: 'remote_environment' } });
+            return { node: await getNode(meta.node_id), frozen: true, window: null, session: null };
+        }
+        const slot = await fleet.reserveSlot(meta.node_id);
+        // The slot is held while the launcher measures the app's memory; a denial gives it back before freezing.
+        const memory = slot ? await admitBrokerMemory(meta.node_id) : null;
+        if (memory?.verdict === 'too_small') {
+            fleet.releaseReservation(meta.node_id);
+            const error = appMemoryTooSmall(memory);
+            await transition(meta.node_id, 'crash', { reason: 'launch_failed', outcome: launchFailureOutcome(error) });
+            throw error;
+        }
+        if (!slot || memory?.verdict === 'denied') {
+            if (memory?.verdict === 'denied')
+                fleet.releaseReservation(meta.node_id);
+            // Freezing is durable and once-per-episode; a birth is by definition the
+            // first, so the mark and its announcement always land here.
+            await setFrozen(meta.node_id, new Date().toISOString());
+            emitEvent({
+                level: 'info',
+                event: 'broker.frozen',
+                node_id: meta.node_id,
+                fields: memory?.verdict === 'denied'
+                    ? { reason: 'app_memory', free_bytes: memory.free_bytes, needed_bytes: memory.needed_bytes }
+                    : { reason: 'broker_cap', live_count: await fleet.occupancy(), hard_cap: brokerThresholdsForDaemon().automaticReviveCap },
+            });
+            // No engine, so no readiness to wait for and no viewer to place.
+            return { node: await getNode(meta.node_id), frozen: true, window: null, session: null };
+        }
+        const bootFault = await beginBootFaultAttempt(meta.node_id);
+        const { automaticReviveCap } = brokerThresholdsForDaemon();
+        let executionId;
+        try {
+            executionId = await beginExecution(meta.node_id, { daemonEpoch: fleet.epoch(), cap: automaticReviveCap });
+        }
+        catch (error) {
+            if (!(error instanceof ExecutionCapReached))
+                throw error;
+            // Another daemon process took the last slot between the in-process check and the row insert.
+            fleet.releaseReservation(meta.node_id);
+            await setFrozen(meta.node_id, new Date().toISOString());
+            emitEvent({ level: 'info', event: 'broker.frozen', node_id: meta.node_id, fields: { reason: 'broker_cap', live_count: error.live, hard_cap: error.cap } });
+            return { node: await getNode(meta.node_id), frozen: true, window: null, session: null };
+        }
+        inv.env = { ...inv.env, CRTR_EXECUTION_ID: executionId };
+        // Broker is the only host: launch the detached broker ENGINE. A managed child
+        // gets NO viewer — spawning it returns once the engine is launched and a human
+        // opens a viewer on demand via `crtr surface node focus` / surface attach. A --root gets
+        // a foreground viewer below.
+        let placed;
+        try {
+            placed = await launchBrokerOrCrash(meta.node_id, inv, {
+                cwd: meta.cwd,
+                name: fullName(meta),
+                resuming: false,
+            });
+        }
+        catch (error) {
+            await abortExecution(executionId, { reason: 'launch_failed' });
+            throw error;
+        }
+        finally {
+            fleet.releaseReservation(meta.node_id);
+        }
+        // Definitive failure: no broker pid ⇒ the node has no engine. Crash it (so the
+        // daemon doesn't watch a zombie 'active') and throw so `crtr node new` exits
+        // non-zero. transition('crash') is a legal from-LIVE move (still 'active' from
+        // spawnNode). Mirrors the old window===null crash.
+        if (placed.pid === null) {
+            const error = new Error(`broker host returned no pid for ${meta.node_id}`);
+            await abortExecution(executionId, { reason: 'launch_failed' });
+            await 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 canonical event diagnostics with \`crtr sys logs --node ${meta.node_id}\`, then verify the pi engine can start in this environment.`);
+        }
+        if (await recordExecutionPid(executionId, meta.node_id, placed.pid) === 'shutdown') {
+            await abortExecution(executionId, { reason: 'superseded' });
+            void headlessBrokerHost.teardown(meta.node_id);
+            throw brokerLaunchFailed(`broker execution was superseded for ${meta.node_id}`, 'Retry spawning the node.');
+        }
+        // A root created through `node new --root` must accept viewers before the
+        // command returns because its caller may attach immediately. Only that root
+        // waits — a managed child (and every cron-launched
+        // birth) stays launch-immediate so the daemon never blocks its serialized
+        // supervision loop on a birth, no matter what forwards the readiness field.
+        if (attendedRoot && opts.readiness === 'await') {
+            const wait = await awaitBrokerViewSocket(meta.node_id, placed.exited);
+            if (!wait.ready) {
+                // Stop a slow but still-live launch before it can bind behind a dead row.
+                const failure = notReadyDescription(meta.node_id, wait);
+                emitEvent({ level: 'error', event: 'broker.launch.not_ready', node_id: meta.node_id, fields: failure.fields });
+                const why = await bootFault.explanation();
+                await crashAndTearDown(meta.node_id, new Error(why ?? failure.text));
+                throw brokerLaunchFailed(why !== null
+                    ? `the root broker ${meta.node_id} could not start — ${why}`
+                    : `the root broker ${meta.node_id} ${failure.text} — it was not started.`, why !== null
+                    ? 'Resolve the cause named above, then retry.'
+                    : `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
+        // from its env precisely so this code cannot resolve someone else's pane),
+        // so a root's foreground viewer is placed by whoever asked for it — the
+        // front door, or `node new`'s own openSpawnViewer in the CLI process. Only a
+        // managed child is placed here, and placement stays non-fatal after the
+        // readiness proof.
+        let window = null;
+        let session = null;
+        if (!root && spawner !== null && readConfig('user').auto_open_child_viewers) {
+            // When enabled, a managed child opens beside a HUMAN actively watching
+            // its spawner. Turning the setting off leaves every child headless until
+            // someone explicitly focuses or attaches it. The broker is headless
+            // (TMUX stripped in broker.ts), so we can't read $TMUX — instead we find
+            // the spawner's live viewer pane from the focus registry (focusOf prunes
+            // a dead pane and returns null) and split beside it. No viewer ⇒ nobody is
+            // watching ⇒ stay headless. Best-effort: never fail a spawn on placement.
+            try {
+                const parentViewer = await focusOf(spawner);
+                if (parentViewer !== null && parentViewer.pane !== null && parentViewer.pane !== '') {
+                    // The child broker was JUST launched (readiness:'launch') and may not
+                    // have bound view.sock yet. Hand the attach pane CRTR_ATTACH_WAIT_MS so
+                    // it self-polls the socket until it accepts instead of connecting once,
+                    // finding a cold socket, and closing the pane instantly — the exact
+                    // mechanism bootRoot uses. A child with a kickoff prompt marks its
+                    // initial viewer for whip_mode; ordinary focus/attach paths stay
+                    // silent. No pre-wait in this CLI subprocess.
+                    const viewer = await openViewerWindow(meta.node_id, parentViewer.session ?? '', {
+                        name: fullName(meta),
+                        cwd: opts.cwd,
+                        besidePane: parentViewer.pane,
+                        waitForBroker: true,
+                        initialWhip: hasKickoff,
+                    });
+                    if (viewer !== null && viewer.pane !== null && viewer.pane !== '') {
+                        session = viewer.session;
+                        window = windowOfPane(viewer.pane);
+                    }
+                }
+            }
+            catch { /* best-effort — a headless spawn must never fail on viewer placement */ }
+        }
+        const saved = await getNode(meta.node_id);
+        return { node: saved, frozen: false, window, session };
+    }
+    catch (err) {
+        // Cleanup scope: a managed worktree is only removed on failure while NO
+        // persisted node identity exists yet. spawnNode() persists the node row
+        // (and its meta files) BEFORE the later fallible steps in this try block
+        // (writeGoal, roadmap seeding, launch, viewer placement) — so a flag set
+        // after spawnNode() merely returns would still read false if one of THOSE
+        // later steps threw, and this catch would then delete the worktree out
+        // from under an already-persisted node whose cwd points at it. Check the
+        // canvas directly instead: once any node row exists for this id, keep the
+        // 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 && await getNode(nodeId) === null) {
+            await rollbackManagedWorktreeAsync(managedWorktree);
+        }
+        throw err;
+    }
+}
+export async function spawnChild(opts) {
+    return spawnChildPrepared(opts);
+}
+/** Invoke the best-effort node-start plan before any cold broker launch. */
+export async function invokeBirthLifecycleHooks(meta) {
+    const lifecycleHooks = discoverLifecycleHookRegistry(meta.cwd, meta.profile_id).plans.get('node:start') ?? [];
+    await invokeLifecycleHooks(lifecycleHooks, {
+        node: {
+            id: meta.node_id,
+            name: meta.name,
+            kind: meta.kind,
+            mode: meta.mode,
+            lifecycle: meta.lifecycle,
+            cwd: meta.cwd,
+            nodeDir: await nodeAgentDir(meta.node_id),
+            contextDir: await contextDir(meta.node_id),
+            jobDir: jobDir(meta.node_id),
+        },
+        runtime: {
+            isBirth: true,
+            canvasHome: crtrHome(),
+            profile: meta.profile_id ?? null,
+        },
+    });
+}
+const FORK_CONTEXT_EXCLUDES = new Set(['initial-prompt.md', 'yield-message.md', 'result.json', 'jobs']);
+/** Create an independent, idle root from a node's conversation and durable
+ * context. Runtime/graph state is intentionally not inherited. */
+/** Fork `sourceId` into a fresh root. `scopes` is the fork's allow-list; omit
+ *  for a root with no ceiling. */
+export async function forkNode(sourceId, scopes, forker) {
+    const source = await getNode(sourceId);
+    if (source === null) {
+        throw usage(`unknown node: ${sourceId}`, {
+            received: sourceId,
+            next: 'List nodes and pass the id of a node with a captured pi session.',
+        });
+    }
+    const sessionFile = await resolveForkSource(sourceId);
+    const sourceContext = await contextDir(sourceId);
+    try {
+        await conversationStore().header(conversationIdFromPath(sessionFile));
+        accessSync(sourceContext, constants.R_OK);
+    }
+    catch (error) {
+        throw new Error(`cannot fork ${sourceId}: its conversation or context is unreadable — ${error.message}`);
+    }
+    return spawnChildPrepared({
+        kind: source.kind,
+        mode: 'base',
+        cwd: source.cwd,
+        prompt: '',
+        root: true,
+        readiness: 'await',
+        forkFrom: sourceId,
+        ...(forker === undefined ? {} : { actor: forker }),
+        profile: source.profile_id,
+        model: source.model_override ?? undefined,
+        ...(scopes === undefined ? {} : { scopes }),
+    }, async (destinationId) => {
+        const destinationContext = await contextDir(destinationId);
+        copyTreeBeneath(await nodeAgentDir(sourceId), sourceContext, await nodeAgentDir(destinationId), destinationContext, FORK_CONTEXT_EXCLUDES);
+    });
+}