@north-light/crouter 0.3.310 → 0.3.312

package/dist/core/runtime/recycle.js

@@ -27,6 +27,7 @@ import { waitForBrokerViewSocket, viewerSplitEnv } from './placement-tmux.js';
 import { headlessBrokerHost } from './host.js';
 import { transition } from './lifecycle.js';
 import { ensureDaemon } from '../../daemon/manage.js';
+import { invokeBirthLifecycleHooks } from './spawn.js';
 /** The agent's most recent surfaced message: the newest reports/*.md body with
  *  its YAML frontmatter stripped. Empty string when the node never reported. */
 function lastReportBody(nodeId) {
@@ -64,17 +65,6 @@ export async function recycleNode(nodeId, callerPane) {
     if (pane === undefined || pane === '') {
         return { recycled: false, finalized: false, newRoot: null, delivered: [] };
     }
-    // 1. Finalize — fan the agent's last message out as a `final`, mark it done.
-    const body = lastReportBody(nodeId) ||
-        `Closed via recycle — no final summary was authored by ${meta.name}.`;
-    let delivered = [];
-    let finalized = false;
-    try {
-        const res = await pushFinal(nodeId, body);
-        delivered = res.deliveredTo;
-        finalized = true;
-    }
-    catch { /* recycle the pane even if the report failed */ }
     // Capture M's focus viewport (if any) before booting its replacement. The
     // old broker remains live until the new broker proves it can accept a viewer;
     // a failed replacement must not strand this finished conversation without an
@@ -92,17 +82,31 @@ export async function recycleNode(nodeId, callerPane) {
     // person's seat, so profile-scope defaults (e.g. a persisted /model default)
     // must keep applying.
     const { launch } = await buildLaunchSpecAsync('general', 'base', { lifecycle: 'resident', hasManager: false, cwd: meta.cwd, profileId: meta.profile_id });
-    const root = spawnNode({
+    const body = lastReportBody(nodeId) ||
+        `Closed via recycle — no final summary was authored by ${meta.name}.`;
+    let delivered = [];
+    let finalized = false;
+    const root = await spawnNode({
         kind: 'general',
         mode: 'base',
         lifecycle: 'resident',
         cwd: meta.cwd,
         name: 'general',
         parent: null,
+        replaces: nodeId,
         profile_id: meta.profile_id,
         launch,
+        beforeCreate: async () => {
+            try {
+                const res = await pushFinal(nodeId, body);
+                delivered = res.deliveredTo;
+                finalized = true;
+            }
+            catch { /* recycle the pane even if the report failed */ }
+        },
     });
     const fresh = getNode(root.node_id);
+    await invokeBirthLifecycleHooks(fresh);
     const inv = buildPiArgv(fresh);
     // CRTR_SUBTREE groups the fresh root's subtree; FRONT_DOOR is set by the broker
     // host itself, so it is not added here.

package/dist/core/runtime/reset.js

@@ -27,6 +27,7 @@ import { tearDownNode, focusOf, registerViewerFocus, respawnPaneSync, windowOfPa
 import { viewerSplitEnv, waitForBrokerViewSocket } from './placement-tmux.js';
 import { buildLaunchSpecAsync, buildPiArgv } from './launch.js';
 import { spawnNode, rootOfSpine } from './nodes.js';
+import { invokeBirthLifecycleHooks } from './spawn.js';
 // reapDescendants — tear down a root's descendant sub-DAG (shared helper)
 /** Reap the descendant sub-DAG of `rootId`: mark each **canceled** (the user
  *  moved on — a clean teardown, NOT a fault) + clear intent FIRST, then kill its
@@ -95,17 +96,19 @@ export async function relaunchRoot(oldId, deps = {}) {
         cwd: old.cwd,
         profileId: old.profile_id,
     });
-    const newMeta = spawnNode({
+    const newMeta = await spawnNode({
         kind: old.kind,
         mode: 'base',
         lifecycle: 'resident',
         cwd: old.cwd,
         name: old.kind,
         parent: null,
+        replaces: oldId,
         profile_id: old.profile_id,
         launch,
         modelOverride: old.model_override ?? undefined,
     });
+    await invokeBirthLifecycleHooks(newMeta);
     const inv = buildPiArgv(newMeta, {});
     // Mirror bootRoot's subtree routing on inv.env (the broker host merges it; it
     // sets CRTR_FRONT_DOOR itself).

package/dist/core/runtime/revive.js

@@ -278,10 +278,6 @@ async function launchRevive(nodeId, meta, opts) {
             next,
         });
     }
-    // This is the same durable distinction used to decide between a birth prompt
-    // and a revive kickoff below. Compute it before launch mutations so a stale
-    // session identity cannot make an ordinary fresh revive look like a birth.
-    const isBirth = isUnstartedBirth(nodeId);
     // Lazy host_kind coerce (§C): every launch now uses the broker host. Persist
     // that identity only after this call has passed the no-op liveness guard.
     if (meta.host_kind !== 'broker') {
@@ -340,6 +336,16 @@ async function launchRevive(nodeId, meta, opts) {
     const hasSessionPath = resume.resumeSessionPath !== undefined;
     const cycling = hasSessionPath && resume.newCycle === true;
     const resuming = hasSessionPath && !cycling;
+    // Never conversed and nothing on disk to rebuild from — relaunch as a birth
+    // (see isUnstartedBirth). A clock-driven wake must keep its <crtr-wake>
+    // kickoff — the schedule IS the instruction to take a turn, so it never
+    // degrades to a birth replay. This one decision selects the kickoff below
+    // and is what the node:start hook payload reports as `isBirth`: a hook is
+    // told "birth" exactly when the node boots as one.
+    const birthReplay = !hasSessionPath
+        && (opts.wakeReason === undefined || opts.wakeReason === 'runtime-restart-abort')
+        && isUnstartedBirth(nodeId);
+    const isBirth = forkBirthPending || birthReplay;
     // A cycling launch is provisional until session_start confirms it. Once
     // true, this marker is monotonic across failed retries; only that confirmed
     // boot may clear it.
@@ -399,14 +405,9 @@ async function launchRevive(nodeId, meta, opts) {
             kickoffOrigin = { type: 'runtime', kind: 'restart-continuation' };
         }
     }
-    else if (!hasSessionPath &&
-        // A clock-driven wake must keep its <crtr-wake> kickoff — the schedule IS
-        // the instruction to take a turn, so it never degrades to a birth replay.
-        (opts.wakeReason === undefined || opts.wakeReason === 'runtime-restart-abort') &&
-        isUnstartedBirth(nodeId)) {
-        // Never conversed and nothing on disk to rebuild from — relaunch as a birth
-        // (see isUnstartedBirth). A node with a spawn mandate replays it; a bare
-        // interactive node boots promptless and takes no turn at all.
+    else if (birthReplay) {
+        // A node with a spawn mandate replays it; a bare interactive node boots
+        // promptless and takes no turn at all.
         const goal = readGoal(nodeId)?.trim();
         inv = buildPiArgv(meta, goal !== undefined && goal !== '' ? { prompt: goal } : {});
         if (goal !== undefined && goal !== '')

package/dist/core/runtime/spawn.d.ts

@@ -127,8 +127,11 @@ export declare function resolveSpawner(parent: string | undefined, ctxNodeId: st
  *  to the spawner (it carries spawned_by=spawner for provenance only), brought
  *  forefront so a human can pick up the conversation directly. */
 type BeforeBrokerLaunch = (nodeId: string) => void;
-export declare function spawnChildPrepared(opts: SpawnChildOpts, beforeBrokerLaunch?: BeforeBrokerLaunch): Promise<SpawnChildResult>;
+type AfterNodeCreated = (nodeId: string) => void;
+export declare function spawnChildPrepared(opts: SpawnChildOpts, beforeBrokerLaunch?: BeforeBrokerLaunch, afterNodeCreated?: AfterNodeCreated): Promise<SpawnChildResult>;
 export declare function spawnChild(opts: SpawnChildOpts): Promise<SpawnChildResult>;
+/** Invoke the best-effort node-start plan before any cold broker launch. */
+export declare function invokeBirthLifecycleHooks(meta: NodeMeta): Promise<void>;
 /** Create an independent, idle root from a node's conversation and durable
  * context. Runtime/graph state is intentionally not inherited. */
 export declare function forkNode(sourceId: string): Promise<SpawnChildResult>;

package/dist/core/runtime/spawn.js

@@ -22,7 +22,7 @@ import { appendSituationalContext, formatSituationalProse } from './situational-
 import { hasRoadmap, seedRoadmap } from './roadmap.js';
 import { buildWakeBearings } from './bearings.js';
 import { encodeKickoffOrigin, KICKOFF_ORIGIN_ENV } from './stamp/protocol.js';
-import { canonicalSessionFile, contextDir, findNodeBySessionFile, getNode, fullName, recordPid, setFrozen } from '../canvas/index.js';
+import { canonicalSessionFile, contextDir, crtrHome, findNodeBySessionFile, getNode, fullName, jobDir, nodeDir, recordPid, 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';
@@ -37,6 +37,8 @@ import { modelRequestFromConfig, unregisteredConcreteModel } from '../model-rout
 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) {
@@ -210,7 +212,7 @@ export function resolveSpawner(parent, ctxNodeId, root) {
     }
     return spawner;
 }
-export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
+export async function spawnChildPrepared(opts, beforeBrokerLaunch, afterNodeCreated) {
     try {
         ensureDaemon();
     }
@@ -276,7 +278,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
         if (wantsWorktree) {
             await assertLaunchModelRegistered(requestFromLaunch(launch), { cwd: spawnCwd, profileId });
         }
-        const meta = spawnNode({
+        const meta = await spawnNode({
             kind: opts.kind,
             mode,
             lifecycle,
@@ -299,6 +301,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
             ...(opts.outcomeDelivery === undefined ? {} : { outcomeDelivery: opts.outcomeDelivery }),
             launch,
         });
+        afterNodeCreated?.(meta.node_id);
         if (opts.forkFrom !== undefined) {
             try {
                 initializeForkContextExposure(meta.node_id, forkSourceNodeId);
@@ -345,6 +348,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
         }
         // (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.
@@ -491,6 +495,29 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
 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. */

package/dist/core/runtime/warm-pool.d.ts

@@ -30,8 +30,8 @@ export interface WarmRequest {
     creator: string | null;
 }
 /** Claim a spare for `request`, reshaped onto its persona — or null when the
- *  pool cannot serve it. The caller falls back to a cold spawn; a claim never
- *  fails the create. */
+ *  pool cannot serve it. The caller falls back to a cold spawn; a refused
+ *  create hook leaves the spare untouched and rejects the create. */
 export declare function claimWarmNode(request: WarmRequest, birth?: {
     deadlineAt?: string;
     outcomeDelivery?: OutcomeDeliveryBinding;

package/dist/core/runtime/warm-pool.js

@@ -60,6 +60,7 @@ import { createHash } from 'node:crypto';
 import { claimWarmSpare, deleteNode, getNode, listNodes, listWarmSpares, registerWarmSpare, unregisterWarmSpare, updateNode, warmSpareCount, } from '../canvas/index.js';
 import { recordedPidLiveness } from '../canvas/pid.js';
 import { nowIso } from '../fs-utils.js';
+import { admitNodeCreate } from '../command-hooks/lifecycle-create.js';
 import { spawnChildPrepared } from './spawn.js';
 import { buildLaunchSpecAsync } from './launch.js';
 import { setModelLive } from './model-swap.js';
@@ -110,15 +111,34 @@ async function resolveRecipe(request) {
     return { key: warmRecipeKey(request.cwd, request.profileId, launch), launch, request };
 }
 /** Claim a spare for `request`, reshaped onto its persona — or null when the
- *  pool cannot serve it. The caller falls back to a cold spawn; a claim never
- *  fails the create. */
+ *  pool cannot serve it. The caller falls back to a cold spawn; a refused
+ *  create hook leaves the spare untouched and rejects the create. */
 export async function claimWarmNode(request, birth = {}) {
     const recipe = await resolveRecipe(request);
+    if (warmSpareCount(recipe.key) === 0)
+        return null;
     const created = nowIso();
     // The claim's requested deadline and delivery registration move with its
     // marker deletion, so the spare becomes caller-owned only as a fully armed
     // birth. meta.json follows with the same created stamp.
-    const nodeId = claimWarmSpare(recipe.key, created, birth);
+    const releaseCreateGate = await admitNodeCreate({
+        kind: request.kind,
+        mode: request.mode,
+        cwd: request.cwd,
+        profile: request.profileId,
+        root: true,
+        parentId: null,
+        requestingNodeId: request.creator,
+        lifecycle: 'resident',
+        replaces: null,
+    });
+    let nodeId;
+    try {
+        nodeId = claimWarmSpare(recipe.key, created, birth);
+    }
+    finally {
+        releaseCreateGate();
+    }
     if (nodeId === null)
         return null;
     const spare = getNode(nodeId);

package/dist/daemon/__tests__/node-outcome-birth-invariants.test.js

@@ -47,9 +47,9 @@ after(() => {
     else
         process.env.CRTR_HOME = priorHome;
 });
-test('birth commits the requested deadline and outcome registration before spawn orchestration can launch a broker', () => {
+test('birth commits the requested deadline and outcome registration before spawn orchestration can launch a broker', async () => {
     const deadlineAt = '2026-01-01T00:00:00.000Z';
-    const born = spawnNode({
+    const born = await spawnNode({
         kind: 'general',
         cwd: home,
         lifecycle: 'terminal',

package/dist/daemon/api/__tests__/profile-launch-gates.test.js

@@ -99,11 +99,11 @@ test('revive refuses a paused profile before launching a broker', async () => {
 // (fork, cron spawn, warm-pool mint, `/new` relaunch, recycle) actually hits,
 // because they all reach the canvas through spawnNode and none of them call
 // handleCreate.
-test('the birth gate refuses a paused profile for a daemon-side spawn', () => {
+test('the birth gate refuses a paused profile for a daemon-side spawn', async () => {
     const profile = createProfile('paused spawn', [{ path: cwd, memory: 'content' }]);
     pauseProfile(profile.profileId);
     const beforeRows = listNodes().length;
-    assert.throws(() => spawnNode({ kind: 'general', cwd, parent: null, profile_id: profile.profileId }), (error) => {
+    await assert.rejects(() => spawnNode({ kind: 'general', cwd, parent: null, profile_id: profile.profileId }), (error) => {
         assert.ok(error instanceof CrtrError);
         assert.equal(error.code, 'usage');
         assert.match(error.details?.['next'], new RegExp(`crtr profile resume ${profile.profileId}`));

package/dist/daemon/api/__tests__/seam/profile-delete.test.js

@@ -247,13 +247,13 @@ test('forced profile deletion owns the complete daemon lifecycle', { timeout: 90
     assert.equal(readFileSync(hardReview.sourceFile, 'utf8'), 'source\n', 'the reviewed source document is never removed');
     assert.equal(getDefaultProfileId(hardPin), null);
     await assert.rejects(client.getProfile(hardProfile.id), (error) => error instanceof ApiError && error.status === 404);
-    assert.throws(() => spawnNode({
+    await assert.rejects(() => spawnNode({
         kind: 'developer',
         cwd: process.cwd(),
         parent: null,
         profile_id: hardProfile.id,
         nodeId: 'hard-stale-birth-deadbeef',
-    }), /profile not found/, 'the final synchronous birth gate rejects a profile resolved before a completed hard deletion');
+    }), /profile not found/, 'the final birth gate rejects a profile resolved before a completed hard deletion');
     assert.equal(h.node('hard-stale-birth-deadbeef'), null);
     // Detach preserves nodes, topology, ticket/review state, and conversations;
     // matching brokers restart with no profile identity and matching crons become

package/dist/daemon/api/handlers/human.js

@@ -10,6 +10,7 @@ import { readTicketResult, validatePageTicketResponses } from '../../../core/hum
 import { getReviewByBridge } from '../../../core/review/store.js';
 import { ReviewOperationError } from '../../../core/review/types.js';
 import { spawnNode } from '../../../core/runtime/nodes.js';
+import { CrtrError } from '../../../core/errors.js';
 import { cancelHumanTicket, resolvePageTicket } from '../../human/finish.js';
 import { cancelReview } from '../../review/finish.js';
 function requireInteractionTicketId(ctx) {
@@ -20,7 +21,7 @@ function requireInteractionTicketId(ctx) {
     return ticketId;
 }
 // POST /v1/human/bridge — create a terminal bridge without a broker
-function handleCreateBridge(ctx) {
+async function handleCreateBridge(ctx) {
     const req = ctx.body;
     if (req === undefined || typeof req !== 'object') {
         throw new ApiError(400, 'invalid_request', 'bridge body is required');
@@ -37,10 +38,12 @@ function handleCreateBridge(ctx) {
         throw new ApiError(400, 'invalid_request', 'bridge `parent` must be a node id or null');
     }
     try {
-        const node = spawnNode({ kind: 'human', parent, creator: parent, cwd, name, lifecycle: 'terminal' });
+        const node = await spawnNode({ kind: 'human', parent, creator: parent, cwd, name, lifecycle: 'terminal' });
         return { status: 200, body: { node_id: node.node_id, name: node.name } };
     }
     catch (error) {
+        if (error instanceof CrtrError && error.code === 'node_create_refused')
+            throw error;
         throw new ApiError(400, 'invalid_request', String(error));
     }
 }

package/dist/daemon/api/handlers/nodes.d.ts

@@ -6,6 +6,7 @@ interface NodeHandlerDeps {
 export { resolveCreateKind } from '../../../core/runtime/launch-target.js';
 export declare function handleCreate(ctx: RequestContext, deps?: NodeHandlerDeps): Promise<HandlerResult>;
 export declare function handleList(ctx: RequestContext): HandlerResult;
+export declare function handleFork(ctx: RequestContext): Promise<HandlerResult>;
 export declare function handlePromote(ctx: RequestContext, deps?: NodeHandlerDeps): Promise<HandlerResult>;
 export declare function handleYield(ctx: RequestContext, deps?: NodeHandlerDeps): Promise<HandlerResult>;
 export declare function handleConfig(ctx: RequestContext, deps?: NodeHandlerDeps): Promise<HandlerResult>;

package/dist/daemon/api/handlers/nodes.js

@@ -13,7 +13,7 @@ import { appendSituationalContext, formatSituationalProse } from '../../../core/
 import { closeNode } from '../../../core/runtime/close.js';
 import { reviveNode } from '../../../core/runtime/revive.js';
 import { nowIso } from '../../../core/fs-utils.js';
-import { assertLaunchModelRegistered, forkNode, spawnChild } from '../../../core/runtime/spawn.js';
+import { assertLaunchModelRegistered, forkNode, spawnChildPrepared } from '../../../core/runtime/spawn.js';
 import { childrenOf, getNode, listNodes, subscribersOf, subscriptionsOf, setMessageWait, updateNode } from '../../../core/canvas/canvas.js';
 import { subtreeIds } from '../../../core/canvas/nav-model.js';
 import { ticketCountsForNodes } from '../../../core/canvas/attention.js';
@@ -298,32 +298,39 @@ export async function handleCreate(ctx, deps = {}) {
     const resolvedReq = { ...req, kind };
     const resolvedOutcomeDelivery = outcomeDelivery === undefined ? undefined : resolveOutcomeDelivery(outcomeDelivery, cwd);
     await assertLaunchModelRegistered(requestFromLaunch(launch), { cwd, profileId }, deps.modelRegistry);
-    // --- Warm path: hand out an already-booted spare instead of paying a full
-    //     engine boot. A miss is not a failure — it falls through to the cold
-    //     spawn below and mints the spare that serves the NEXT create. ---
-    const warm = warmRequestFor(resolvedReq, cwd, profileId);
-    if (warm !== null) {
-        const claimed = await claimWarmNode(warm, {
-            ...(deadline === undefined ? {} : { deadlineAt: deadline }),
-            ...(resolvedOutcomeDelivery === undefined ? {} : { outcomeDelivery: resolvedOutcomeDelivery }),
-        });
-        refillWarmPool(warm);
-        if (claimed !== null) {
-            if (schema !== null)
-                writeOutputSchema(claimed, 'terminal', schema);
-            return { status: 201, body: detailOf(claimed) };
+    let warmRefill = null;
+    {
+        // --- Warm path: hand out an already-booted spare instead of paying a full
+        //     engine boot. A miss is not a failure — it falls through to the cold
+        //     spawn below and mints the spare that serves the NEXT create. ---
+        const warm = warmRequestFor(resolvedReq, cwd, profileId);
+        if (warm !== null) {
+            const claimed = await claimWarmNode(warm, {
+                ...(deadline === undefined ? {} : { deadlineAt: deadline }),
+                ...(resolvedOutcomeDelivery === undefined ? {} : { outcomeDelivery: resolvedOutcomeDelivery }),
+            });
+            if (claimed !== null) {
+                refillWarmPool(warm);
+                if (schema !== null)
+                    writeOutputSchema(claimed, 'terminal', schema);
+                return { status: 201, body: detailOf(claimed) };
+            }
+            warmRefill = warm;
         }
+        const recipe = buildRecipe(resolvedReq, parent, cwd);
+        if (deadline !== undefined)
+            recipe.deadlineAt = deadline;
+        if (resolvedOutcomeDelivery !== undefined)
+            recipe.outcomeDelivery = resolvedOutcomeDelivery;
+        recipe.readiness = req.root === true ? 'await' : 'launch';
+        const result = await spawnChildPrepared(recipe, undefined, () => {
+            if (warmRefill !== null)
+                refillWarmPool(warmRefill);
+        });
+        if (schema !== null)
+            writeOutputSchema(result.node.node_id, 'terminal', schema);
+        return { status: 201, body: detailOf(result.node.node_id) };
     }
-    const recipe = buildRecipe(resolvedReq, parent, cwd);
-    if (deadline !== undefined)
-        recipe.deadlineAt = deadline;
-    if (resolvedOutcomeDelivery !== undefined)
-        recipe.outcomeDelivery = resolvedOutcomeDelivery;
-    recipe.readiness = req.root === true ? 'await' : 'launch';
-    const result = await spawnChild(recipe);
-    if (schema !== null)
-        writeOutputSchema(result.node.node_id, 'terminal', schema);
-    return { status: 201, body: detailOf(result.node.node_id) };
 }
 // GET /v1/nodes — list (filters) ; GET /v1/nodes/{id} — detail
 function singleQueryValue(ctx, name) {
@@ -557,10 +564,8 @@ function handleArtifacts(ctx) {
     return { status: 200, body };
 }
 // Lifecycle verbs
-async function handleFork(ctx) {
-    const id = ctx.params['id'];
-    requireMeta(id);
-    const result = await forkNode(id);
+export async function handleFork(ctx) {
+    const result = await forkNode(ctx.params['id']);
     return { status: 201, body: detailOf(result.node.node_id) };
 }
 async function handleRevive(ctx) {

package/dist/daemon/cron-run.js

@@ -35,14 +35,14 @@
 // promises for graceful-teardown drain but never blocks on a slow run.
 import { spawn } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
-import { CRON_KILL_GRACE_MS, CRON_OUTPUT_HEAD_BYTES, EMPTY_STDOUT_SHA256, newHeadCapture, } from './cron/capture.js';
+import { CRON_DEATH_POLL_MS, CRON_KILL_GRACE_MS, CRON_OUTPUT_HEAD_BYTES, EMPTY_STDOUT_SHA256, newHeadCapture, } from './cron/capture.js';
 import { clearLiveRun, cronDaemonInstanceId, liveRunFor, registerLiveRun } from './cron/live-runs.js';
 import { buildArmedRunContext } from './cron/armed-context.js';
 import { decideHeldSettle, EXIT_HELD, HELD_DELIVERED } from './cron/held.js';
 import { settleRun } from './cron/settle.js';
 import { applyOverlapPolicies, expireDueCrons, } from './cron/passes.js';
 import { dueClockCrons, acquireCronRunLease, advanceCron, setCronState, } from '../core/canvas/crons.js';
-import { killProcessGroup } from '../core/canvas/pid.js';
+import { captureTeardownSnapshot, isAnyPidAlive, killProcessTreePids } from '../core/canvas/pid.js';
 import { emitEvent } from '../core/events/emit.js';
 import { nextSlotAfter } from '../core/wake.js';
 import { resolveAdmittedHostCommand } from '../core/runtime/spawn-env.js';
@@ -239,6 +239,9 @@ export function executeCron(c, opts) {
         let settled = false;
         let timer;
         let killTimer;
+        let deathTimer;
+        let closeCode;
+        let killed = false;
         let timedOut = false;
         let leaseLost = false;
         let processError = null;
@@ -259,19 +262,8 @@ export function executeCron(c, opts) {
         child.stderr?.on('data', (chunk) => {
             stderr.take(chunk);
         });
-        const killWithEscalation = (pid) => {
-            killProcessGroup(pid);
-            if (killTimer === undefined) {
-                killTimer = setTimeout(() => killProcessGroup(pid, 'SIGKILL'), CRON_KILL_GRACE_MS);
-                killTimer.unref?.();
-            }
-        };
-        // A signal, not settlement: 'close' always follows 'error'.
-        child.on('error', (err) => {
-            if (processError == null)
-                processError = err;
-        });
-        child.on('close', (code) => {
+        let teardown;
+        const settleClosedChild = (code) => {
             if (settled)
                 return;
             settled = true;
@@ -279,6 +271,8 @@ export function executeCron(c, opts) {
                 clearTimeout(timer);
             if (killTimer !== undefined)
                 clearTimeout(killTimer);
+            if (deathTimer !== undefined)
+                clearTimeout(deathTimer);
             const stdoutHead = stdout.decode();
             const stderrHead = stderr.decode();
             const live = liveRunFor(c.cron_id);
@@ -306,6 +300,46 @@ export function executeCron(c, opts) {
                 wasReplaced,
                 wasSelfCanceled,
             }).then(resolve, reject);
+        };
+        const awaitTeardownDeath = () => {
+            if (teardown === undefined || !isAnyPidAlive(teardown.tree)) {
+                if (closeCode !== undefined)
+                    settleClosedChild(closeCode);
+                return;
+            }
+            deathTimer = setTimeout(awaitTeardownDeath, CRON_DEATH_POLL_MS);
+        };
+        const killWithEscalation = (pid) => {
+            teardown ??= captureTeardownSnapshot(pid, null);
+            killProcessTreePids(teardown.tree, 'SIGTERM', teardown.identities);
+            if (killTimer === undefined) {
+                killTimer = setTimeout(() => {
+                    if (isAnyPidAlive(teardown.tree))
+                        killProcessTreePids(teardown.tree, 'SIGKILL', teardown.identities);
+                    killed = true;
+                    if (closeCode !== undefined)
+                        awaitTeardownDeath();
+                }, CRON_KILL_GRACE_MS);
+                killTimer.unref?.();
+            }
+        };
+        // A signal, not settlement: 'close' always follows 'error'.
+        child.on('error', (err) => {
+            if (processError == null)
+                processError = err;
+        });
+        child.on('close', (code) => {
+            if (settled)
+                return;
+            closeCode = code;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            if (teardown !== undefined && isAnyPidAlive(teardown.tree)) {
+                if (killed)
+                    awaitTeardownDeath();
+                return;
+            }
+            settleClosedChild(code);
         });
         if (child.pid == null ||
             !acquireCronRunLease(c.cron_id, cronDaemonInstanceId, child.pid, startedAtIso, outOfBand)) {

package/dist/hook-authoring.d.ts

@@ -23,6 +23,32 @@ export interface LifecycleHookRuntime {
     canvasHome: string;
     profile: string | null;
 }
+/** `node:create` runs before every node birth, immediately before a cold row is written or a warm spare is claimed. Return `ok:false` to refuse the birth. There is no node payload because no node exists yet. */
+export interface NodeCreateHookRequest {
+    protocolVersion: 1;
+    op: string;
+    event: 'node:create';
+    phase: 'before';
+    operationId: string;
+    create: {
+        kind: string;
+        mode: string;
+        cwd: string;
+        profile: string | null;
+        root: boolean;
+        parentId: string | null;
+        requestingNodeId: string | null;
+        lifecycle: 'resident' | 'terminal';
+        replaces: string | null;
+    };
+    runtime: {
+        canvasHome: string;
+        profile: string | null;
+    };
+    context: {
+        cwd: string;
+    };
+}
 interface HookRequestBase {
     protocolVersion: 1;
     op: string;
@@ -43,7 +69,7 @@ export interface AfterHookRequest extends HookRequestBase {
 export interface ReplaceHookRequest extends HookRequestBase {
     phase: 'replace';
 }
-/** Lifecycle handlers run on every matching event. `node:start` handlers must be idempotent because they fire for birth and every revive. */
+/** `node:start` handlers run for birth and every revive, so they must be idempotent. `node:close` runs after close. */
 export interface LifecycleHookRequest {
     protocolVersion: 1;
     op: string;
@@ -56,7 +82,7 @@ export interface LifecycleHookRequest {
         cwd: string;
     };
 }
-export type HookRequest = BeforeHookRequest | AfterHookRequest | ReplaceHookRequest | LifecycleHookRequest;
+export type HookRequest = BeforeHookRequest | AfterHookRequest | ReplaceHookRequest | NodeCreateHookRequest | LifecycleHookRequest;
 export interface HookSuccess {
     protocolVersion: 1;
     ok: true;