@north-light/crouter 0.3.311 → 0.3.312

package/dist/core/command-hooks/transport/exec-lifecycle.js

@@ -3,53 +3,109 @@ import { spawn } from 'node:child_process';
 import { PROCESS_GROUP_KILL_GRACE_MS, posixProcessGroupSpawnOptions, terminateProcessGroup } from '../../../hook-process.js';
 import { isRecord } from '../../../shared/predicates.js';
 import { diag } from '../../io.js';
+import { LIFECYCLE_CATALOG } from '../lifecycle-catalog.js';
 const MAX_STDOUT = 10 * 1024 * 1024;
-export const LIFECYCLE_HOOK_TIMEOUT_MS = 5_000;
-export const LIFECYCLE_EVENT_BUDGET_MS = 10_000;
-/** Runs one lifecycle hook. The node launch remains authoritative on every failure. */
+/** Runs one lifecycle hook. `node:start` and `node:close` remain best-effort. */
 export async function invokeLifecycleHook(hook, invocation, timeoutMs) {
     try {
-        const request = {
-            protocolVersion: 1,
-            op: hook.op,
-            event: hook.event,
-            phase: hook.phase,
-            operationId: randomBytes(16).toString('hex'),
-            node: invocation.node,
-            runtime: invocation.runtime,
-            context: { cwd: invocation.node.cwd },
-        };
-        const result = await runLifecycleProcess(hook, JSON.stringify(request), timeoutMs);
-        if (result.signal !== null)
-            throw new Error(`executable was killed by signal ${result.signal}`);
-        const envelope = parseEnvelope(result.stdout);
-        if (envelope.ok) {
-            if (result.status !== 0)
-                diag(`crtr: ${label(hook)} returned ok:true but exited ${result.status} (honoring the envelope)`);
-            return;
-        }
-        diag(`crtr: ${label(hook)} failed: ${envelope.error.code}: ${envelope.error.message}`);
+        const envelope = await executeLifecycleHook(hook, invocation, timeoutMs);
+        if (!envelope.ok)
+            diag(`crtr: ${label(hook)} failed: ${envelope.error.code}: ${envelope.error.message}`);
     }
     catch (error) {
         diag(`crtr: ${label(hook)} failed: ${describeError(error)}`);
     }
 }
-/** Executes lifecycle hooks in discovery order, within one bounded event budget. */
+/** Executes non-blocking lifecycle hooks in discovery order within the event's catalogued budget. */
 export async function invokeLifecycleHooks(hooks, invocation) {
-    const deadline = Date.now() + LIFECYCLE_EVENT_BUDGET_MS;
+    if (hooks.length === 0)
+        return;
+    const { hookTimeoutMs, eventBudgetMs } = LIFECYCLE_CATALOG[hooks[0].event];
+    const deadline = Date.now() + eventBudgetMs;
     for (const hook of hooks) {
         const remaining = deadline - Date.now();
-        // A timed-out hook must be reaped before launch can proceed. Reserve the
-        // process-group termination grace inside the event budget rather than
-        // letting the final cleanup extend the node-start critical path.
-        const timeoutMs = Math.min(LIFECYCLE_HOOK_TIMEOUT_MS, remaining - PROCESS_GROUP_KILL_GRACE_MS);
+        const timeoutMs = Math.min(hookTimeoutMs, remaining - PROCESS_GROUP_KILL_GRACE_MS);
         if (timeoutMs <= 0) {
-            diag(`crtr: lifecycle hook event ${hook.event} exceeded its ${LIFECYCLE_EVENT_BUDGET_MS}ms aggregate budget; skipped ${label(hook)}`);
+            diag(`crtr: lifecycle hook event ${hook.event} exceeded its ${eventBudgetMs}ms aggregate budget; skipped ${label(hook)}`);
             return;
         }
         await invokeLifecycleHook(hook, invocation, timeoutMs);
     }
 }
+/** Runs blocking `node:create` hooks. Every protocol or process failure refuses the create. */
+export async function invokeBlockingLifecycleHooks(hooks, invocation) {
+    if (hooks.length === 0)
+        return null;
+    const { hookTimeoutMs, eventBudgetMs } = LIFECYCLE_CATALOG['node:create'];
+    const deadline = Date.now() + eventBudgetMs;
+    for (const hook of hooks) {
+        const remaining = deadline - Date.now();
+        const timeoutMs = Math.min(hookTimeoutMs, remaining - PROCESS_GROUP_KILL_GRACE_MS);
+        if (timeoutMs <= 0) {
+            return refusal(hook, `lifecycle hook event node:create exceeded its ${eventBudgetMs}ms aggregate budget`);
+        }
+        try {
+            const envelope = await executeLifecycleHook(hook, invocation, timeoutMs);
+            if (!envelope.ok)
+                return {
+                    hook,
+                    message: envelope.error.message,
+                    next: envelope.error.next ?? attribution(hook),
+                };
+        }
+        catch (error) {
+            return refusal(hook, describeError(error));
+        }
+    }
+    return null;
+}
+function refusal(hook, cause) {
+    return {
+        hook,
+        message: `${label(hook)} failed: ${cause}`,
+        next: attribution(hook),
+    };
+}
+export function lifecycleHookAttribution(hook) {
+    return attribution(hook);
+}
+async function executeLifecycleHook(hook, invocation, timeoutMs) {
+    const request = hook.event === 'node:create'
+        ? createRequest(hook, invocation)
+        : nodeRequest(hook, invocation);
+    const result = await runLifecycleProcess(hook, JSON.stringify(request), timeoutMs);
+    if (result.signal !== null)
+        throw new Error(`executable was killed by signal ${result.signal}`);
+    const envelope = parseEnvelope(result.stdout);
+    if (envelope.ok && result.status !== 0) {
+        diag(`crtr: ${label(hook)} returned ok:true but exited ${result.status} (honoring the envelope)`);
+    }
+    return envelope;
+}
+function nodeRequest(hook, invocation) {
+    return {
+        protocolVersion: 1,
+        op: hook.op,
+        event: hook.event,
+        phase: hook.phase,
+        operationId: randomBytes(16).toString('hex'),
+        node: invocation.node,
+        runtime: invocation.runtime,
+        context: { cwd: invocation.node.cwd },
+    };
+}
+function createRequest(hook, invocation) {
+    return {
+        protocolVersion: 1,
+        op: hook.op,
+        event: 'node:create',
+        phase: 'before',
+        operationId: randomBytes(16).toString('hex'),
+        create: invocation.create,
+        runtime: invocation.runtime,
+        context: { cwd: invocation.create.cwd },
+    };
+}
 async function runLifecycleProcess(hook, input, timeoutMs) {
     let child;
     try {
@@ -147,6 +203,9 @@ function exactKeys(value, required, optional = []) {
 function label(hook) {
     return `plugin "${hook.plugin.name}" lifecycle hook "${hook.op}" for ${hook.event}`;
 }
+function attribution(hook) {
+    return `Refused by plugin ${hook.plugin.name}, op ${hook.op}.`;
+}
 function describeError(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/dist/core/errors.d.ts

@@ -22,6 +22,7 @@ export declare function general(message: string, details?: Record<string, unknow
  *  `apiErrorToCliError` (tier 2) reconstructs the exact code, message, and
  *  actionable `next` instead of degrading to a generic `invalid_request`. */
 export declare function brokerLaunchFailed(message: string, next: string): CrtrError;
+export declare function nodeCreateRefused(message: string, next: string): CrtrError;
 /** Thrown by stub handlers for leaves not yet wired in P3+.
  *  code='not_implemented', exitCode=GENERAL, next names the node. */
 export declare function notImplemented(node: string): CrtrError;

package/dist/core/errors.js

@@ -41,6 +41,10 @@ export function brokerLaunchFailed(message, next) {
     const code = 'broker_launch_failed';
     return new CrtrError(code, message, ExitCode.GENERAL, { error: code, message, next });
 }
+export function nodeCreateRefused(message, next) {
+    const code = 'node_create_refused';
+    return new CrtrError(code, message, ExitCode.GENERAL, { error: code, message, next });
+}
 /** Thrown by stub handlers for leaves not yet wired in P3+.
  *  code='not_implemented', exitCode=GENERAL, next names the node. */
 export function notImplemented(node) {

package/dist/core/human/feedback-companion.js

@@ -65,7 +65,7 @@ export async function realizeFeedbackCompanion(args) {
         cwd: origin.cwd,
         profileId: origin.profile_id ?? null,
     });
-    const node = spawnNode({
+    const node = await spawnNode({
         kind: origin.kind,
         mode: origin.mode,
         lifecycle: 'resident',

package/dist/core/review/companion.d.ts

@@ -27,7 +27,7 @@ export declare function captureOrigin(originNodeId: string, deps?: {
 /** Materialize the immutable review fork, reusing only an already-valid branch. */
 export declare function materializeReviewBranch(reviewId: string, capture: OriginCapture): string;
 /** Create the ordinary, promptless companion node. Realization owns its launch. */
-export declare function spawnReviewCompanion(spec: ReviewCompanionSpec): void;
+export declare function spawnReviewCompanion(spec: ReviewCompanionSpec): Promise<void>;
 /** A companion is bound only when its session coordinates and visible boundary are durable. */
 export declare function isReviewCompanionBound(nodeId: string): boolean;
 /** Wait for the durable companion bind without owning companion liveness. */

package/dist/core/review/companion.js

@@ -141,7 +141,7 @@ export function materializeReviewBranch(reviewId, capture) {
     return branchFile;
 }
 /** Create the ordinary, promptless companion node. Realization owns its launch. */
-export function spawnReviewCompanion(spec) {
+export async function spawnReviewCompanion(spec) {
     if (!isAbsolute(spec.branchFile) || !isAbsolute(spec.targetFile)) {
         throw new Error('review companion requires absolute branch and target paths');
     }
@@ -156,7 +156,7 @@ export function spawnReviewCompanion(spec) {
         cwd: spec.cwd,
         profileId: spec.profileId,
     });
-    const node = spawnNode({
+    const node = await spawnNode({
         nodeId: spec.nodeId,
         kind: 'review/companion',
         mode: 'base',

package/dist/core/review/realize.js

@@ -57,12 +57,12 @@ function requireOrigin(review) {
         throw originMissing(review.origin_node_id);
     return origin;
 }
-function spawnCompanion(review) {
+async function spawnCompanion(review) {
     if (getNode(review.companion_node_id) !== null)
         return;
     const origin = requireOrigin(review);
     try {
-        spawnReviewCompanion({
+        await spawnReviewCompanion({
             nodeId: review.companion_node_id,
             reviewId: review.review_id,
             originNodeId: review.origin_node_id,
@@ -94,13 +94,13 @@ function ensureBridgeSubscription(review, bridgeNodeId) {
         throw bridgeUnsubscribed(review, bridgeNodeId);
 }
 /** R2: create/bind the ticket bridge and prove its active origin subscription. */
-function realizeBridge(review) {
+async function realizeBridge(review) {
     if (review.origin_kind !== 'ticket')
         return review;
     let current = review;
     if (current.bridge_node_id === null) {
         const origin = requireOrigin(current);
-        const bridge = spawnNode({
+        const bridge = await spawnNode({
             kind: 'human',
             lifecycle: 'terminal',
             parent: current.origin_node_id,
@@ -160,9 +160,9 @@ export async function realizeReview(reviewId) {
         throw new ReviewOperationError('branch_lost', 'review branch was lost before realization', { review_id: review.review_id });
     }
     // R1: creation consumes only the persisted coordinates and preallocated id.
-    spawnCompanion(review);
+    await spawnCompanion(review);
     // R2: ticket bridge birth and route assertion precede all public exposure.
-    review = realizeBridge(requireReview(reviewId));
+    review = await realizeBridge(requireReview(reviewId));
     if (review.state !== 'binding')
         return review;
     // R3: only realization owns this initial launch/retry.

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

@@ -101,6 +101,10 @@ export interface SpawnNodeOpts {
     deadlineAt?: string;
     /** Delivery target persisted with the row before any broker can launch. */
     outcomeDelivery?: OutcomeDeliveryBinding;
+    /** Runs after the create hook admitted the birth but before its row is written. */
+    beforeCreate?: () => void | Promise<void>;
+    /** Root id replaced by this birth (`/new` or recycle); null for all other births. */
+    replaces?: string | null;
     /** Override the generated id — either an internally pre-allocated id
      *  (worktree naming; always valid+fresh) or an external caller's explicit id
      *  (`--node-id`), which is format-validated
@@ -112,4 +116,4 @@ export interface SpawnNodeOpts {
  *  For a child (parent given): the parent auto-subscribes ACTIVE to the child
  *  (so it's woken when the child finishes), and a spawned_by audit edge is
  *  recorded. For a root (no parent): no edges, resident by default. */
-export declare function spawnNode(opts: SpawnNodeOpts): NodeMeta;
+export declare function spawnNode(opts: SpawnNodeOpts): Promise<NodeMeta>;

package/dist/core/runtime/nodes.js

@@ -21,6 +21,7 @@ import { resolveInstallId } from '../canvas/install-id.js';
 import { canvasDbPath } from '../canvas/paths.js';
 import { usage } from '../errors.js';
 import { assertProfileAvailableForBirth } from '../profiles/deletion-reservation.js';
+import { admitNodeCreate } from '../command-hooks/lifecycle-create.js';
 import { fanDoctrineWake } from './close.js';
 import { BIRTH_ANNOUNCEMENT_MARKER, birthAnnouncementBody } from '../../shared/birth-announcement.js';
 // crtrd sets this once at boot (setInstallId) and it wins unconditionally —
@@ -131,14 +132,9 @@ export function preflightNodeId(nodeId) {
  *  satisfy the format unconditionally and are never a duplicate (they embed a
  *  fresh timestamp+random suffix), so this is only ever exercised by an
  *  explicit `opts.nodeId` from a real caller (`--node-id` / API `node_id`).
- *
- *  RACE SAFETY: this function and the `createNode()` call that follows it in
- *  `spawnNode` run with no `await` between them, and `spawnNode` itself is a
- *  synchronous function — so on the single-threaded daemon process, the
- *  existence-check-then-create is atomic relative to any other concurrent
- *  request. Two concurrent creates at the same id resolve to exactly one
- *  winner (whichever's synchronous `spawnNode()` call runs first) and one
- *  `NodeIdConflictError` for the loser. */
+ *  It runs inside the create critical section immediately before `createNode`,
+ *  so concurrent explicit-id births resolve to one winner and one
+ *  `NodeIdConflictError`. */
 function validatedExplicitNodeId(nodeId) {
     validateNodeIdFormat(nodeId);
     if (getNode(nodeId) !== null)
@@ -225,8 +221,8 @@ export function nodeEnv(meta) {
  *  For a child (parent given): the parent auto-subscribes ACTIVE to the child
  *  (so it's woken when the child finishes), and a spawned_by audit edge is
  *  recorded. For a root (no parent): no edges, resident by default. */
-export function spawnNode(opts) {
-    const nodeId = opts.nodeId !== undefined ? validatedExplicitNodeId(opts.nodeId) : newNodeId();
+export async function spawnNode(opts) {
+    const nodeId = opts.nodeId !== undefined ? (validateNodeIdFormat(opts.nodeId), opts.nodeId) : newNodeId();
     const parent = opts.parent ?? null;
     const isRoot = parent === null;
     // Provenance is independent of the spine: a root has no parent but still
@@ -279,7 +275,26 @@ export function spawnNode(opts) {
         throw new Error(`cannot spawn from unknown creator node: ${creator}`);
     }
     assertProfileAvailableForBirth(meta.profile_id ?? null);
-    createNode(meta, opts.outcomeDelivery === undefined ? undefined : { outcomeDelivery: opts.outcomeDelivery });
+    const releaseCreateGate = await admitNodeCreate({
+        kind: meta.kind,
+        mode: meta.mode,
+        cwd: meta.cwd,
+        profile: meta.profile_id ?? null,
+        root: isRoot,
+        parentId: parent,
+        requestingNodeId: creator,
+        lifecycle,
+        replaces: opts.replaces ?? null,
+    });
+    try {
+        if (opts.nodeId !== undefined)
+            validatedExplicitNodeId(opts.nodeId);
+        await opts.beforeCreate?.();
+        createNode(meta, opts.outcomeDelivery === undefined ? undefined : { outcomeDelivery: opts.outcomeDelivery });
+    }
+    finally {
+        releaseCreateGate();
+    }
     // Create the node-local memory directory so substrate docs can be written
     // directly into it without a separate mkdir. Skip for ephemeral human-bridge
     // rows (kind 'human') — they are not agent nodes.

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',