@north-light/crouter 0.3.269 → 0.3.271

package/dist/core/__tests__/revive-parked-fresh.test.js

@@ -103,10 +103,10 @@ after(() => {
     else
         process.env['CRTR_HOME'] = priorHome;
 });
-test('a parked node with mail waiting re-enters fresh even when the caller asked to resume, and the marker clears', () => {
+test('a parked node with mail waiting re-enters fresh even when the caller asked to resume, and the marker clears', async () => {
     parkResident('parked', { roadmap: '# Roadmap\n\n- one open item\n' });
     deliverMail('parked');
-    const result = reviveNode('parked', { resume: true, capacity: 'freeze' });
+    const result = await reviveNode('parked', { resume: true, capacity: 'freeze' });
     assert.equal(result.resumed, false, 'the concluded transcript is not replayed');
     assert.deepEqual(placements(), [{ nodeId: 'parked', resuming: false }]);
     assert.equal(kickedOff(launches[0]), true, 'the fresh window is handed its bearings');
@@ -115,15 +115,15 @@ test('a parked node with mail waiting re-enters fresh even when the caller asked
     assert.equal(reopened.intent ?? null, null, 'the park marker clears on revival');
     assert.equal(reopened.cycle_pending, true, 'the fresh cycle is provisional until session_start confirms it');
 });
-test('a parked node grounded only by a goal still re-enters fresh when mail rides the revive', () => {
+test('a parked node grounded only by a goal still re-enters fresh when mail rides the revive', async () => {
     parkResident('goal-only', { goal: 'Watch the deploy lane.' });
     deliverMail('goal-only');
-    assert.equal(reviveNode('goal-only', { resume: true, capacity: 'freeze' }).resumed, false);
+    assert.equal((await reviveNode('goal-only', { resume: true, capacity: 'freeze' })).resumed, false);
     assert.equal(kickedOff(launches[0]), true);
 });
-test('an input-less revival of a parked node quietly resumes and injects no kickoff', () => {
+test('an input-less revival of a parked node quietly resumes and injects no kickoff', async () => {
     parkResident('quiet', { roadmap: '# Roadmap\n\n- one open item\n' });
-    const result = reviveNode('quiet', { resume: true, capacity: 'freeze' });
+    const result = await reviveNode('quiet', { resume: true, capacity: 'freeze' });
     assert.equal(result.resumed, true, 'nothing arrived, so there is nothing a fresh window would answer');
     assert.deepEqual(placements(), [{ nodeId: 'quiet', resuming: true }]);
     assert.equal(kickedOff(launches[0]), false, 'a quiet resume generates nothing');
@@ -132,29 +132,29 @@ test('an input-less revival of a parked node quietly resumes and injects no kick
     assert.equal(reopened.status, 'active');
     assert.equal(reopened.intent ?? null, null, 'the park marker clears on a quiet resume too');
 });
-test('deferred mail alone is not input, so the revival still resumes quietly', () => {
+test('deferred mail alone is not input, so the revival still resumes quietly', async () => {
     parkResident('deferred', { roadmap: '# Roadmap\n\n- one open item\n' });
     deliverMail('deferred', 'deferred');
-    assert.equal(reviveNode('deferred', { resume: true, capacity: 'freeze' }).resumed, true);
+    assert.equal((await reviveNode('deferred', { resume: true, capacity: 'freeze' })).resumed, true);
     assert.equal(kickedOff(launches[0]), false);
     assert.equal(readCursor('deferred'), undefined, 'the deferred entry rides the next natural cycle, unconsumed');
 });
-test('mail already covered by the cursor is not input, so the revival still resumes quietly', () => {
+test('mail already covered by the cursor is not input, so the revival still resumes quietly', async () => {
     parkResident('stale', { roadmap: '# Roadmap\n\n- one open item\n' });
     writeCursor('stale', deliverMail('stale'));
-    assert.equal(reviveNode('stale', { resume: true, capacity: 'freeze' }).resumed, true, 'only the UNSEEN suffix counts as input');
+    assert.equal((await reviveNode('stale', { resume: true, capacity: 'freeze' })).resumed, true, 'only the UNSEEN suffix counts as input');
     assert.equal(kickedOff(launches[0]), false);
 });
-test('a parked node with no goal and no roadmap resumes its transcript rather than waking amnesiac', () => {
+test('a parked node with no goal and no roadmap resumes its transcript rather than waking amnesiac', async () => {
     parkResident('bare');
     deliverMail('bare');
-    const result = reviveNode('bare', { resume: true, capacity: 'freeze' });
+    const result = await reviveNode('bare', { resume: true, capacity: 'freeze' });
     assert.equal(result.resumed, true, 'the degraded park has nothing on disk to ground a fresh window');
     assert.deepEqual(placements(), [{ nodeId: 'bare', resuming: true }]);
 });
-test('an ordinary done node with a roadmap still resumes — only the park marker vetoes', () => {
+test('an ordinary done node with a roadmap still resumes — only the park marker vetoes', async () => {
     parkResident('finished', { roadmap: '# Roadmap\n\n- one open item\n' });
     transition('finished', 'revive');
     transition('finished', 'finish');
-    assert.equal(reviveNode('finished', { resume: true, capacity: 'freeze' }).resumed, true);
+    assert.equal((await reviveNode('finished', { resume: true, capacity: 'freeze' })).resumed, true);
 });

package/dist/core/__tests__/seam/broker-cap-freeze.test.js

@@ -117,7 +117,7 @@ test('a birth at the cap freezes instead of booting, survives saturated ticks, a
     const filler = await h.spawnHeadlessChild(root, 'terminal thaw filler');
     assert.equal(h.fleet.size(), 2, 'the parked target is non-live while the cap remains full');
     appendInbox(second, { from: root, tier: 'normal', kind: 'message', label: 'durable wake' });
-    assert.equal(reviveNode(second, { resume: true, capacity: 'freeze' }).outcome, 'frozen');
+    assert.equal((await reviveNode(second, { resume: true, capacity: 'freeze' })).outcome, 'frozen');
     closeDb();
     const frozenTerminal = h.node(second);
     assert.equal(frozenTerminal.status, 'done', 'freezing preserves the terminal status');
@@ -144,7 +144,7 @@ test('a birth at the cap freezes instead of booting, survives saturated ticks, a
         created: new Date().toISOString(),
         pi_session_id: 'resident-drain-session',
     });
-    assert.equal(reviveNode('resident-drain', { resume: true, capacity: 'freeze' }).outcome, 'frozen');
+    assert.equal((await reviveNode('resident-drain', { resume: true, capacity: 'freeze' })).outcome, 'frozen');
     await h.tick();
     closeDb();
     const drained = h.node('resident-drain');

package/dist/core/__tests__/seam/broker-provider-retry.test.js

@@ -109,6 +109,8 @@ test('a managed-cooling terminal authors a rate-limit auto fault whose deadline
     seedPool('openai-codex', false);
     const child = await h.spawnHeadlessChild(parent, 'cooling terminal', { model: OPENAI_STRONG.spec });
     await h.waitFor(() => agentStartCount(child) >= 1, { label: 'initial cooling fixture turn started' });
+    const kickoffObserver = await attachUntil(child, 'observer', 'cooling-terminal-kickoff-settled', (a) => a.welcome.snapshot.state.isStreaming === false, 'cooling terminal kickoff settled');
+    kickoffObserver.close();
     const baselineStarts = agentStartCount(child);
     // A terminal managed-cooling error at agent_end: its explanatory prose avoids
     // rate-limit words entirely; the typed diagnostic alone must classify the

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>;