@north-light/crouter 0.3.318 → 0.3.320

package/dist/core/runtime/spawn.js

@@ -1,577 +1,3 @@
-// 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, cpSync, readdirSync, existsSync, rmSync } from 'node:fs';
-import { isAbsolute, resolve, join } from 'node:path';
-import { spawnNode, 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 { 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 { hasRoadmap, seedRoadmap } from './roadmap.js';
-import { buildWakeBearings } from './bearings.js';
-import { encodeKickoffOrigin, KICKOFF_ORIGIN_ENV } from './stamp/protocol.js';
-import { beginExecution, canonicalSessionFile, contextDir, crtrHome, findNodeBySessionFile, getNode, fullName, jobDir, nodeDir, recordExecutionPid, abortExecution, reportsDir, setFrozen } from '../canvas/index.js';
-import { boundFleet, brokerThresholdsForDaemon } from './fleet.js';
-import { emitEvent } from '../events/emit.js';
-import { openViewerWindow, focusOf, windowOfPane, } from './placement.js';
-import { waitForBrokerViewSocket } from './placement-tmux.js';
-import { transition } from './lifecycle.js';
-import { beginBootFaultAttempt } from '../canvas/recovery.js';
-import { piSessionsRoot } from './pi-vendored.js';
-import { headlessBrokerHost } from './host.js';
-import { ensureDaemon } from '../../daemon/manage.js';
-import { readConfig } from '../config.js';
-import { modelRequestFromConfig, unregisteredConcreteModel } from '../model-routes.js';
-import { openModelRegistry } from './model-registry.js';
-import { MODEL_SPEC_NEXT } from './model-selection.js';
-import { initializeForkContextExposure } from '../substrate/injected-store.js';
-import { discoverLifecycleHookRegistry } from '../command-hooks/discovery.js';
-import { invokeLifecycleHooks } from '../command-hooks/transport/exec-lifecycle.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),
-        },
-    };
-}
-function launchBrokerOrCrash(nodeId, inv, opts) {
-    try {
-        return headlessBrokerHost.launch(nodeId, inv, opts);
-    }
-    catch (error) {
-        try {
-            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.');
-    }
-}
-/** A readiness failure must never leave a broker able to bind behind a dead row. */
-function crashAndTearDown(nodeId, error) {
-    try {
-        // Mark dead before touching the process so daemon supervision cannot revive it.
-        transition(nodeId, 'crash', { reason: 'launch_failed', outcome: launchFailureOutcome(error) });
-    }
-    catch {
-        /* preserve teardown even if lifecycle reconciliation already happened */
-    }
-    try {
-        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`. */
-function resolveSessionUuid(uuid) {
-    const sessionsRoot = piSessionsRoot();
-    if (!existsSync(sessionsRoot)) {
-        throw usage(`--fork-from '${uuid}': no pi sessions store at ${sessionsRoot} to resolve it from — pass a node id or an absolute .jsonl path.`, {
-            next: 'Pass a live node id, an absolute .jsonl session path, or drop --fork-from.',
-        });
-    }
-    const matches = [];
-    for (const dir of readdirSync(sessionsRoot, { withFileTypes: true })) {
-        if (!dir.isDirectory())
-            continue;
-        const projDir = join(sessionsRoot, dir.name);
-        for (const f of readdirSync(projDir)) {
-            if (!f.endsWith('.jsonl'))
-                continue;
-            const stem = f.slice(0, -'.jsonl'.length);
-            const id = stem.slice(stem.lastIndexOf('_') + 1);
-            matches.push({ id, path: join(projDir, f) });
-        }
-    }
-    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 canonicalSessionFile(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 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')) {
-        return canonicalSessionFile(isAbsolute(v) ? v : resolve(process.cwd(), v));
-    }
-    // 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 = 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.',
-            });
-        }
-        return canonicalSessionFile(src);
-    }
-    // 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 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 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);
-}
-/** 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 || request.kind === 'logical')
-        return;
-    const unknown = unregisteredConcreteModel(request, registry ?? await openModelRegistry(), options);
-    if (unknown === undefined)
-        return;
-    throw usage(`model '${unknown.request.spec}' is not registered in this daemon.`, {
-        received: unknown.request.spec,
-        next: MODEL_SPEC_NEXT,
-    });
-}
-/** 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 wantsWorktree = opts.worktree === true;
-    const nodeId = wantsWorktree ? (opts.nodeId ?? newNodeId()) : opts.nodeId;
-    // 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.
-    if (opts.nodeId !== undefined)
-        preflightNodeId(opts.nodeId);
-    const profileId = await resolveProfileId(opts.profile, spawner, opts.cwd);
-    const preflightLaunch = (await buildLaunchSpecAsync(opts.kind, mode, {
-        lifecycle, hasManager: !root, model: opts.model, modelOverride: opts.model !== undefined, cwd: opts.cwd, profileId,
-    })).launch;
-    await assertLaunchModelRegistered(requestFromLaunch(preflightLaunch), { cwd: opts.cwd, profileId });
-    const forkFrom = opts.forkFrom !== undefined ? resolveForkSource(opts.forkFrom) : undefined;
-    const forkSourceNodeId = forkFrom === undefined
-        ? null
-        : findNodeBySessionFile(forkFrom)?.node_id ?? null;
-    let managedWorktree;
-    let spawnCwd = opts.cwd;
-    try {
-        if (wantsWorktree) {
-            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 buildLaunchSpecAsync(opts.kind, mode, {
-                lifecycle, hasManager: !root, model: opts.model, modelOverride: opts.model !== undefined, cwd: spawnCwd, profileId,
-            })).launch
-            : preflightLaunch;
-        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,
-            spawnedBy: root ? (spawner ?? undefined) : undefined,
-            profile_id: profileId,
-            forkFrom: opts.forkFrom,
-            forkSourceFile: forkFrom,
-            modelOverride: opts.model === undefined ? undefined : launch.model,
-            ...(managedWorktree !== undefined ? { managedWorktree } : {}),
-            ...(nodeId !== undefined ? { nodeId } : {}),
-            ...(opts.deadlineAt === undefined ? {} : { deadlineAt: opts.deadlineAt }),
-            ...(opts.outcomeDelivery === undefined ? {} : { outcomeDelivery: opts.outcomeDelivery }),
-            launch,
-        });
-        afterNodeCreated?.(meta.node_id);
-        if (opts.forkFrom !== undefined) {
-            try {
-                initializeForkContextExposure(meta.node_id, forkSourceNodeId);
-            }
-            catch (error) {
-                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.
-        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) {
-            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) {
-                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 memory artifact from
-        // birth, instead of waking memory-less. Guarded so it never clobbers.
-        if (mode === 'orchestrator' && !hasRoadmap(meta.node_id)) {
-            seedRoadmap(meta.node_id, { goal: opts.prompt.trim() });
-        }
-        // (The three scoped long-term memory stores are seeded for EVERY node at birth
-        // in spawnNode — no orchestrator-gated seeding needed here.)
-        await invokeBirthLifecycleHooks(meta);
-        const inv = buildPiArgv(meta, { prompt: kickoff, forkFrom });
-        // 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: 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();
-        if (!fleet.reserveSlot(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.
-            setFrozen(meta.node_id, new Date().toISOString());
-            emitEvent({
-                level: 'info',
-                event: 'broker.frozen',
-                node_id: meta.node_id,
-                fields: { live_count: fleet.size(), hard_cap: brokerThresholdsForDaemon().automaticReviveCap },
-            });
-            // No engine, so no readiness to wait for and no viewer to place.
-            return { node: getNode(meta.node_id), frozen: true, window: null, session: null };
-        }
-        const bootFault = beginBootFaultAttempt(meta.node_id);
-        const executionId = beginExecution(meta.node_id, { daemonEpoch: fleet.epoch() });
-        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 = launchBrokerOrCrash(meta.node_id, inv, {
-                cwd: meta.cwd,
-                name: fullName(meta),
-                resuming: false,
-            });
-        }
-        catch (error) {
-            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}`);
-            abortExecution(executionId, { reason: 'launch_failed' });
-            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 (recordExecutionPid(executionId, meta.node_id, placed.pid) === 'shutdown') {
-            abortExecution(executionId, { reason: 'superseded' });
-            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' && !await waitForBrokerViewSocket(meta.node_id, placed.exited)) {
-            // Stop a slow but still-live launch before it can bind behind a dead row.
-            const why = bootFault.explanation();
-            crashAndTearDown(meta.node_id, new Error(why ?? `broker view socket never bound for ${meta.node_id}`));
-            throw brokerLaunchFailed(why !== null
-                ? `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 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 = 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 = 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 = 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 && 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: nodeDir(meta.node_id),
-            contextDir: contextDir(meta.node_id),
-            jobDir: jobDir(meta.node_id),
-            reportsDir: reportsDir(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']);
-/** Create an independent, idle root from a node's conversation and durable
- * context. Runtime/graph state is intentionally not inherited. */
-export async function forkNode(sourceId) {
-    const source = 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 = resolveForkSource(sourceId);
-    const sourceContext = contextDir(sourceId);
-    try {
-        accessSync(sessionFile, constants.R_OK);
-        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,
-        profile: source.profile_id,
-        model: source.model_override ?? undefined,
-    }, (destinationId) => {
-        const destinationContext = contextDir(destinationId);
-        for (const entry of readdirSync(sourceContext, { withFileTypes: true })) {
-            if (FORK_CONTEXT_EXCLUDES.has(entry.name))
-                continue;
-            cpSync(join(sourceContext, entry.name), join(destinationContext, entry.name), {
-                recursive: true,
-                dereference: false,
-                force: true,
-            });
-        }
-        for (const excluded of FORK_CONTEXT_EXCLUDES) {
-            rmSync(join(destinationContext, excluded), { recursive: true, force: true });
-        }
-    });
-}
+var Q=Object.defineProperty;var s=(e,o)=>Q(e,"name",{value:o,configurable:!0});import{accessSync as W,constants as A,cpSync as Y,readdirSync as D,existsSync as Z,rmSync as ee}from"node:fs";import{isAbsolute as ne,resolve as oe,join as g}from"node:path";import{spawnNode as re,currentNodeContext as ie,rootOfSpine as te,newNodeId as de,preflightNodeId as ae}from"./nodes.js";import{resolveProfileOperand as se}from"../profiles/manifest.js";import{selectProfileForCwd as ce,selectProfileForCwdReadOnly as le}from"../profiles/select.js";import{buildLaunchSpecAsync as M,buildPiArgv as fe}from"./launch.js";import{createManagedWorktreeAsync as ue,rollbackManagedWorktreeAsync as me}from"../worktree-mutation-async.js";import{usage as f,brokerLaunchFailed as E}from"../errors.js";import{writeGoal as he}from"./kickoff.js";import{appendSituationalContext as we,formatSituationalProse as pe}from"./situational-context.js";import{hasRoadmap as ke,seedRoadmap as _e}from"./roadmap.js";import{buildWakeBearings as ye}from"./bearings.js";import{encodeKickoffOrigin as ve,KICKOFF_ORIGIN_ENV as ge}from"./stamp/protocol.js";import{beginExecution as be,canonicalSessionFile as I,contextDir as P,crtrHome as xe,findNodeBySessionFile as Fe,getNode as w,fullName as H,jobDir as Oe,nodeDir as Ce,recordExecutionPid as Se,abortExecution as j,reportsDir as $e,setFrozen as Ee}from"../canvas/index.js";import{boundFleet as Re,brokerThresholdsForDaemon as De}from"./fleet.js";import{emitEvent as Ie}from"../events/emit.js";import{openViewerWindow as Pe,focusOf as je,windowOfPane as Ne}from"./placement.js";import{waitForBrokerViewSocket as Be}from"./placement-tmux.js";import{transition as b}from"./lifecycle.js";import{beginBootFaultAttempt as Te}from"../canvas/recovery.js";import{piSessionsRoot as Le}from"./pi-vendored.js";import{headlessBrokerHost as N}from"./host.js";import{ensureDaemon as We}from"../../daemon/manage.js";import{readConfig as Ae}from"../config.js";import{modelRequestFromConfig as Me,unregisteredConcreteModel as He}from"../model-routes.js";import{openModelRegistry as Ke}from"./model-registry.js";import{MODEL_SPEC_NEXT as ze}from"./model-selection.js";import{initializeForkContextExposure as qe}from"../substrate/injected-store.js";import{discoverLifecycleHookRegistry as Ue}from"../command-hooks/discovery.js";import{invokeLifecycleHooks as Ve}from"../command-hooks/transport/exec-lifecycle.js";function x(e){return{detail:{schema:"crtr.node-outcome-detail/v1",message:e instanceof Error?e.message:String(e)}}}s(x,"launchFailureOutcome");function Xe(e,o,d){try{return N.launch(e,o,d)}catch(r){try{b(e,"crash",{reason:"launch_failed",outcome:x(r)})}catch{}const t=r.message;throw E(t.startsWith("[broker]")?t:`[broker] refusing to launch ${e}: ${t}`,"Inspect the cause above, fix the launch recipe or environment, then retry.")}}s(Xe,"launchBrokerOrCrash");function Ge(e,o){try{b(e,"crash",{reason:"launch_failed",outcome:x(o)})}catch{}try{N.teardown(e)}catch{}}s(Ge,"crashAndTearDown");function Je(e){const o=Le();if(!Z(o))throw f(`--fork-from '${e}': no pi sessions store at ${o} to resolve it from \u2014 pass a node id or an absolute .jsonl path.`,{next:"Pass a live node id, an absolute .jsonl session path, or drop --fork-from."});const d=[];for(const a of D(o,{withFileTypes:!0})){if(!a.isDirectory())continue;const c=g(o,a.name);for(const l of D(c)){if(!l.endsWith(".jsonl"))continue;const F=l.slice(0,-6),u=F.slice(F.lastIndexOf("_")+1);d.push({id:u,path:g(c,l)})}}const r=d.filter(a=>a.id===e),t=r.length>0?r:d.filter(a=>a.id.startsWith(e));if(t.length===0)throw f(`--fork-from '${e}': 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(t.length>1)throw f(`--fork-from '${e}': ambiguous \u2014 ${t.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 I(t[0].path)}s(Je,"resolveSessionUuid");function K(e){const o=e.trim();if(o==="")throw f("--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."});if(o.includes("/")||o.endsWith(".jsonl"))return I(ne(o)?o:oe(process.cwd(),o));const d=w(o);if(d!==null){const r=d.pi_session_file;if(r==null||r==="")throw f(`node ${o} has no pi session yet \u2014 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."});return I(r)}return Je(o)}s(K,"resolveForkSource");async function Qe(e,o,d,r={}){return e===null?null:e!==void 0&&e!==""?se(e).profileId:o!==null?w(o)?.profile_id??null:r.readOnlySelection===!0?le(d):ce(d)}s(Qe,"resolveProfileId");function z(e){const o=e.modelIntent===void 0?void 0:`${e.modelIntent.family}/${e.modelIntent.strength}`;return Me(e.model,o,e.modelExact===!0)}s(z,"requestFromLaunch");async function q(e,o,d){if(e===void 0||e.kind==="logical")return;const r=He(e,d??await Ke(),o);if(r!==void 0)throw f(`model '${r.request.spec}' is not registered in this daemon.`,{received:r.request.spec,next:ze})}s(q,"assertLaunchModelRegistered");function Ye(e,o,d){const r=e??o??null;if(!d&&r===null)throw new Error("spawnChild requires a calling node (CRTR_NODE_ID) or an explicit parent");return r}s(Ye,"resolveSpawner");async function U(e,o,d){try{We()}catch{}const r=ie(),t=e.root===!0,a=Ye(e.parent,r.nodeId??null,t),c=e.mode??"base",l=e.rootLifecycle??(t?"resident":"terminal"),F=t&&l==="resident",u=e.worktree===!0,p=u?e.nodeId??de():e.nodeId;e.nodeId!==void 0&&ae(e.nodeId);const k=await Qe(e.profile,a,e.cwd),B=(await M(e.kind,c,{lifecycle:l,hasManager:!t,model:e.model,modelOverride:e.model!==void 0,cwd:e.cwd,profileId:k})).launch;await q(z(B),{cwd:e.cwd,profileId:k});const O=e.forkFrom!==void 0?K(e.forkFrom):void 0,X=O===void 0?null:Fe(O)?.node_id??null;let m,C=e.cwd;try{u&&(m=await ue(e.worktreeCwd??e.cwd,p,e.worktreeBase),C=m.path);const _=u?(await M(e.kind,c,{lifecycle:l,hasManager:!t,model:e.model,modelOverride:e.model!==void 0,cwd:C,profileId:k})).launch:B;u&&await q(z(_),{cwd:C,profileId:k});const n=await re({kind:e.kind,mode:c,lifecycle:l,cwd:C,name:e.name??e.kind,description:e.description,parent:t?null:a,creator:e.creator,spawnedBy:t?a??void 0:void 0,profile_id:k,forkFrom:e.forkFrom,forkSourceFile:O,modelOverride:e.model===void 0?void 0:_.model,...m!==void 0?{managedWorktree:m}:{},...p!==void 0?{nodeId:p}:{},...e.deadlineAt===void 0?{}:{deadlineAt:e.deadlineAt},...e.outcomeDelivery===void 0?{}:{outcomeDelivery:e.outcomeDelivery},launch:_});if(d?.(n.node_id),e.forkFrom!==void 0)try{qe(n.node_id,X)}catch(i){throw b(n.node_id,"crash",{reason:"launch_failed",outcome:x(i)}),i}if(he(n.node_id,e.prompt),e.situationalContext!==void 0&&we(n.node_id,pe(e.situationalContext)),o!==void 0)try{o(n.node_id)}catch(i){throw b(n.node_id,"crash",{reason:"launch_failed",outcome:x(i)}),i}const R=e.prompt!=="",G=`${R&&e.wakeOrigin!==void 0?`${ye(e.wakeOrigin)}
+
+`:""}${e.prompt}`;c==="orchestrator"&&!ke(n.node_id)&&_e(n.node_id,{goal:e.prompt.trim()}),await Ze(n);const h=fe(n,{prompt:G,forkFrom:O});if(h.env={...h.env,CRTR_SUBTREE:te(n.node_id)},R){const i=e.wakeOrigin!==void 0?{type:"runtime",kind:"wake",wake:e.wakeOrigin}:{type:"runtime",kind:"kickoff",...n.spawned_by!=null&&n.spawned_by!==""?{spawnedBy:n.spawned_by}:{}};h.env[ge]=ve(i)}const S=Re();if(!S.reserveSlot(n.node_id))return Ee(n.node_id,new Date().toISOString()),Ie({level:"info",event:"broker.frozen",node_id:n.node_id,fields:{live_count:S.size(),hard_cap:De().automaticReviveCap}}),{node:w(n.node_id),frozen:!0,window:null,session:null};const J=Te(n.node_id),y=be(n.node_id,{daemonEpoch:S.epoch()});h.env={...h.env,CRTR_EXECUTION_ID:y};let $;try{$=Xe(n.node_id,h,{cwd:n.cwd,name:H(n),resuming:!1})}catch(i){throw j(y,{reason:"launch_failed"}),i}finally{S.releaseReservation(n.node_id)}if($.pid===null){const i=new Error(`broker host returned no pid for ${n.node_id}`);throw j(y,{reason:"launch_failed"}),b(n.node_id,"crash",{reason:"launch_failed",outcome:x(i)}),E(`failed to launch the broker engine for ${n.node_id} (${n.name}) \u2014 the node was not started.`,`Inspect canonical event diagnostics with \`crtr sys logs --node ${n.node_id}\`, then verify the pi engine can start in this environment.`)}if(Se(y,n.node_id,$.pid)==="shutdown")throw j(y,{reason:"superseded"}),N.teardown(n.node_id),E(`broker execution was superseded for ${n.node_id}`,"Retry spawning the node.");if(F&&e.readiness==="await"&&!await Be(n.node_id,$.exited)){const i=J.explanation();throw Ge(n.node_id,new Error(i??`broker view socket never bound for ${n.node_id}`)),E(i!==null?`the root broker ${n.node_id} could not start \u2014 ${i}`:`the root broker ${n.node_id} never bound its view socket \u2014 it was not started.`,i!==null?"Resolve the cause named above, then retry.":`The broker engine exited before binding its view socket. Inspect canonical event diagnostics with \`crtr sys logs --node ${n.node_id}\`, then retry.`)}let T=null,L=null;if(!t&&a!==null&&Ae("user").auto_open_child_viewers)try{const i=je(a);if(i!==null&&i.pane!==null&&i.pane!==""){const v=Pe(n.node_id,i.session??"",{name:H(n),cwd:e.cwd,besidePane:i.pane,waitForBroker:!0,initialWhip:R});v!==null&&v.pane!==null&&v.pane!==""&&(L=v.session,T=Ne(v.pane))}}catch{}return{node:w(n.node_id),frozen:!1,window:T,session:L}}catch(_){throw m!==void 0&&p!==void 0&&w(p)===null&&await me(m),_}}s(U,"spawnChildPrepared");async function jn(e){return U(e)}s(jn,"spawnChild");async function Ze(e){const o=Ue(e.cwd,e.profile_id).plans.get("node:start")??[];await Ve(o,{node:{id:e.node_id,name:e.name,kind:e.kind,mode:e.mode,lifecycle:e.lifecycle,cwd:e.cwd,nodeDir:Ce(e.node_id),contextDir:P(e.node_id),jobDir:Oe(e.node_id),reportsDir:$e(e.node_id)},runtime:{isBirth:!0,canvasHome:xe(),profile:e.profile_id??null}})}s(Ze,"invokeBirthLifecycleHooks");const V=new Set(["initial-prompt.md","yield-message.md","result.json"]);async function Nn(e){const o=w(e);if(o===null)throw f(`unknown node: ${e}`,{received:e,next:"List nodes and pass the id of a node with a captured pi session."});const d=K(e),r=P(e);try{W(d,A.R_OK),W(r,A.R_OK)}catch(t){throw new Error(`cannot fork ${e}: its conversation or context is unreadable \u2014 ${t.message}`)}return U({kind:o.kind,mode:"base",cwd:o.cwd,prompt:"",root:!0,readiness:"await",forkFrom:e,profile:o.profile_id,model:o.model_override??void 0},t=>{const a=P(t);for(const c of D(r,{withFileTypes:!0}))V.has(c.name)||Y(g(r,c.name),g(a,c.name),{recursive:!0,dereference:!1,force:!0});for(const c of V)ee(g(a,c),{recursive:!0,force:!0})})}s(Nn,"forkNode");export{q as assertLaunchModelRegistered,Nn as forkNode,Ze as invokeBirthLifecycleHooks,K as resolveForkSource,Qe as resolveProfileId,Ye as resolveSpawner,jn as spawnChild,U as spawnChildPrepared};