@north-light/crouter 0.3.154

package/dist/core/runtime/spawn.js

@@ -0,0 +1,473 @@
+// 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 { loadProfileManifest } from '../profiles/manifest.js';
+import { selectProfileForCwd } from '../profiles/select.js';
+import { buildLaunchSpec, buildPiArgv } from './launch.js';
+import { createManagedWorktree, rollbackManagedWorktree } from '../worktree.js';
+import { usage, brokerLaunchFailed } from '../errors.js';
+import { writeGoal } from './kickoff.js';
+import { appendSituationalContext } from './situational-context.js';
+import { hasRoadmap, seedRoadmap } from './roadmap.js';
+import { buildIdentityAssertion, buildWakeBearings } from './bearings.js';
+import { contextDir, getNode, fullName, recordPid } from '../canvas/index.js';
+import { jobDir } from '../canvas/paths.js';
+import { openViewerWindow, focusOf, windowOfPane, currentTmux, focusWindow, } from './placement.js';
+import { waitForBrokerViewSocket } from './placement-tmux.js';
+import { transition } from './lifecycle.js';
+import { beginBootFaultAttempt } from './fault.js';
+import { piSessionsRoot } from './pi-vendored.js';
+import { headlessBrokerHost } from './host.js';
+import { ensureDaemon } from '../../daemon/manage.js';
+// ---------------------------------------------------------------------------
+// Shared broker-launch wrapper — catch launch/preflight failures at the call
+// site, mark the node crashed, then rethrow a clear error.
+// ---------------------------------------------------------------------------
+function launchBrokerOrCrash(nodeId, inv, opts) {
+    try {
+        return headlessBrokerHost.launch(nodeId, inv, opts);
+    }
+    catch (error) {
+        try {
+            transition(nodeId, 'crash');
+        }
+        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) {
+    try {
+        // Mark dead before touching the process so daemon supervision cannot revive it.
+        transition(nodeId, 'crash');
+    }
+    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 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 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 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 or name) validated through `loadProfileManifest`, 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) {
+    if (explicit === null)
+        return null;
+    if (explicit !== undefined && explicit !== '') {
+        return loadProfileManifest(explicit).profileId;
+    }
+    if (spawner !== null)
+        return getNode(spawner)?.profile_id ?? null;
+    return selectProfileForCwd(cwd);
+}
+/** 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 (regression: `crtr node new --root` from outside a node used to
+ *  throw here). */
+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) {
+    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';
+    // Lifecycle keys on ROOT-ness only, independent of mode: an independent root
+    // (or `--root`) is resident by default (a conversation that persists, woken by
+    // inbox/human); every spawned child is terminal — it owes a final up the spine
+    // and reaps when done. A child born as an orchestrator is terminal/orchestrator
+    // (delegates + holds a roadmap, but still reports up), NOT resident.
+    //
+    // `rootLifecycle: 'terminal'` is the one deliberate exception: a parentless
+    // node that STILL owes a final (see the option's docblock). It is unattended
+    // by construction, so `attendedRoot` below also suppresses viewer placement.
+    const lifecycle = root ? (opts.rootLifecycle ?? '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 (the 2-3s freeze it used to cost).
+    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) and an invalid `--profile`
+    // (resolveProfileId) 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 forkFrom = opts.forkFrom !== undefined ? resolveForkSource(opts.forkFrom) : undefined;
+    let managedWorktree;
+    let spawnCwd = opts.cwd;
+    try {
+        if (wantsWorktree) {
+            managedWorktree = createManagedWorktree(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 } = buildLaunchSpec(opts.kind, mode, { lifecycle, hasManager: !root, model: opts.model, cwd: spawnCwd, profileId });
+        const meta = spawnNode({
+            kind: opts.kind,
+            mode,
+            lifecycle,
+            cwd: spawnCwd,
+            name: opts.name ?? opts.kind,
+            // 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,
+            spawnedBy: root ? (spawner ?? undefined) : undefined,
+            profile_id: profileId,
+            // Persist the RAW fork reference (not the resolved path) as provenance, so
+            // the boot intro can detect this is a fork and re-assert the node's own
+            // identity over the source's copied-in conversation.
+            forkFrom: opts.forkFrom,
+            modelOverride: opts.model,
+            ...(managedWorktree !== undefined ? { managedWorktree } : {}),
+            ...(nodeId !== undefined ? { nodeId } : {}),
+            launch,
+        });
+        // 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, 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');
+                throw error;
+            }
+        }
+        // A fork inherits the SOURCE node's entire first-person conversation, so the
+        // identity re-assertion must ride the STRONGEST channel too, not only the
+        // session-start bearings (a trailing custom_message the model weighs only by
+        // recency). Prepend it to the kickoff PROMPT — the message that actually
+        // triggers the fork's first turn, so the model acts on "you are node X, a
+        // FORK of <source>, NOT them" as live instruction. When the daemon births this
+        // node from a scheduled `spawn` wake, the <crtr-wake> provenance block leads
+        // (so "a timer birthed you" precedes the task) — mirroring the fork-identity
+        // prepend. Only the pi argv prompt is reframed; the persisted goal (writeGoal
+        // above) keeps the raw task.
+        //
+        // A no-kickoff spawn (opts.prompt === '', see `node new --no-kickoff`) delivers
+        // NO positional prompt at all (buildPiArgv below omits it on an empty string),
+        // so no turn ever runs at spawn — neither block is meaningful without a turn to
+        // ride, so both are skipped even when forkFrom/wakeOrigin are set: the forked
+        // history still lands in the new session verbatim, it is simply not paired
+        // with an immediate re-assertion turn. Whatever real prompt arrives later is
+        // the fork's actual first turn.
+        const hasKickoff = opts.prompt !== '';
+        const wakeBlock = hasKickoff && opts.wakeOrigin !== undefined ? `${buildWakeBearings(opts.wakeOrigin)}\n\n` : '';
+        const idBlock = hasKickoff && forkFrom !== undefined ? `${buildIdentityAssertion(meta.node_id)}\n\n` : '';
+        const kickoff = `${wakeBlock}${idBlock}${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.)
+        // An ATTENDED --root spawned from inside tmux opens its foreground viewer
+        // in the CALLER'S CURRENT session (below), so it appears where the spawner is
+        // working; a managed child is a headless broker with NO viewer at all, and
+        // so is an unattended terminal root (nobody asked to watch it).
+        const here = attendedRoot ? currentTmux() : null;
+        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) };
+        // 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.
+        const bootFault = beginBootFaultAttempt(meta.node_id);
+        // 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.
+        const placed = launchBrokerOrCrash(meta.node_id, inv, {
+            cwd: meta.cwd,
+            name: fullName(meta),
+            resuming: false,
+        });
+        // 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) {
+            transition(meta.node_id, 'crash');
+            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.`);
+        }
+        recordPid(meta.node_id, placed.pid);
+        // Directly driven roots are not useful until their broker accepts viewers:
+        // the web composer navigates as soon as `node new --root` returns. Only a
+        // directly driven 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);
+            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 ${jobDir(meta.node_id)}/broker.log for the underlying cause (a missing dependency, model auth, or a crash), then retry.`);
+        }
+        // An ATTENDED --root is spawned to be DRIVEN directly: when the caller is
+        // inside tmux, open ONE foreground viewer in the caller's CURRENT session and
+        // bring it forefront so whoever asked for it picks up the conversation.
+        // Outside tmux a --root opens no viewer (an agent handing a root off); an
+        // UNATTENDED terminal root (rootLifecycle: 'terminal') opens none anywhere —
+        // stealing focus for machinery nobody is watching is the bug, not the
+        // feature. A managed child opens nothing. Viewer placement remains non-fatal
+        // after the readiness proof.
+        let window = null;
+        let session = null;
+        if (attendedRoot && here !== null) {
+            const viewer = openViewerWindow(meta.node_id, here.session, { name: fullName(meta), cwd: opts.cwd });
+            if (viewer !== null && viewer.pane !== null && viewer.pane !== '') {
+                session = here.session;
+                window = windowOfPane(viewer.pane);
+                if (window !== null) {
+                    try {
+                        focusWindow(here.session, window);
+                    }
+                    catch { /* best-effort */ }
+                }
+            }
+        }
+        else if (!root && spawner !== null) {
+            // A managed child is normally born headless (no viewer). But when a HUMAN is
+            // actively watching the spawner in a tmux viewer pane, pop the child's viewer
+            // open beside it so the human sees background work start immediately instead of
+            // having to hunt for 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 as before. Best-effort:
+            // never fail a spawn on viewer 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. 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,
+                    });
+                    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, 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) {
+            rollbackManagedWorktree(managedWorktree);
+        }
+        throw err;
+    }
+}
+export async function spawnChild(opts) {
+    return spawnChildPrepared(opts);
+}
+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 });
+        }
+    });
+}

package/dist/core/runtime/stop-guard.d.ts

@@ -0,0 +1,18 @@
+export interface StopSignals {
+    /** Did the node call `push --final` (finish) this turn? */
+    pushedFinal: boolean;
+    /** Did the node call `crtr ask` (escalate to the human) this turn? */
+    askedHuman: boolean;
+}
+export type StopAction = {
+    action: 'allow';
+    reason: 'awaiting' | 'scheduled' | 'finished' | 'escalated' | 'dormant';
+} | {
+    action: 'reprompt';
+    reason: 'stalled';
+    message: string;
+};
+export declare const STALL_REPROMPT: string;
+/** Decide what to do when a node stops. Pure given the canvas + this turn's
+ *  signals — the stophook supplies the signals and enacts the action. */
+export declare function evaluateStop(nodeId: string, signals: StopSignals): StopAction;

package/dist/core/runtime/stop-guard.js

@@ -0,0 +1,77 @@
+// The stop-guard — no stalled agents.
+//
+// Every time a node's pi process stops, we ask one question: is this node
+// *legitimately waiting*? A node is legitimately waiting iff it holds an ACTIVE
+// subscription to a live node, or explicitly awaits a live controller's message
+// — something that can actually wake it. (A passive sub won't wake you, so it
+// doesn't count.)
+//
+//   • resident       → an interactable / human-driven node is NEVER forced to
+//                      submit a final: stopping to go dormant is always
+//                      legitimate (woken by inbox/human). Keyed on the LIFECYCLE
+//                      value, not on parent/mode — what matters is residency.
+//   • waiting        → a TERMINAL node holding an active live subscription is a
+//                      dormant orchestrator awaiting its workers. Let it sleep;
+//                      a child's push wakes it (and idle-releases its window).
+//   • finished/asked → it pushed --final (done) or called `crtr ask` this turn.
+//                      Also fine.
+//   • otherwise      → a TERMINAL node with nothing live to wait for and no
+//                      final pushed. Re-prompt it to finish or escalate.
+import { hasActiveLiveSubscription, hasLiveMessageWait, hasPendingCancelOnWakeCron, getNode } from '../canvas/index.js';
+import { hasPendingStructuredOutput, readOutputRequest } from './structured-output.js';
+export const STALL_REPROMPT = "You've stopped but you're not waiting on anyone and haven't finished. " +
+    "Pipe the result to `crtr push final` through a single-quoted heredoc if the work is done, or use `crtr human ask` if you are blocked or need the user.";
+function structuredOutputReprompt(nodeId) {
+    let schema = '{}';
+    try {
+        const request = readOutputRequest(nodeId);
+        if (request !== null)
+            schema = JSON.stringify(request.schema, null, 2);
+    }
+    catch {
+        /* keep a deterministic reprompt even if the schema file was corrupted */
+    }
+    return `You must call the \`submit\` tool with a result matching the required schema before you can stop. You cannot finish or go dormant any other way while this request is pending.\n\nRequired schema:\n\n\`\`\`json\n${schema}\n\`\`\``;
+}
+/** Decide what to do when a node stops. Pure given the canvas + this turn's
+ *  signals — the stophook supplies the signals and enacts the action. */
+export function evaluateStop(nodeId, signals) {
+    if (signals.pushedFinal)
+        return { action: 'allow', reason: 'finished' };
+    if (signals.askedHuman)
+        return { action: 'allow', reason: 'escalated' };
+    // A pending structured-output request overrides every stored-state dormancy
+    // path: a post-final one-off follow-up still owes `submit` before it may stop.
+    if (hasPendingStructuredOutput(nodeId)) {
+        return { action: 'reprompt', reason: 'stalled', message: structuredOutputReprompt(nodeId) };
+    }
+    // Canonically finalized follow-up cycles and already-terminal stored states
+    // are not waiting to be re-prompted for a second final.
+    const node = getNode(nodeId);
+    if (node !== null && (node.final_report != null
+        || node.status === 'done'
+        || node.status === 'dead'
+        || node.status === 'canceled')) {
+        return { action: 'allow', reason: 'finished' };
+    }
+    // A RESIDENT node is interactable / human-driven and is never forced to submit
+    // a final: stopping to go dormant is always legitimate (the inbox or the human
+    // wakes it). Keyed on lifecycle, not parent — whether it has a parent doesn't
+    // matter, only whether it's resident. Roots are resident by birth default, so
+    // this still covers "don't nag the human's root" while generalizing it.
+    if (node !== null && node.lifecycle === 'resident') {
+        return { action: 'allow', reason: 'dormant' };
+    }
+    // A terminal node with a pending cancel-on-wake deadline is legitimately
+    // waiting on the clock, so it should idle-release rather than busy-wait
+    // holding its broker.
+    if (hasPendingCancelOnWakeCron(nodeId))
+        return { action: 'allow', reason: 'scheduled' };
+    // A terminal node holding something live to wake it is legitimately awaiting.
+    // Parentage alone is deliberately absent: only a subscription or explicit
+    // controller wait can suppress the stall guard.
+    if (hasActiveLiveSubscription(nodeId) || hasLiveMessageWait(nodeId))
+        return { action: 'allow', reason: 'awaiting' };
+    // A terminal node with nothing live and no final pushed has stalled.
+    return { action: 'reprompt', reason: 'stalled', message: STALL_REPROMPT };
+}

package/dist/core/runtime/stop-signals.d.ts

@@ -0,0 +1,14 @@
+import type { StopSignals } from './stop-guard.js';
+export type StopSignal = keyof StopSignals;
+/** Record a successful command outcome for this broker process. The stophook
+ * consumes the marker at settlement, so no broker-side canvas read is needed to
+ * recognize the command the node itself just completed. */
+export declare function markStopSignal(nodeId: string, signal: StopSignal): void;
+/** Consume command outcomes from this broker's just-settled turn. Markers from
+ * an earlier crashed broker are discarded rather than bleeding into its successor. */
+export declare function consumeStopSignals(nodeId: string): StopSignals;
+/** Discard any marker left by an earlier run of this same broker — a run that
+ * errored or was interrupted returns before settlement consumes its markers, and
+ * the pid stamp cannot tell those apart from the current run's. Called when a new
+ * user-directed run begins, never on an in-run retry. */
+export declare function clearStopSignals(nodeId: string): void;

package/dist/core/runtime/stop-signals.js

@@ -0,0 +1,46 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { jobDir } from '../canvas/paths.js';
+const SIGNALS = ['pushedFinal', 'askedHuman'];
+function signalPath(nodeId, signal) {
+    return join(jobDir(nodeId), `.${signal}`);
+}
+/** Which broker process a marker belongs to. `broker.ts` exports
+ * `CRTR_BROKER_PID` into its own env, so inside a broker this IS `process.pid`
+ * and every crtr command it spawns inherits the same value. Both the write and
+ * the read side go through this so a marker written by a command is recognized
+ * by the broker that consumes it — and so neither side is thrown off by an
+ * outer broker's pid leaking in through the environment. */
+function brokerIdentity() {
+    return process.env['CRTR_BROKER_PID'] ?? String(process.pid);
+}
+/** Record a successful command outcome for this broker process. The stophook
+ * consumes the marker at settlement, so no broker-side canvas read is needed to
+ * recognize the command the node itself just completed. */
+export function markStopSignal(nodeId, signal) {
+    mkdirSync(jobDir(nodeId), { recursive: true });
+    writeFileSync(signalPath(nodeId, signal), brokerIdentity());
+}
+/** Consume command outcomes from this broker's just-settled turn. Markers from
+ * an earlier crashed broker are discarded rather than bleeding into its successor. */
+export function consumeStopSignals(nodeId) {
+    const signals = { pushedFinal: false, askedHuman: false };
+    for (const signal of SIGNALS) {
+        const path = signalPath(nodeId, signal);
+        if (!existsSync(path))
+            continue;
+        const brokerPid = readFileSync(path, 'utf8').trim();
+        rmSync(path, { force: true });
+        if (brokerPid === brokerIdentity())
+            signals[signal] = true;
+    }
+    return signals;
+}
+/** Discard any marker left by an earlier run of this same broker — a run that
+ * errored or was interrupted returns before settlement consumes its markers, and
+ * the pid stamp cannot tell those apart from the current run's. Called when a new
+ * user-directed run begins, never on an in-run retry. */
+export function clearStopSignals(nodeId) {
+    for (const signal of SIGNALS)
+        rmSync(signalPath(nodeId, signal), { force: true });
+}