@north-light/crouter 0.3.269 → 0.3.270

package/dist/core/__tests__/seam/dormancy-release.test.js

@@ -79,7 +79,7 @@ test('idle-release settles its real watcher before exit; daemon revives exactly
             },
         },
     });
-    reviveNode(manager, { resume: true, capacity: 'freeze' });
+    await reviveNode(manager, { resume: true, capacity: 'freeze' });
     await h.awaitBoot(manager);
     // A live managed child makes this unfocused terminal manager legitimately
     // awaiting, so its real stophook takes the idle-release branch.
@@ -172,7 +172,7 @@ test('an unattended resident with no live obligation completes on the daemon clo
             },
         });
         subscribe(root, nodeId, true);
-        reviveNode(nodeId, { resume: true, capacity: 'freeze' });
+        await reviveNode(nodeId, { resume: true, capacity: 'freeze' });
         const boot = await h.awaitBoot(nodeId);
         assert.equal(h.fleet.has(nodeId), true, 'the revived broker is fleet-owned');
         const seenAt = 10_000;
@@ -223,7 +223,7 @@ test('a non-attending observer does not prevent unattended resident parking', {
         intent: 'idle-release',
     });
     updateNode(nodeId, { launch: { extensions: [], tools: [], systemPrompt: '', env: {} } });
-    reviveNode(nodeId, { resume: true, capacity: 'freeze' });
+    await reviveNode(nodeId, { resume: true, capacity: 'freeze' });
     const boot = await h.awaitBoot(nodeId);
     await attach.attach(nodeId, 'observer', 'system-observer-test', { attends: false });
     assert.equal(JSON.parse(readFileSync(join(h.home, 'nodes', nodeId, 'job', 'attach.json'), 'utf8')).viewers, 0, 'a non-attending hello is not persisted as human attendance');
@@ -268,7 +268,7 @@ test('a connected broker viewer keeps an obligation-free resident live', { timeo
             env: {},
         },
     });
-    reviveNode(nodeId, { resume: true, capacity: 'freeze' });
+    await reviveNode(nodeId, { resume: true, capacity: 'freeze' });
     const boot = await h.awaitBoot(nodeId);
     // awaitBoot returns on the boot proof, which is written BEFORE the broker's
     // own `persistAttachState()` lays down the truthful zero state. Writing our
@@ -311,7 +311,7 @@ test('the unattended park clock cancels an obligation-free terminal node and spa
     try {
         const boot = async (id) => {
             updateNode(id, { launch: { extensions: [], tools: [], systemPrompt: '', env: {} } });
-            reviveNode(id, { resume: true, capacity: 'freeze' });
+            await reviveNode(id, { resume: true, capacity: 'freeze' });
             return (await h.awaitBoot(id)).pid;
         };
         const settled = h.fabricateBrokerNode({ id: 'terminal-no-work', parent: root, status: 'idle', intent: 'idle-release' });
@@ -378,7 +378,7 @@ test('a resident managed child parks without finalizing while a terminal child i
         subscribe(terminalManager, terminal, true);
         const boot = async (id) => {
             updateNode(id, { launch: { extensions: [], tools: [], systemPrompt: '', env: {} } });
-            reviveNode(id, { resume: true, capacity: 'freeze' });
+            await reviveNode(id, { resume: true, capacity: 'freeze' });
             return (await h.awaitBoot(id)).pid;
         };
         const residentPid = await boot(resident);
@@ -439,7 +439,7 @@ test('an unattended resident awaiting a live child remains wakeable', { timeout:
                 env: {},
             },
         });
-        reviveNode(nodeId, { resume: true, capacity: 'freeze' });
+        await reviveNode(nodeId, { resume: true, capacity: 'freeze' });
         const boot = await h.awaitBoot(nodeId);
         const seenAt = 20_000;
         await h.tick(seenAt);

package/dist/core/__tests__/seam/held-deferred-human-prompt.test.js

@@ -42,7 +42,7 @@ test('a Jiti-loaded watcher prepends its held deferred batch to a native broker
             },
         },
     });
-    reviveNode(nodeId, { resume: true, capacity: 'freeze' });
+    await reviveNode(nodeId, { resume: true, capacity: 'freeze' });
     await h.awaitBoot(nodeId);
     const entry = appendInbox(nodeId, {
         from: 'child',

package/dist/core/__tests__/seam/yield-refresh-transaction.test.js

@@ -73,11 +73,11 @@ test('yield-message survives one pre-session_start retry and clears on session_s
     // the retry still roots a fresh cycle carrying the note, never reopening the
     // old session. Driving reviveNode directly is exactly what focus's revive path
     // calls, minus a tmux pane this contract does not involve.
-    const focusRevive = reviveNode(id, { resume: true, capacity: 'freeze' });
+    const focusRevive = await reviveNode(id, { resume: true, capacity: 'freeze' });
     const focusPid = focusRevive.launch?.pid;
     assert.ok(focusPid != null, 'the competing focus invocation launches the replacement broker');
     assert.equal(focusRevive.resumed, false, 'refresh intent overrides this invocation\'s strict-resume request');
-    assert.equal(h.fleet.get(id)?.pid, focusPid, 'the focus invocation synchronously owns the authoritative fleet slot');
+    assert.equal(h.fleet.get(id)?.pid, focusPid, 'the focus invocation owns the authoritative fleet slot');
     // Registering the manual launch cancels the exit policy's deferred recovery.
     // Its pid must therefore be the successful observed boot, proving these
     // assertions belong to the contender above rather than an already-queued boot.

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

@@ -1,6 +1,7 @@
 import type { InstalledPlugin } from '../../types.js';
 import type { CoreHookCatalog } from './catalog.js';
-import type { HookManifestIssue, HookPhase, ValidatedHookManifest } from './schema.js';
+import type { HookManifestIssue, HookPhase, LifecycleHookPhase, ValidatedHookManifest } from './schema.js';
+import type { LifecycleEvent } from './lifecycle-catalog.js';
 export type HookDiscoveryIssueCode = HookManifestIssue['code'] | 'command_hook_target_invalid' | 'command_hook_collision';
 export interface HookDiscoveryIssue {
     code: HookDiscoveryIssueCode;
@@ -38,6 +39,27 @@ export interface EffectiveHookPlan {
     after: readonly EffectiveHook[];
     replacements: readonly EffectiveHook[];
 }
+/** One lifecycle declaration resolved to the local executable that receives it. */
+export interface EffectiveLifecycleHook {
+    executable: string;
+    plugin: HookPluginAttribution;
+    event: LifecycleEvent;
+    phase: LifecycleHookPhase;
+    op: string;
+    description: string;
+    effects: readonly string[];
+    /** Index in this plugin's lifecycle declaration array. */
+    declarationIndex: number;
+    /** Stable discovery order: scope, lexical plugin name, declaration index. */
+    order: number;
+}
+export interface LifecycleHookRegistry {
+    hooks: readonly EffectiveLifecycleHook[];
+    plans: ReadonlyMap<LifecycleEvent, readonly EffectiveLifecycleHook[]>;
+    validations: readonly HookPluginValidation[];
+    issues: readonly HookDiscoveryIssue[];
+    valid: boolean;
+}
 export interface HookPluginValidation {
     plugin: InstalledPlugin;
     manifestPath?: string;
@@ -74,6 +96,10 @@ export interface HookPluginCandidate {
  * manifest files to validate them but never executes a plugin executable.
  */
 export declare function compileHookRegistry(catalog: CoreHookCatalog, plugins: readonly InstalledPlugin[]): HookRegistry;
+/** Compiles lifecycle declarations from resolved plugins without loading the command tree. */
+export declare function compileLifecycleHookRegistry(plugins: readonly InstalledPlugin[]): LifecycleHookRegistry;
+/** Discovers lifecycle hooks for one node's resolved cwd and profile. */
+export declare function discoverLifecycleHookRegistry(startDir: string, profileId?: string | null): LifecycleHookRegistry;
 /** Discovers and compiles the invocation-local effective registry. */
 export declare function discoverHookRegistry(catalog: CoreHookCatalog, startDir?: string, profileId?: string | null): HookRegistry;
 /** Compile the exact effective set a source candidate would create before its

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

@@ -153,6 +153,58 @@ export function compileHookRegistry(catalog, plugins) {
         valid: issues.length === 0,
     });
 }
+/** Compiles lifecycle declarations from resolved plugins without loading the command tree. */
+export function compileLifecycleHookRegistry(plugins) {
+    const validations = [];
+    const hooks = [];
+    const issues = [];
+    let order = 0;
+    for (const plugin of plugins) {
+        const artifact = validatePluginHookArtifact(plugin.root, plugin.manifest);
+        const pluginIssues = artifactIssues(plugin, artifact.issues);
+        let compiled = [];
+        if (pluginIssues.length === 0 && artifact.manifest !== undefined && artifact.executablePath !== undefined) {
+            const lifecycle = artifact.manifest.schemaVersion === 2 ? artifact.manifest.lifecycle : [];
+            compiled = lifecycle.map((hook, declarationIndex) => Object.freeze({
+                executable: artifact.executablePath,
+                plugin: Object.freeze({ name: plugin.name, scope: plugin.scope, root: plugin.root }),
+                event: hook.event,
+                phase: hook.phase,
+                op: hook.op,
+                description: hook.description,
+                effects: Object.freeze([...hook.effects]),
+                declarationIndex,
+                order: order++,
+            }));
+            hooks.push(...compiled);
+        }
+        validations.push(Object.freeze({
+            plugin,
+            ...(artifact.manifestPath === undefined ? {} : { manifestPath: artifact.manifestPath }),
+            ...(artifact.executablePath === undefined ? {} : { executablePath: artifact.executablePath }),
+            ...(artifact.manifest === undefined ? {} : { manifest: artifact.manifest }),
+            hooks: Object.freeze([]),
+            issues: Object.freeze(pluginIssues),
+        }));
+        issues.push(...pluginIssues);
+    }
+    const plans = new Map();
+    for (const hook of hooks) {
+        const entries = plans.get(hook.event) ?? [];
+        plans.set(hook.event, Object.freeze([...entries, hook]));
+    }
+    return Object.freeze({
+        hooks: Object.freeze(hooks),
+        plans,
+        validations: Object.freeze(validations),
+        issues: Object.freeze(issues),
+        valid: issues.length === 0,
+    });
+}
+/** Discovers lifecycle hooks for one node's resolved cwd and profile. */
+export function discoverLifecycleHookRegistry(startDir, profileId) {
+    return compileLifecycleHookRegistry(effectiveHookPlugins(startDir, profileId));
+}
 /** Discovers and compiles the invocation-local effective registry. */
 export function discoverHookRegistry(catalog, startDir = process.cwd(), profileId) {
     return compileHookRegistry(catalog, effectiveHookPlugins(startDir, profileId));

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

@@ -1,6 +1,7 @@
 export { createCoreHookCatalog, type CoreHookCatalog, type CoreHookTarget } from './catalog.js';
 export { projectEffectiveLeafHelp } from './help.js';
-export { compileHookRegistry, discoverCandidateHookRegistry, discoverHookRegistry, discoverHookRegistryInScopes, effectiveHookPlugins, hookDiscoveryScopes, type EffectiveHook, type EffectiveHookPlan, type HookDiscoveryIssue, type HookPluginAttribution, type HookPluginValidation, type HookRegistry, type HookScope, } from './discovery.js';
+export { compileHookRegistry, compileLifecycleHookRegistry, discoverCandidateHookRegistry, discoverHookRegistry, discoverHookRegistryInScopes, discoverLifecycleHookRegistry, effectiveHookPlugins, hookDiscoveryScopes, type EffectiveHook, type EffectiveHookPlan, type EffectiveLifecycleHook, type HookDiscoveryIssue, type HookPluginAttribution, type HookPluginValidation, type HookRegistry, type HookScope, type LifecycleHookRegistry, } from './discovery.js';
 export { validatePluginHookArtifact, type HookArtifactValidation } from './artifact.js';
-export { hasDeclaredHooks, hookReport, HOOK_TRUST_WARNING, type HookDeclarationReport, type HookReport } from './report.js';
-export { validateHookManifest, type DeclaredHook, type HookManifestIssue, type HookManifestValidation, type HookPhase, type ValidatedHookManifest, } from './schema.js';
+export { hasDeclaredHooks, hookReport, HOOK_TRUST_WARNING, type HookDeclarationReport, type HookReport, type LifecycleHookDeclarationReport } from './report.js';
+export { validateHookManifest, type DeclaredHook, type DeclaredLifecycleHook, type HookManifestIssue, type HookManifestValidation, type HookPhase, type LifecycleHookPhase, type ValidatedHookManifest, } from './schema.js';
+export { LIFECYCLE_EVENTS, isLifecycleEvent, type LifecycleEvent } from './lifecycle-catalog.js';

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

@@ -1,6 +1,7 @@
 export { createCoreHookCatalog } from './catalog.js';
 export { projectEffectiveLeafHelp } from './help.js';
-export { compileHookRegistry, discoverCandidateHookRegistry, discoverHookRegistry, discoverHookRegistryInScopes, effectiveHookPlugins, hookDiscoveryScopes, } from './discovery.js';
+export { compileHookRegistry, compileLifecycleHookRegistry, discoverCandidateHookRegistry, discoverHookRegistry, discoverHookRegistryInScopes, discoverLifecycleHookRegistry, effectiveHookPlugins, hookDiscoveryScopes, } from './discovery.js';
 export { validatePluginHookArtifact } from './artifact.js';
 export { hasDeclaredHooks, hookReport, HOOK_TRUST_WARNING } from './report.js';
 export { validateHookManifest, } from './schema.js';
+export { LIFECYCLE_EVENTS, isLifecycleEvent } from './lifecycle-catalog.js';

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

@@ -0,0 +1,3 @@
+export declare const LIFECYCLE_EVENTS: readonly ["node:start"];
+export type LifecycleEvent = typeof LIFECYCLE_EVENTS[number];
+export declare function isLifecycleEvent(value: string): value is LifecycleEvent;

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

@@ -0,0 +1,4 @@
+export const LIFECYCLE_EVENTS = ['node:start'];
+export function isLifecycleEvent(value) {
+    return LIFECYCLE_EVENTS.includes(value);
+}

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

@@ -1,7 +1,7 @@
 import type { PluginManifest } from '../../types.js';
 import type { HookDiscoveryIssue, HookPluginValidation } from './discovery.js';
-import type { DeclaredHook } from './schema.js';
-export declare const HOOK_TRUST_WARNING = "Hooks receive normalized inputs; after hooks receive results. They run implicitly and may block or replace declared targets. The local executable runs with caller authority and can transmit received data.";
+import type { DeclaredHook, DeclaredLifecycleHook } from './schema.js';
+export declare const HOOK_TRUST_WARNING = "Command hooks receive normalized inputs and may block or replace declared targets. Lifecycle hooks run unprompted at every declared event before node launch. Both run local executables with runtime authority and may transmit received data.";
 export interface HookDeclarationReport {
     target: string;
     phase: DeclaredHook['phase'];
@@ -9,6 +9,13 @@ export interface HookDeclarationReport {
     description: string;
     effects: readonly string[];
 }
+export interface LifecycleHookDeclarationReport {
+    event: DeclaredLifecycleHook['event'];
+    phase: DeclaredLifecycleHook['phase'];
+    op: string;
+    description: string;
+    effects: readonly string[];
+}
 /** One static hook artifact report shared by plugin inspection and lifecycle
  * output. It only reads declarations and filesystem metadata; it never runs
  * the hook executable. */
@@ -16,6 +23,8 @@ export interface HookReport {
     manifestPath?: string;
     executablePath?: string;
     declarations: readonly HookDeclarationReport[];
+    /** Present only for schemaVersion 2 manifests. */
+    lifecycle?: readonly LifecycleHookDeclarationReport[];
     issues: readonly HookDiscoveryIssue[];
     trust: typeof HOOK_TRUST_WARNING;
 }

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

@@ -1,4 +1,4 @@
-export const HOOK_TRUST_WARNING = 'Hooks receive normalized inputs; after hooks receive results. They run implicitly and may block or replace declared targets. The local executable runs with caller authority and can transmit received data.';
+export const HOOK_TRUST_WARNING = 'Command hooks receive normalized inputs and may block or replace declared targets. Lifecycle hooks run unprompted at every declared event before node launch. Both run local executables with runtime authority and may transmit received data.';
 export function hasDeclaredHooks(manifest) {
     return manifest.hooks !== undefined || manifest.hookExecutable !== undefined;
 }
@@ -13,6 +13,15 @@ export function hookReport(validation, issues = validation.issues) {
             description: hook.description,
             effects: Object.freeze([...hook.effects]),
         }))),
+        ...(validation.manifest?.schemaVersion === 2 ? {
+            lifecycle: Object.freeze(validation.manifest.lifecycle.map((hook) => Object.freeze({
+                event: hook.event,
+                phase: hook.phase,
+                op: hook.op,
+                description: hook.description,
+                effects: Object.freeze([...hook.effects]),
+            }))),
+        } : {}),
         issues: Object.freeze([...issues]),
         trust: HOOK_TRUST_WARNING,
     });

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

@@ -1,4 +1,6 @@
+import { type LifecycleEvent } from './lifecycle-catalog.js';
 export type HookPhase = 'before' | 'after' | 'replace';
+export type LifecycleHookPhase = 'on';
 export interface DeclaredHook {
     target: string;
     phase: HookPhase;
@@ -6,10 +8,23 @@ export interface DeclaredHook {
     description: string;
     effects: string[];
 }
-export interface ValidatedHookManifest {
+export interface DeclaredLifecycleHook {
+    event: LifecycleEvent;
+    phase: LifecycleHookPhase;
+    op: string;
+    description: string;
+    effects: string[];
+}
+export interface ValidatedV1HookManifest {
     schemaVersion: 1;
     hooks: DeclaredHook[];
 }
+export interface ValidatedV2HookManifest {
+    schemaVersion: 2;
+    hooks: DeclaredHook[];
+    lifecycle: DeclaredLifecycleHook[];
+}
+export type ValidatedHookManifest = ValidatedV1HookManifest | ValidatedV2HookManifest;
 export type HookIssueCode = 'hook_manifest_unreadable' | 'hook_manifest_invalid' | 'hook_schema_version' | 'hook_path_unsafe' | 'hook_not_executable';
 export interface HookManifestIssue {
     code: HookIssueCode;

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

@@ -1,4 +1,5 @@
 import { isRecord } from '../../shared/predicates.js';
+import { LIFECYCLE_EVENTS, isLifecycleEvent } from './lifecycle-catalog.js';
 function typeName(value) {
     if (value === null)
         return 'null';
@@ -6,6 +7,98 @@ function typeName(value) {
         return 'array';
     return typeof value;
 }
+function validateCommandDeclaration(value, index, issue) {
+    const path = `hooks[${index}]`;
+    if (!isRecord(value)) {
+        issue('hook_manifest_invalid', 'hook must be an object', typeName(value), '{ target, phase, op, description, effects }', 'Fix the hook declaration.', path);
+        return undefined;
+    }
+    const keys = Object.keys(value).filter((key) => !['target', 'phase', 'op', 'description', 'effects'].includes(key));
+    if (keys.length > 0) {
+        issue('hook_manifest_invalid', 'unknown hook keys', keys.join(', '), 'only: target, phase, op, description, effects', 'Remove the unknown keys.', path);
+        return undefined;
+    }
+    for (const field of ['target', 'op', 'description']) {
+        if (typeof value[field] !== 'string' || value[field].length === 0) {
+            issue('hook_manifest_invalid', `${field} must be a non-empty string`, typeName(value[field]), 'a non-empty string', `Set ${field}.`, `${path}.${field}`);
+            return undefined;
+        }
+    }
+    if (value['phase'] !== 'before' && value['phase'] !== 'after' && value['phase'] !== 'replace') {
+        issue('hook_manifest_invalid', 'phase must be before|after|replace', String(value['phase']), 'before | after | replace', 'Set phase to a supported hook phase.', `${path}.phase`);
+        return undefined;
+    }
+    if (!isEffects(value['effects'])) {
+        issue('hook_manifest_invalid', 'effects must be a non-empty string array', typeName(value['effects']), 'a non-empty array of non-empty strings', 'Declare every persistent effect.', `${path}.effects`);
+        return undefined;
+    }
+    return {
+        target: value['target'],
+        phase: value['phase'],
+        op: value['op'],
+        description: value['description'],
+        effects: value['effects'],
+    };
+}
+function validateLifecycleDeclaration(value, index, issue) {
+    const path = `lifecycle[${index}]`;
+    if (!isRecord(value)) {
+        issue('hook_manifest_invalid', 'lifecycle hook must be an object', typeName(value), '{ event, phase, op, description, effects }', 'Fix the lifecycle declaration.', path);
+        return undefined;
+    }
+    const keys = Object.keys(value).filter((key) => !['event', 'phase', 'op', 'description', 'effects'].includes(key));
+    if (keys.length > 0) {
+        issue('hook_manifest_invalid', 'unknown lifecycle hook keys', keys.join(', '), 'only: event, phase, op, description, effects', 'Remove the unknown keys.', path);
+        return undefined;
+    }
+    for (const field of ['event', 'op', 'description']) {
+        if (typeof value[field] !== 'string' || value[field].length === 0) {
+            issue('hook_manifest_invalid', `${field} must be a non-empty string`, typeName(value[field]), 'a non-empty string', `Set ${field}.`, `${path}.${field}`);
+            return undefined;
+        }
+    }
+    if (!isLifecycleEvent(value['event'])) {
+        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`);
+        return undefined;
+    }
+    if (!isEffects(value['effects'])) {
+        issue('hook_manifest_invalid', 'effects must be a non-empty string array', typeName(value['effects']), 'a non-empty array of non-empty strings', 'Declare every persistent effect.', `${path}.effects`);
+        return undefined;
+    }
+    return {
+        event: value['event'],
+        phase: 'on',
+        op: value['op'],
+        description: value['description'],
+        effects: value['effects'],
+    };
+}
+function isEffects(value) {
+    return Array.isArray(value) && value.length > 0 && value.every((effect) => typeof effect === 'string' && effect.length > 0);
+}
+function validateV1(raw, issue) {
+    const unknown = Object.keys(raw).filter((key) => key !== 'schemaVersion' && key !== 'hooks');
+    if (unknown.length > 0) {
+        issue('hook_manifest_invalid', 'unknown top-level keys', unknown.join(', '), 'only: schemaVersion, hooks', 'Remove the unknown keys.');
+        return { issues: [] };
+    }
+    if (!Array.isArray(raw['hooks']) || raw['hooks'].length === 0) {
+        issue('hook_manifest_invalid', 'hooks must be a non-empty array', typeName(raw['hooks']), 'a non-empty array of hook declarations', 'Declare at least one hook.', 'hooks');
+        return { issues: [] };
+    }
+    const hooks = [];
+    for (let index = 0; index < raw['hooks'].length; index++) {
+        const hook = validateCommandDeclaration(raw['hooks'][index], index, issue);
+        if (hook === undefined)
+            return { issues: [] };
+        hooks.push(hook);
+    }
+    return { manifest: { schemaVersion: 1, hooks }, issues: [] };
+}
 /** Validates the declarative hooks.json payload without filesystem access. */
 export function validateHookManifest(raw) {
     const issues = [];
@@ -16,53 +109,48 @@ export function validateHookManifest(raw) {
         issue('hook_manifest_invalid', 'manifest must be an object', typeName(raw), '{ schemaVersion, hooks }', 'Provide a valid hooks.json manifest.');
         return { issues };
     }
-    const unknown = Object.keys(raw).filter((key) => key !== 'schemaVersion' && key !== 'hooks');
+    if (raw['schemaVersion'] === 1) {
+        const validation = validateV1(raw, issue);
+        return { ...(validation.manifest === undefined ? {} : { manifest: validation.manifest }), issues };
+    }
+    if (raw['schemaVersion'] !== 2) {
+        issue('hook_schema_version', 'schemaVersion must be exactly 1 or 2', String(raw['schemaVersion']), '1 | 2', 'Update the manifest schema version to 1 or 2.', 'schemaVersion');
+        return { issues };
+    }
+    const unknown = Object.keys(raw).filter((key) => key !== 'schemaVersion' && key !== 'hooks' && key !== 'lifecycle');
     if (unknown.length > 0) {
-        issue('hook_manifest_invalid', 'unknown top-level keys', unknown.join(', '), 'only: schemaVersion, hooks', 'Remove the unknown keys.');
+        issue('hook_manifest_invalid', 'unknown top-level keys', unknown.join(', '), 'only: schemaVersion, hooks, lifecycle', 'Remove the unknown keys.');
         return { issues };
     }
-    if (raw['schemaVersion'] !== 1) {
-        issue('hook_schema_version', 'schemaVersion must be exactly 1', String(raw['schemaVersion']), '1', 'Update the manifest schema version to 1.', 'schemaVersion');
+    const rawHooks = raw['hooks'];
+    const rawLifecycle = raw['lifecycle'];
+    if (rawHooks !== undefined && !Array.isArray(rawHooks)) {
+        issue('hook_manifest_invalid', 'hooks must be an array when present', typeName(rawHooks), 'an array of hook declarations', 'Fix hooks.', 'hooks');
         return { issues };
     }
-    if (!Array.isArray(raw['hooks']) || raw['hooks'].length === 0) {
-        issue('hook_manifest_invalid', 'hooks must be a non-empty array', typeName(raw['hooks']), 'a non-empty array of hook declarations', 'Declare at least one hook.', 'hooks');
+    if (rawLifecycle !== undefined && !Array.isArray(rawLifecycle)) {
+        issue('hook_manifest_invalid', 'lifecycle must be an array when present', typeName(rawLifecycle), 'an array of lifecycle hook declarations', 'Fix lifecycle.', 'lifecycle');
         return { issues };
     }
-    const hooks = [];
-    for (let index = 0; index < raw['hooks'].length; index++) {
-        const value = raw['hooks'][index];
-        const path = `hooks[${index}]`;
-        if (!isRecord(value)) {
-            issue('hook_manifest_invalid', 'hook must be an object', typeName(value), '{ target, phase, op, description, effects }', 'Fix the hook declaration.', path);
-            return { issues };
-        }
-        const keys = Object.keys(value).filter((key) => !['target', 'phase', 'op', 'description', 'effects'].includes(key));
-        if (keys.length > 0) {
-            issue('hook_manifest_invalid', 'unknown hook keys', keys.join(', '), 'only: target, phase, op, description, effects', 'Remove the unknown keys.', path);
-            return { issues };
-        }
-        for (const field of ['target', 'op', 'description']) {
-            if (typeof value[field] !== 'string' || value[field].length === 0) {
-                issue('hook_manifest_invalid', `${field} must be a non-empty string`, typeName(value[field]), 'a non-empty string', `Set ${field}.`, `${path}.${field}`);
-                return { issues };
-            }
-        }
-        if (value['phase'] !== 'before' && value['phase'] !== 'after' && value['phase'] !== 'replace') {
-            issue('hook_manifest_invalid', 'phase must be before|after|replace', String(value['phase']), 'before | after | replace', 'Set phase to a supported hook phase.', `${path}.phase`);
+    const hooks = rawHooks ?? [];
+    const lifecycle = rawLifecycle ?? [];
+    if (hooks.length === 0 && lifecycle.length === 0) {
+        issue('hook_manifest_invalid', 'hooks or lifecycle must be a non-empty array', 'both arrays were empty or absent', 'at least one command or lifecycle hook declaration', 'Declare at least one hook.', 'hooks');
+        return { issues };
+    }
+    const declaredHooks = [];
+    for (let index = 0; index < hooks.length; index++) {
+        const hook = validateCommandDeclaration(hooks[index], index, issue);
+        if (hook === undefined)
             return { issues };
-        }
-        if (!Array.isArray(value['effects']) || value['effects'].length === 0 || !value['effects'].every((effect) => typeof effect === 'string' && effect.length > 0)) {
-            issue('hook_manifest_invalid', 'effects must be a non-empty string array', typeName(value['effects']), 'a non-empty array of non-empty strings', 'Declare every persistent effect.', `${path}.effects`);
+        declaredHooks.push(hook);
+    }
+    const declaredLifecycle = [];
+    for (let index = 0; index < lifecycle.length; index++) {
+        const hook = validateLifecycleDeclaration(lifecycle[index], index, issue);
+        if (hook === undefined)
             return { issues };
-        }
-        hooks.push({
-            target: value['target'],
-            phase: value['phase'],
-            op: value['op'],
-            description: value['description'],
-            effects: value['effects'],
-        });
-    }
-    return { manifest: { schemaVersion: 1, hooks }, issues };
+        declaredLifecycle.push(hook);
+    }
+    return { manifest: { schemaVersion: 2, hooks: declaredHooks, lifecycle: declaredLifecycle }, issues };
 }

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

@@ -0,0 +1,12 @@
+import type { LifecycleHookRequest } 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 {
+    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 start-event budget. */
+export declare function invokeLifecycleHooks(hooks: readonly EffectiveLifecycleHook[], invocation: LifecycleHookInvocation): Promise<void>;