@north-light/crouter 0.3.311 → 0.3.312

package/dist/core/__tests__/on-read-nested-store.test.js

@@ -76,9 +76,9 @@ function makeWorkTree() {
         'NESTED NEIGHBOUR BODY\n');
     return work;
 }
-test('a nested store front door surfaces on a read beneath its owning dir, not outside it', () => {
+test('a nested store front door surfaces on a read beneath its owning dir, not outside it', async () => {
     const work = makeWorkTree();
-    const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
+    const node = (await spawnNode({ kind: 'general', cwd: work, parent: null })).node_id;
     const inside = join(work, 'pkg', 'lib', 'file.ts');
     mkdirSync(join(work, 'pkg', 'lib'), { recursive: true });
     writeFileSync(inside, 'export const x = 1;\n');
@@ -93,9 +93,9 @@ test('a nested store front door surfaces on a read beneath its owning dir, not o
     const renderedOutside = renderOnReadDocs(node, outside, freshTranscriptTarget());
     assert.ok(!renderedOutside.includes(NESTED_BODY), `read outside pkg must not surface the nested front door; got: ${renderedOutside}`);
 });
-test('workspace-open and on-read share one exposure ledger', () => {
+test('workspace-open and on-read share one exposure ledger', async () => {
     const work = makeWorkTree();
-    const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
+    const node = (await spawnNode({ kind: 'general', cwd: work, parent: null })).node_id;
     const transcript = freshTranscriptTarget();
     const opened = renderWorkspaceOpenDocs(node, transcript);
     assert.ok(opened.includes(ROOT_BODY), 'workspace open delivers the mounted root front door');
@@ -109,7 +109,7 @@ test('workspace-open and on-read share one exposure ledger', () => {
     assert.ok(onRead.includes('name="work/pkg"'), 'the nested front door answers under the root namespace plus owner path');
     assert.ok(!onRead.includes(ROOT_BODY), 'the root front door already delivered at workspace open — never twice');
 });
-test('a hand-authored `./`-anchored read glob in a user-scope doc never matches a read', () => {
+test('a hand-authored `./`-anchored read glob in a user-scope doc never matches a read', async () => {
     const userStore = join(fakeHome, '.crouter', 'memory');
     mkdirSync(userStore, { recursive: true });
     writeFileSync(join(userStore, 'control.md'), '---\nkind: knowledge\n' +
@@ -124,7 +124,7 @@ test('a hand-authored `./`-anchored read glob in a user-scope doc never matches
         'USER DOT BODY MUST NOT FIRE\n');
     const work = join(fakeHome, 'work');
     mkdirSync(work, { recursive: true });
-    const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
+    const node = (await spawnNode({ kind: 'general', cwd: work, parent: null })).node_id;
     const readFile = join(fakeHome, 'notes', 'thing.md');
     mkdirSync(join(fakeHome, 'notes'), { recursive: true });
     writeFileSync(readFile, '# a note\n');

package/dist/core/__tests__/profile-project-memory-delivery.test.js

@@ -350,11 +350,11 @@ after(() => {
     restore('CRTR_PROFILE_ID', prevProfile);
     restore('CRTR_NODE_ID', prevNode);
 });
-function newNode(kind = 'general') {
-    return spawnNode({ kind, cwd: cwdProject, parent: null, profile_id: profileId }).node_id;
+async function newNode(kind = 'general') {
+    return (await spawnNode({ kind, cwd: cwdProject, parent: null, profile_id: profileId })).node_id;
 }
-test('boot delivery caps every profile project at its relationship, including the one used as cwd', () => {
-    const boot = renderKnowledgeBlock(newNode(), freshTranscriptTarget());
+test('boot delivery caps every profile project at its relationship, including the one used as cwd', async () => {
+    const boot = renderKnowledgeBlock(await newNode(), freshTranscriptTarget());
     // The control: an uncapped relationship still renders its authored content.
     assert.ok(boot.includes(B.pcontent), `the content-capped project renders its body; got:\n${boot}`);
     // The reported failure. cwd reaches this root before the manifest pointer
@@ -369,22 +369,22 @@ test('boot delivery caps every profile project at its relationship, including th
     assert.match(boot, /[├└]─ t9-pname-doc$/m, `the name-capped doc discloses as a bare name; got:\n${boot}`);
     assert.ok(!boot.includes('When the name project delivers'), 'a name-capped doc discloses no preview line');
 });
-test('surface-entry gates select the rung by node kind while the document gate remains absolute', () => {
+test('surface-entry gates select the rung by node kind while the document gate remains absolute', async () => {
     for (const kind of ['design', 'spec', 'plan', 'developer']) {
-        const boot = renderKnowledgeBlock(newNode(kind), freshTranscriptTarget());
+        const boot = renderKnowledgeBlock(await newNode(kind), freshTranscriptTarget());
         assert.ok(boot.includes(B.kindSplit), `${kind} receives the content rung; got:\n${boot}`);
     }
     for (const kind of ['general', 'review', 'advisor']) {
-        const boot = renderKnowledgeBlock(newNode(kind), freshTranscriptTarget());
+        const boot = renderKnowledgeBlock(await newNode(kind), freshTranscriptTarget());
         assert.match(boot, /t9-kind-split {2}# read when: When the node needs this kind-specific guide\./, `${kind} receives the preview rung; got:\n${boot}`);
         assert.ok(!boot.includes(B.kindSplit), `${kind} does not receive the body`);
     }
     for (const kind of ['explore', 'personal-assistant']) {
-        const boot = renderKnowledgeBlock(newNode(kind), freshTranscriptTarget());
+        const boot = renderKnowledgeBlock(await newNode(kind), freshTranscriptTarget());
         assert.ok(!boot.includes('t9-kind-split'), `${kind} receives no kind-split entry; got:\n${boot}`);
         assert.ok(!boot.includes(B.kindSplit), `${kind} receives no kind-split body`);
     }
-    const developer = renderKnowledgeBlock(newNode('developer'), freshTranscriptTarget());
+    const developer = renderKnowledgeBlock(await newNode('developer'), freshTranscriptTarget());
     assert.ok(!developer.includes('t9-document-gate-wins'), `a failing document gate excludes every entry; got:\n${developer}`);
     assert.ok(!developer.includes(B.documentGateWins), 'a failing document gate excludes its content');
     assert.ok(developer.includes(B.codeCraftIndex), 'the directory document delivers its boot content');
@@ -394,8 +394,8 @@ test('surface-entry gates select the rung by node kind while the document gate r
     // The ancestor listing, not just the doc's own directory.
     assert.match(developer, /sibling {2}# read when: When the dev sibling applies\./, `content delivery exposes the enclosing directory's members too; got:\n${developer}`);
 });
-test('context docs accounting reports content attachment raises from the renderer', () => {
-    const node = newNode('developer');
+test('context docs accounting reports content attachment raises from the renderer', async () => {
+    const node = await newNode('developer');
     const subject = assembleNodeSubject(node);
     assert.ok(subject !== null, 'the fixture node assembles a subject');
     const target = { cwd: cwdProject, profileId, nodeId: node };
@@ -431,8 +431,8 @@ test('context docs accounting reports content attachment raises from the rendere
     assert.equal(viewerRecord?.deliveryCause, 'directory listing attached to content delivery');
     plans.dispose();
 });
-test('context docs accounting adds full-view workspace content attachments', () => {
-    const node = newNode();
+test('context docs accounting adds full-view workspace content attachments', async () => {
+    const node = await newNode();
     const subject = assembleNodeSubject(node);
     assert.ok(subject !== null, 'the fixture node assembles a subject');
     const target = { cwd: outsideProject, profileId, nodeId: node };
@@ -446,8 +446,8 @@ test('context docs accounting adds full-view workspace content attachments', ()
     assert.equal(companion?.final_rung, 'content');
     assert.equal(companion?.delivery_cause, 'memory-read companion of content delivery');
 });
-test('boot content triggers memory-read companions to a deduplicated fixpoint', () => {
-    const boot = renderKnowledgeBlock(newNode(), freshTranscriptTarget());
+test('boot content triggers memory-read companions to a deduplicated fixpoint', async () => {
+    const boot = renderKnowledgeBlock(await newNode(), freshTranscriptTarget());
     for (const body of [B.companionSource, B.companionA, B.companionB]) {
         assert.equal(boot.split(body).length - 1, 1, `content companion ${body} delivers once; got:\n${boot}`);
     }
@@ -455,8 +455,8 @@ test('boot content triggers memory-read companions to a deduplicated fixpoint',
     // discloses its members exactly as the doc that routed to it did.
     assert.match(boot, /member-1 {2}# read when: When the companion member applies\./, `a content companion exposes its own directory's members; got:\n${boot}`);
 });
-test('one body delivered across both boot partitions renders exactly once', () => {
-    const node = newNode();
+test('one body delivered across both boot partitions renders exactly once', async () => {
+    const node = await newNode();
     const subject = assembleNodeSubject(node);
     assert.ok(subject !== null, 'the fixture node assembles a subject');
     const state = emptyContextExposureState();
@@ -470,8 +470,8 @@ test('one body delivered across both boot partitions renders exactly once', () =
     const occurrences = (preferences.split(B.crossPartition).length - 1) + (knowledge.split(B.crossPartition).length - 1);
     assert.equal(occurrences, 1, `the companion body renders once across both partitions; got:\n${preferences}\n---\n${knowledge}`);
 });
-test('a node-local doc floors to name only without boot entries', () => {
-    const node = newNode('explore');
+test('a node-local doc floors to name only without boot entries', async () => {
+    const node = await newNode('explore');
     writeDoc(memoryDir(node), 't9-node-local-bootless', bootlessDoc('When the node-local fallback applies', 'BODY-T9-NODE-LOCAL-BOOTLESS'));
     writeDoc(memoryDir(node), 't9-node-local-entry-gated', [
         '---',
@@ -491,8 +491,8 @@ test('a node-local doc floors to name only without boot entries', () => {
     assert.ok(!boot.includes('t9-node-local-entry-gated'), `ineligible boot entries keep a node-local doc absent; got:\n${boot}`);
     assert.ok(!boot.includes('BODY-T9-NODE-LOCAL-ENTRY-GATED'), 'ineligible boot entries disclose no body');
 });
-test('a `none` project contributes nothing to boot — no body, no name, no hidden count, no shadow', () => {
-    const boot = renderKnowledgeBlock(newNode(), freshTranscriptTarget());
+test('a `none` project contributes nothing to boot — no body, no name, no hidden count, no shadow', async () => {
+    const boot = renderKnowledgeBlock(await newNode(), freshTranscriptTarget());
     assert.ok(!boot.includes(B.pnone), 'a none-capped body must not render');
     assert.ok(!boot.includes('pnone'), 'a none-capped store must not appear as a name either — not even its namespace row');
     // Hidden counts are disclosure too: the control project's namespace row proves
@@ -512,7 +512,7 @@ test('a capped nearer candidate yields the shared identity instead of suppressin
     // physical candidates. Automatic delivery filters candidates by the profile
     // cap BEFORE dedupe, so the `none`-capped nearer one drops out and the farther
     // one delivers; a deliberate read stays winner-only on source order.
-    const boot = renderKnowledgeBlock(newNode(), freshTranscriptTarget());
+    const boot = renderKnowledgeBlock(await newNode(), freshTranscriptTarget());
     assert.ok(boot.includes(B.dupFar), `the farther uncapped candidate delivers the shared identity; got:\n${boot}`);
     assert.ok(!boot.includes(B.dupNear), 'the none-capped nearer candidate delivers nothing');
     const read = (await readLeaf.run({
@@ -524,14 +524,14 @@ test('a capped nearer candidate yields the shared identity instead of suppressin
     }));
     assert.ok(read.content.includes(B.dupNear) && !read.content.includes(B.dupFar), `a deliberate read resolves the source-order winner; got:\n${read.content}`);
 });
-test('a non-none cap keeps its project precedence and discloses the duplicate at the capped rung', () => {
-    const boot = renderKnowledgeBlock(newNode(), freshTranscriptTarget());
+test('a non-none cap keeps its project precedence and discloses the duplicate at the capped rung', async () => {
+    const boot = renderKnowledgeBlock(await newNode(), freshTranscriptTarget());
     assert.match(boot, /[├└]─ t9-namedup-doc$/m, `the name-capped project discloses its doc as a bare name; got:\n${boot}`);
     assert.ok(!boot.includes(B.nameFromPname), 'a name-capped doc discloses at `name`, never its body');
     assert.ok(boot.includes(B.nameFromPcontent), 'the content project delivers its own distinct identity in full');
 });
-test('workspace-open clamps each project store the same way boot does', () => {
-    const opened = renderWorkspaceOpenDocs(newNode(), freshTranscriptTarget());
+test('workspace-open clamps each project store the same way boot does', async () => {
+    const opened = renderWorkspaceOpenDocs(await newNode(), freshTranscriptTarget());
     assert.ok(opened.includes(B.pcontent), `the content-capped project delivers its body; got:\n${opened}`);
     assert.ok(!opened.includes(B.ppreview), `the cwd project must not deliver its body; got:\n${opened}`);
     assert.match(opened, /name="ppreview\/t9-ppreview-doc" readWhen="When the cwd project delivers\./, `the cwd project delivers its preview line under its canonical name; got:\n${opened}`);
@@ -539,8 +539,8 @@ test('workspace-open clamps each project store the same way boot does', () => {
     assert.ok(!opened.includes('t9-pnone-doc'), 'the none-capped project delivers nothing at workspace-open');
     assert.ok(!opened.includes(B.sharedFromPnone), 'nor its side of a name collision');
 });
-test('workspace-open answers its listings from the workspace it opened, not the ambient one', () => {
-    const node = newNode();
+test('workspace-open answers its listings from the workspace it opened, not the ambient one', async () => {
+    const node = await newNode();
     const subject = assembleNodeSubject(node);
     assert.ok(subject !== null, 'the fixture node assembles a subject');
     // The process cwd is `ppreview`; this workspace is outside the profile
@@ -551,7 +551,7 @@ test('workspace-open answers its listings from the workspace it opened, not the
     assert.match(opened, /\[\[poutside\/t9-ws-guide\/member-1\]\]: When the outside guide member applies\./, `the listing carries that directory's own members; got:\n${opened}`);
 });
 test('memory list and find record synthetic pages without crediting matched documents', async () => {
-    const node = newNode();
+    const node = await newNode();
     process.env['CRTR_NODE_ID'] = node;
     try {
         const listed = await listLeaf.run({
@@ -589,7 +589,7 @@ test('memory list and find record synthetic pages without crediting matched docu
     }
 });
 test('an explicit read after boot content adds no duplicate directory attachments', async () => {
-    const node = newNode('developer');
+    const node = await newNode('developer');
     process.env['CRTR_NODE_ID'] = node;
     try {
         const state = loadContextExposureState(node);
@@ -614,7 +614,7 @@ test('an explicit read after boot content adds no duplicate directory attachment
     }
 });
 test('an explicit `crtr memory read` returns and records the full body a cap withheld', async () => {
-    const node = newNode();
+    const node = await newNode();
     process.env['CRTR_NODE_ID'] = node;
     const state = loadContextExposureState(node);
     const transcript = exposureTarget(state, 'transcript');

package/dist/core/__tests__/spawn-worktree-id-conflict.test.js

@@ -50,7 +50,7 @@ after(async () => {
 });
 test('a --worktree spawn at an already-existing node id throws and leaves NO worktree registered', async () => {
     const nodeId = 'duplicate-id';
-    spawnNode({ kind: 'general', cwd: '/tmp/work', nodeId });
+    await spawnNode({ kind: 'general', cwd: '/tmp/work', nodeId });
     await assert.rejects(() => spawnChild({ kind: 'general', cwd: repoDir, prompt: '', worktree: true, nodeId }));
     assert.ok(!existsSync(managedWorktreePath(nodeId)), 'the conflicting spawn must not leave a worktree checkout directory');
     assert.equal(gitSync(['show-ref', '--verify', '--quiet', `refs/heads/crtr/${nodeId}`], repoDir).status, 1, 'the conflicting spawn must not leave a registered crtr/<id> branch');
@@ -59,12 +59,12 @@ test('a --worktree spawn at an already-existing node id throws and leaves NO wor
     assert.equal(getNode(nodeId).kind, 'general');
     assert.equal(getNode(nodeId).managed_worktree, undefined);
 });
-test('spawnNode({ nodeId }): a hyphen-less opaque id spawns at the exact given id', () => {
+test('spawnNode({ nodeId }): a hyphen-less opaque id spawns at the exact given id', async () => {
     // Regression for the reviewed opaque-id-contract violation: the old validator
     // required >=2 hyphen segments and rejected a hyphen-less id outright,
     // contradicting the design's "opaque, never parsed for structure" ID scheme
     // that remote and cloud spawns depend on.
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', nodeId: 'remote42' });
+    const meta = await spawnNode({ kind: 'general', cwd: '/tmp/work', nodeId: 'remote42' });
     assert.equal(meta.node_id, 'remote42');
     assert.notEqual(getNode('remote42'), null);
 });

package/dist/core/__tests__/warm-claim-preference-snapshot.test.js

@@ -33,7 +33,7 @@ after(() => {
     delete process.env['CRTR_HOME'];
 });
 test('the claim path persists a frozen preference snapshot', async () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
+    const meta = await spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
     assert.equal(loadContextExposureState(meta.node_id).preferenceSnapshot, null, 'a spare mints with nothing frozen');
     await deliverBearingsLive(meta.node_id);
     assert.notEqual(loadContextExposureState(meta.node_id).preferenceSnapshot, null, 'claim freezes the snapshot the persona gate requires');

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

@@ -1,9 +1,15 @@
 import type { PluginManifest } from '../../types.js';
 import { type HookManifestIssue, type ValidatedHookManifest } from './schema.js';
+export interface LifecycleDeclarationCandidate {
+    event: string;
+    op: string;
+    index: number;
+}
 export interface HookArtifactValidation {
     manifestPath?: string;
     executablePath?: string;
     manifest?: ValidatedHookManifest;
+    lifecycleCandidates: readonly LifecycleDeclarationCandidate[];
     issues: HookManifestIssue[];
 }
 /** Statically validates the local hook artifact a source plugin ships. */

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;