@north-light/crouter 0.3.310 → 0.3.312

package/dist/core/command-hooks/artifact.js

@@ -1,6 +1,21 @@
 import { readFileSync, realpathSync, statSync } from 'node:fs';
 import { isAbsolute, resolve, sep } from 'node:path';
 import { validateHookManifest } from './schema.js';
+function lifecycleCandidates(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return [];
+    const lifecycle = raw['lifecycle'];
+    if (!Array.isArray(lifecycle))
+        return [];
+    return lifecycle.flatMap((value, index) => {
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            return [];
+        const declaration = value;
+        return typeof declaration['event'] === 'string'
+            ? [{ event: declaration['event'], op: typeof declaration['op'] === 'string' ? declaration['op'] : '<invalid>', index }]
+            : [];
+    });
+}
 function safeFilePath(root, pointer) {
     if (isAbsolute(pointer))
         return null;
@@ -29,10 +44,10 @@ export function validatePluginHookArtifact(root, manifest) {
             expected: 'both hooks and hookExecutable',
             next: hasHooks ? 'Add plugin.json.hookExecutable or remove hooks.' : 'Add plugin.json.hooks or remove hookExecutable.',
         });
-        return { issues };
+        return { lifecycleCandidates: [], issues };
     }
     if (!hasHooks)
-        return { issues };
+        return { lifecycleCandidates: [], issues };
     if (typeof hooks !== 'string' || hooks.length === 0) {
         issues.push({
             code: 'hook_manifest_invalid',
@@ -54,7 +69,7 @@ export function validatePluginHookArtifact(root, manifest) {
         });
     }
     if (issues.length > 0)
-        return { issues };
+        return { lifecycleCandidates: [], issues };
     const hooksPointer = hooks;
     const executablePointer = executable;
     const manifestPath = safeFilePath(root, hooksPointer);
@@ -90,7 +105,7 @@ export function validatePluginHookArtifact(root, manifest) {
         });
     }
     if (manifestPath === null)
-        return { ...(executablePath === null ? {} : { executablePath }), issues };
+        return { lifecycleCandidates: [], ...(executablePath === null ? {} : { executablePath }), issues };
     let text;
     try {
         text = readFileSync(manifestPath, 'utf8');
@@ -103,7 +118,7 @@ export function validatePluginHookArtifact(root, manifest) {
             expected: 'a readable JSON file',
             next: 'Reinstall or update the plugin.',
         });
-        return { manifestPath, ...(executablePath === null ? {} : { executablePath }), issues };
+        return { manifestPath, lifecycleCandidates: [], ...(executablePath === null ? {} : { executablePath }), issues };
     }
     let raw;
     try {
@@ -117,11 +132,12 @@ export function validatePluginHookArtifact(root, manifest) {
             expected: 'a JSON object',
             next: 'Regenerate hooks.json.',
         });
-        return { manifestPath, ...(executablePath === null ? {} : { executablePath }), issues };
+        return { manifestPath, lifecycleCandidates: [], ...(executablePath === null ? {} : { executablePath }), issues };
     }
     const validation = validateHookManifest(raw);
     return {
         manifestPath,
+        lifecycleCandidates: lifecycleCandidates(raw),
         ...(executablePath === null ? {} : { executablePath }),
         ...(validation.manifest === undefined ? {} : { manifest: validation.manifest }),
         issues: [...issues, ...validation.issues],

package/dist/core/command-hooks/discovery.d.ts

@@ -1,4 +1,5 @@
 import type { InstalledPlugin } from '../../types.js';
+import { type LifecycleDeclarationCandidate } from './artifact.js';
 import type { CoreHookCatalog } from './catalog.js';
 import type { HookManifestIssue, HookPhase, LifecycleHookPhase, ValidatedHookManifest } from './schema.js';
 import type { LifecycleEvent } from './lifecycle-catalog.js';
@@ -65,6 +66,7 @@ export interface HookPluginValidation {
     manifestPath?: string;
     executablePath?: string;
     manifest?: ValidatedHookManifest;
+    lifecycleCandidates: readonly LifecycleDeclarationCandidate[];
     hooks: readonly EffectiveHook[];
     issues: readonly HookDiscoveryIssue[];
 }

package/dist/core/command-hooks/discovery.js

@@ -109,6 +109,7 @@ export function compileHookRegistry(catalog, plugins) {
             ...(artifact.manifestPath === undefined ? {} : { manifestPath: artifact.manifestPath }),
             ...(artifact.executablePath === undefined ? {} : { executablePath: artifact.executablePath }),
             ...(artifact.manifest === undefined ? {} : { manifest: artifact.manifest }),
+            lifecycleCandidates: Object.freeze([...artifact.lifecycleCandidates]),
             hooks: Object.freeze(compiled),
             issues: Object.freeze(pluginIssues),
         }));
@@ -183,6 +184,7 @@ export function compileLifecycleHookRegistry(plugins) {
             ...(artifact.manifestPath === undefined ? {} : { manifestPath: artifact.manifestPath }),
             ...(artifact.executablePath === undefined ? {} : { executablePath: artifact.executablePath }),
             ...(artifact.manifest === undefined ? {} : { manifest: artifact.manifest }),
+            lifecycleCandidates: Object.freeze([...artifact.lifecycleCandidates]),
             hooks: Object.freeze([]),
             issues: Object.freeze(pluginIssues),
         }));

package/dist/core/command-hooks/lifecycle-catalog.d.ts

@@ -1,3 +1,21 @@
-export declare const LIFECYCLE_EVENTS: readonly ["node:start", "node:close"];
-export type LifecycleEvent = typeof LIFECYCLE_EVENTS[number];
+export declare const LIFECYCLE_CATALOG: {
+    readonly 'node:create': {
+        readonly phase: "before";
+        readonly hookTimeoutMs: 5000;
+        readonly eventBudgetMs: 10000;
+    };
+    readonly 'node:start': {
+        readonly phase: "on";
+        readonly hookTimeoutMs: 5000;
+        readonly eventBudgetMs: 10000;
+    };
+    readonly 'node:close': {
+        readonly phase: "on";
+        readonly hookTimeoutMs: 120000;
+        readonly eventBudgetMs: 180000;
+    };
+};
+export type LifecycleEvent = keyof typeof LIFECYCLE_CATALOG;
+export type LifecycleHookPhase = (typeof LIFECYCLE_CATALOG)[LifecycleEvent]['phase'];
+export declare const LIFECYCLE_EVENTS: readonly ("node:create" | "node:start" | "node:close")[];
 export declare function isLifecycleEvent(value: string): value is LifecycleEvent;

package/dist/core/command-hooks/lifecycle-catalog.js

@@ -1,4 +1,9 @@
-export const LIFECYCLE_EVENTS = ['node:start', 'node:close'];
+export const LIFECYCLE_CATALOG = {
+    'node:create': { phase: 'before', hookTimeoutMs: 5_000, eventBudgetMs: 10_000 },
+    'node:start': { phase: 'on', hookTimeoutMs: 5_000, eventBudgetMs: 10_000 },
+    'node:close': { phase: 'on', hookTimeoutMs: 120_000, eventBudgetMs: 180_000 },
+};
+export const LIFECYCLE_EVENTS = Object.freeze(Object.keys(LIFECYCLE_CATALOG));
 export function isLifecycleEvent(value) {
-    return LIFECYCLE_EVENTS.includes(value);
+    return Object.hasOwn(LIFECYCLE_CATALOG, value);
 }

package/dist/core/command-hooks/lifecycle-create.d.ts

@@ -0,0 +1,4 @@
+import type { NodeCreateHookRequest } from '../../hook-authoring.js';
+export type NodeCreateRequest = NodeCreateHookRequest['create'];
+/** Admit one node creation and return the release that must run after its row exists. */
+export declare function admitNodeCreate(create: NodeCreateRequest): Promise<() => void>;

package/dist/core/command-hooks/lifecycle-create.js

@@ -0,0 +1,51 @@
+import { crtrHome } from '../canvas/paths.js';
+import { nodeCreateRefused } from '../errors.js';
+import { discoverLifecycleHookRegistry } from './discovery.js';
+import { invokeBlockingLifecycleHooks } from './transport/exec-lifecycle.js';
+let nodeCreateGate = Promise.resolve();
+async function enterNodeCreateGate() {
+    let resolve;
+    const previous = nodeCreateGate;
+    nodeCreateGate = new Promise((release) => { resolve = release; });
+    await previous;
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        resolve();
+    };
+}
+function refusedCreateHookDiscovery(cwd, profileId) {
+    const registry = discoverLifecycleHookRegistry(cwd, profileId);
+    const plan = registry.plans.get('node:create') ?? [];
+    const failed = registry.validations.flatMap((validation) => validation.lifecycleCandidates
+        .filter((candidate) => candidate.event === 'node:create' && !plan.some((hook) => hook.plugin.name === validation.plugin.name && hook.declarationIndex === candidate.index))
+        .map((candidate) => ({
+        validation,
+        candidate,
+        issue: validation.issues.find((issue) => issue.path === `lifecycle[${candidate.index}]` || issue.path?.startsWith(`lifecycle[${candidate.index}].`)) ?? validation.issues[0],
+    })))[0];
+    if (failed === undefined)
+        return registry;
+    const { validation, candidate, issue } = failed;
+    throw nodeCreateRefused(`plugin "${validation.plugin.name}" lifecycle hook "${candidate.op}" for node:create could not be discovered: ${issue.message}`, `Refused by plugin ${validation.plugin.name}, op ${candidate.op}.`);
+}
+/** Admit one node creation and return the release that must run after its row exists. */
+export async function admitNodeCreate(create) {
+    const release = await enterNodeCreateGate();
+    try {
+        const registry = refusedCreateHookDiscovery(create.cwd, create.profile);
+        const refusal = await invokeBlockingLifecycleHooks(registry.plans.get('node:create') ?? [], {
+            create,
+            runtime: { canvasHome: crtrHome(), profile: create.profile },
+        });
+        if (refusal !== null)
+            throw nodeCreateRefused(refusal.message, refusal.next);
+        return release;
+    }
+    catch (error) {
+        release();
+        throw error;
+    }
+}

package/dist/core/command-hooks/schema.d.ts

@@ -1,6 +1,6 @@
-import { type LifecycleEvent } from './lifecycle-catalog.js';
+import { type LifecycleEvent, type LifecycleHookPhase } from './lifecycle-catalog.js';
+export type { LifecycleHookPhase } from './lifecycle-catalog.js';
 export type HookPhase = 'before' | 'after' | 'replace';
-export type LifecycleHookPhase = 'on';
 export interface DeclaredHook {
     target: string;
     phase: HookPhase;

package/dist/core/command-hooks/schema.js

@@ -1,5 +1,5 @@
 import { isRecord } from '../../shared/predicates.js';
-import { LIFECYCLE_EVENTS, isLifecycleEvent } from './lifecycle-catalog.js';
+import { LIFECYCLE_CATALOG, LIFECYCLE_EVENTS, isLifecycleEvent } from './lifecycle-catalog.js';
 function typeName(value) {
     if (value === null)
         return 'null';
@@ -61,8 +61,9 @@ function validateLifecycleDeclaration(value, index, issue) {
         issue('hook_manifest_invalid', 'event must name a supported lifecycle event', String(value['event']), LIFECYCLE_EVENTS.join(' | '), `Set event to one of: ${LIFECYCLE_EVENTS.join(', ')}.`, `${path}.event`);
         return undefined;
     }
-    if (value['phase'] !== 'on') {
-        issue('hook_manifest_invalid', 'phase must be on', String(value['phase']), 'on', 'Set phase to on.', `${path}.phase`);
+    const phase = LIFECYCLE_CATALOG[value['event']].phase;
+    if (value['phase'] !== phase) {
+        issue('hook_manifest_invalid', `phase must be ${phase}`, String(value['phase']), phase, `Set phase to ${phase}.`, `${path}.phase`);
         return undefined;
     }
     if (!isEffects(value['effects'])) {
@@ -71,7 +72,7 @@ function validateLifecycleDeclaration(value, index, issue) {
     }
     return {
         event: value['event'],
-        phase: 'on',
+        phase,
         op: value['op'],
         description: value['description'],
         effects: value['effects'],

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

@@ -170,7 +170,9 @@ function buildRequest(spec, invocation, cwd) {
     if (invocation.result !== undefined) {
         throw protocolError(spec, invocation, `${spec.phase} hook invocation included a result`, 'result only for after hooks');
     }
-    return { ...base, phase: spec.phase };
+    if (spec.phase === 'before')
+        return { ...base, phase: 'before' };
+    return { ...base, phase: 'replace' };
 }
 function parseEnvelope(spec, invocation, stdout) {
     let value;

package/dist/core/command-hooks/transport/exec-lifecycle.d.ts

@@ -1,12 +1,22 @@
-import type { LifecycleHookRequest } from '../../../hook-authoring.js';
+import type { LifecycleHookRequest, NodeCreateHookRequest } from '../../../hook-authoring.js';
 import type { EffectiveLifecycleHook } from '../discovery.js';
-export declare const LIFECYCLE_HOOK_TIMEOUT_MS = 5000;
-export declare const LIFECYCLE_EVENT_BUDGET_MS = 10000;
-export interface LifecycleHookInvocation {
+export interface NodeLifecycleHookInvocation {
     node: LifecycleHookRequest['node'];
     runtime: LifecycleHookRequest['runtime'];
 }
-/** Runs one lifecycle hook. The node launch remains authoritative on every failure. */
-export declare function invokeLifecycleHook(hook: EffectiveLifecycleHook, invocation: LifecycleHookInvocation, timeoutMs: number): Promise<void>;
-/** Executes lifecycle hooks in discovery order, within one bounded event budget. */
-export declare function invokeLifecycleHooks(hooks: readonly EffectiveLifecycleHook[], invocation: LifecycleHookInvocation): Promise<void>;
+export interface NodeCreateHookInvocation {
+    create: NodeCreateHookRequest['create'];
+    runtime: NodeCreateHookRequest['runtime'];
+}
+export interface BlockingLifecycleHookRefusal {
+    hook: EffectiveLifecycleHook;
+    message: string;
+    next: string;
+}
+/** Runs one lifecycle hook. `node:start` and `node:close` remain best-effort. */
+export declare function invokeLifecycleHook(hook: EffectiveLifecycleHook, invocation: NodeLifecycleHookInvocation, timeoutMs: number): Promise<void>;
+/** Executes non-blocking lifecycle hooks in discovery order within the event's catalogued budget. */
+export declare function invokeLifecycleHooks(hooks: readonly EffectiveLifecycleHook[], invocation: NodeLifecycleHookInvocation): Promise<void>;
+/** Runs blocking `node:create` hooks. Every protocol or process failure refuses the create. */
+export declare function invokeBlockingLifecycleHooks(hooks: readonly EffectiveLifecycleHook[], invocation: NodeCreateHookInvocation): Promise<BlockingLifecycleHookRefusal | null>;
+export declare function lifecycleHookAttribution(hook: EffectiveLifecycleHook): string;

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.