@north-light/crouter 0.3.269 → 0.3.271

package/dist/api/dto/broker.d.ts

@@ -26,6 +26,10 @@ export interface BrokerWelcomeSnapshot<M = unknown> {
     messages: M[];
     /** Stable session-entry ids aligned 1:1 with `messages`. */
     messageIds?: string[];
+    /** Presentation visibility aligned 1:1 with `messages`. */
+    messageVisibility: Array<'visible' | 'internal'>;
+    /** Presentation visibility of the run currently owned by the engine. */
+    turnVisibility: 'visible' | 'internal';
     state?: {
         isStreaming?: boolean;
     };
@@ -42,6 +46,11 @@ export interface BrokerWelcomeFrame<M = unknown> {
     type: 'welcome';
     snapshot?: BrokerWelcomeSnapshot<M>;
 }
+/** The presentation classification of the run whose native events follow. */
+export interface BrokerTurnVisibilityFrame {
+    type: 'turn_visibility';
+    visibility: 'visible' | 'internal';
+}
 /**
  * The crtrd broker `node_named` control frame — the node's generated name at the
  * instant crtrd committed it.
@@ -68,11 +77,11 @@ export interface BrokerNodeNamedFrame {
 }
 /**
  * The broker-control frames a relay consumer reads: `welcome` (catch-up snapshot),
- * `error`, and `node_named`. The broker interleaves others (display_*, ack, …)
+ * `turn_visibility`, `error`, and `node_named`. The broker interleaves others (display_*, ack, …)
  * under non-colliding `type` discriminants; a relay mapper drops those through its
  * `default` arm untyped, so they are not enumerated here.
  */
-export type BrokerControlFrame<M = unknown> = BrokerWelcomeFrame<M> | BrokerErrorFrame | BrokerNodeNamedFrame;
+export type BrokerControlFrame<M = unknown> = BrokerWelcomeFrame<M> | BrokerTurnVisibilityFrame | BrokerErrorFrame | BrokerNodeNamedFrame;
 /**
  * What the crtrd broker attach delivers to a relay consumer: the live engine
  * event stream (`E` — pi's `AgentSessionEvent`, relayed verbatim) unioned with the

package/dist/api/dto/broker.js

@@ -1,8 +1,8 @@
 // Broker attach-protocol envelope DTOs — the crtrd-specific control frames the
 // broker interleaves around pi's native agent-session event stream over a node's
 // `view.sock` (and its WS bridge, spec §5). This module owns ONLY that envelope
-// vocabulary: the two broker-control frames a relay consumer reads (`welcome` +
-// `error`), the welcome snapshot they carry, and the relay union that folds them
+// vocabulary: the broker-control frames a relay consumer reads, the welcome
+// snapshot they carry, and the relay union that folds them
 // together with the live engine event stream.
 //
 // PURITY (spec §3.1): like every file under `src/api/`, this imports NOTHING —

package/dist/api/dto/nodes.d.ts

@@ -244,6 +244,8 @@ export interface NodeSnapshotDTO {
     snapshot: {
         messages: unknown[];
         messageIds?: string[];
+        messageVisibility: Array<'visible' | 'internal'>;
+        turnVisibility: 'visible' | 'internal';
         stats: unknown;
         state: Record<string, unknown>;
         display: {
@@ -282,6 +284,8 @@ export interface NodeMessagesPageDTO {
     messages: unknown[];
     /** Stable session-entry ids aligned 1:1 with `messages`. */
     message_ids?: string[];
+    /** Presentation visibility aligned 1:1 with `messages`. */
+    message_visibility: Array<'visible' | 'internal'>;
     /** Opaque cursor toward older messages; null at the start of the session. */
     next_cursor: Cursor | null;
     captured_at: IsoTime;

package/dist/commands/pkg/plugin-inspect.js

@@ -107,10 +107,10 @@ export const pluginShow = defineLeaf({
             { name: 'manifest', type: 'object', required: true, constraint: 'Full plugin.json contents.' },
             { name: 'docs', type: 'object[]', required: true, constraint: 'Each: {name, path}. Memory docs provided by the plugin (its `<pluginName>/` memory subtree).' },
             { name: 'commands', type: 'object', required: false, constraint: 'Present only when the plugin declares a command manifest (manifest.commands). {manifestPath: string, mounts: string[] (accepted top-level command names), extensibleBranches: string[] (mount names accepting repository fragments), issues: object[] ({code, path?, message, received, expected, next})}. Validated statically; command execution never occurs.' },
-            { name: 'hooks', type: 'object', required: false, constraint: 'Present for every hook declaration, including hook-only plugins. {manifestPath?, executablePath?, declarations: {target, phase, op, description, effects}[], issues: object[] ({code, path?, message, received, expected, next}), trust: string}. Static only: no hook executable runs.' },
+            { name: 'hooks', type: 'object', required: false, constraint: 'Present for every hook declaration, including hook-only plugins. {manifestPath?, executablePath?, declarations: {target, phase, op, description, effects}[], lifecycle?: {event, phase, op, description, effects}[], issues: object[] ({code, path?, message, received, expected, next}), trust: string}. Static only: no hook executable runs.' },
         ],
         outputKind: 'object',
-        effects: ['None. Read-only. Command and hook manifests are validated statically; plugin executables are never executed.'],
+        effects: ['None. Read-only. Command and lifecycle-hook manifests are validated statically; plugin executables are never executed.'],
     },
     run: async (input) => {
         const name = input['name'];

package/dist/commands/pkg/plugin-manage.js

@@ -729,7 +729,7 @@ export const pluginInstall = defineLeaf({
             { name: 'kinds', type: 'integer', required: false, constraint: 'Kind-registry entry count declared by an --endpoint archive\u2019s bundle.json.' },
             { name: 'pageComponents', type: 'integer', required: false, constraint: 'Page-component registration count declared by an --endpoint archive\u2019s bundle.json.' },
             { name: 'commands', type: 'object', required: false, constraint: 'Present only when the plugin declares a command manifest. {mounts: string[] (accepted top-level command names now live for the next invocation), issues: object[] (typed validation issues that rejected a contribution — {code, path?, message, received, expected, next})}. Validated statically; commands are never executed.' },
-            { name: 'hooks', type: 'object', required: false, constraint: 'Present only when the source plugin declares hooks. {manifestPath?, executablePath?, declarations: {target, phase, op, description, effects}[], issues: object[], trust: string}. Declarations, eligible targets, and replacement collisions are validated statically; hook executables are never run.' },
+            { name: 'hooks', type: 'object', required: false, constraint: 'Present only when the source plugin declares hooks. {manifestPath?, executablePath?, declarations: {target, phase, op, description, effects}[], lifecycle?: {event, phase, op, description, effects}[], issues: object[], trust: string}. Command targets, lifecycle events, and replacement collisions are validated statically; hook executables are never run.' },
             { name: 'warnings', type: 'string[]', required: false, constraint: 'Advisory missing PATH executable requirements declared by the installed plugin. The install still succeeds and leaves the plugin enabled.' },
             { name: 'memory', type: 'object', required: false, constraint: 'Present only when the plugin ships a memory store. {docs: integer (documents checked), migrated: string[] (store-relative documents rewritten to reach exact canonical identity), linkedSource?: string (the caller-owned directory converged in place, present only when the install keeps that directory as a live link)}.' },
         ],
@@ -738,7 +738,7 @@ export const pluginInstall = defineLeaf({
             'A ref install clones, links, or copies the plugin into the scope plugins directory and registers it with enabled=true. Marketplace installs refresh the source marketplace before resolving the plugin entry.',
             'An --endpoint install fetches and validates one authenticated uncompressed tar archive before writing. It replaces the complete plugin directory with synthesized provenance and invocation metadata, commands.json, memory docs, any kind-registry entries the bundle.json declares (they join the launch registry below this scope\u2019s own config.json kinds), and any page components it declares (they join the active page-component catalog alongside the user config entries); a fetch or validation failure preserves the prior package.',
             'If the plugin declares a command manifest, its commands go live on the next crtr invocation. Exec commands run trusted local code only when explicitly invoked; HTTP commands call their declared endpoint only when explicitly invoked.',
-            'Source plugin hooks go live on the next crtr invocation. They run implicitly with caller authority, may receive normalized inputs and after results, may block or replace declared targets, and may transmit received data. Hook executables are never run during install or update validation.',
+            'Source plugin command hooks go live on the next crtr invocation. They run implicitly with caller authority, may receive normalized inputs and after results, may block or replace declared targets, and may transmit received data. Lifecycle hooks run unprompted at every declared event before node launch and may transmit node identity and resolved paths. Hook executables are never run during install or update validation.',
             'A plugin manifest `requires` declaration is checked against the PATH a node bash receives after install. Missing executables emit a warning with the declared install hint but never fail the install, disable the plugin, or remove its bare-binary contributions.',
             'Before activation the candidate\u2019s memory corpus is migrated to exact canonical identity and refused if it cannot mount. A staged candidate is migrated in staging and rolls back with the package; a local path or marketplace-relative source stays a live link, so its own directory is rewritten in place, keeps that rewrite whether or not the install completes, and is named as `memory.linkedSource`. A refused corpus writes nothing and installs nothing.',
         ],
@@ -904,7 +904,7 @@ export const pluginUpdate = defineLeaf({
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Narrows resolution.' },
         ],
         output: [
-            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, transport?, updated, sha?, version?, docs?, kinds?, pageComponents?, commands?, hooks?, memory?, warnings?, error?}. memory is present for a plugin shipping a memory store and reports the same corpus migration install performs: {docs, migrated, linkedSource?}. Archive plugins report transport=http and replace their complete directory after an authenticated refetch; version is the archive content identifier, docs is the written memory-document count, kinds is the declared kind-registry entry count, and pageComponents is the declared page-component registration count. sha is present for git updates. A bulk update reports and skips a failed archive plugin. commands is present for validated command plugins: {mounts: string[], issues: object[]}. hooks is present for source hook plugins: {manifestPath?, executablePath?, declarations: {target, phase, op, description, effects}[], issues: object[], trust: string}; it is static and never executes hooks. warnings lists advisory PATH requirements that remain absent after update.' },
+            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, transport?, updated, sha?, version?, docs?, kinds?, pageComponents?, commands?, hooks?, memory?, warnings?, error?}. memory is present for a plugin shipping a memory store and reports the same corpus migration install performs: {docs, migrated, linkedSource?}. Archive plugins report transport=http and replace their complete directory after an authenticated refetch; version is the archive content identifier, docs is the written memory-document count, kinds is the declared kind-registry entry count, and pageComponents is the declared page-component registration count. sha is present for git updates. A bulk update reports and skips a failed archive plugin. commands is present for validated command plugins: {mounts: string[], issues: object[]}. hooks is present for source hook plugins: {manifestPath?, executablePath?, declarations: {target, phase, op, description, effects}[], lifecycle?: {event, phase, op, description, effects}[], issues: object[], trust: string}; it is static and never executes hooks. warnings lists advisory PATH requirements that remain absent after update.' }
         ],
         outputKind: 'object',
         effects: [

package/dist/commands/sys/doctor.js

@@ -178,8 +178,9 @@ async function runHookPluginChecks(scopes) {
             continue;
         const issues = registry.issues.filter((issue) => issue.plugin === plugin.name && issue.scope === plugin.scope);
         if (issues.length === 0) {
-            const declarations = validation.hooks.map((hook) => `${hook.target} [${hook.phase} ${hook.op}]`).join('; ');
-            results.push(pass(plugin.scope, `plugin:${plugin.name}:hooks`, `effective hook declaration(s): ${declarations}`));
+            const commandDeclarations = validation.hooks.map((hook) => `${hook.target} [${hook.phase} ${hook.op}]`);
+            const lifecycleDeclarations = (validation.manifest?.schemaVersion === 2 ? validation.manifest.lifecycle : []).map((hook) => `${hook.event} [${hook.phase} ${hook.op}; effects: ${hook.effects.join(', ')}]`);
+            results.push(pass(plugin.scope, `plugin:${plugin.name}:hooks`, `effective hook declaration(s): ${[...commandDeclarations, ...lifecycleDeclarations].join('; ')}`));
             continue;
         }
         issues.forEach((issue, index) => {
@@ -578,7 +579,7 @@ export const sysDoctorLeaf = defineLeaf({
             { kind: 'flag', name: 'remote', type: 'bool', required: false, constraint: 'Check git remotes with ls-remote (slow — makes network calls).' },
         ],
         output: [
-            { name: 'checks', type: 'object[]', required: true, constraint: 'Each: {scope, name, status, message, fixed?, remediation?}. status: pass | fail. scope may be user | project | canvas. bin:<name> checks report bare-binary contributions (a `bin` block in a plugin manifest or a scope config.json): a pass names the contributor and the resolved target, a fail names an unsafe/reserved command name, malformed target declaration, missing/non-executable/escaping target, or same-precedence name collision that installed nothing; their remediation is always a human_action. humanActions:<name>@<config-origin> checks validate each user/project scope completion-action declaration: action-name and argv shape, cwd directory, argv[0] regular-file existence, and execute permission; they never execute an action. A malformed effective declaration fails; a malformed shadowed declaration is a pass-level warning that names the winning and shadowed origins. requires:<name> checks report each enabled plugin manifest PATH requirement: a pass names the plugin and resolved executable path; a fail names the plugin and carries its declared install hint as remediation. Runtime checks validate selected and process generation manifests, sealing/containment, and full SHA-256 inventories. terminal:nerd-font (user scope) reports whether a Nerd Font is installed for the viewer\'s icon glyphs; its remediation is always a human_action carrying the platform install command, never auto-fixed. Plugin checks appear as plugin:<name>:commands and plugin:<name>:hooks; both are validated statically and never execute plugin code. Hook failures identify manifest/path/target/collision problems and carry disable/update/remove/show remediation; healthy hooks list effective target, phase, and op. remediation (when present) is {kind, description, ...payload} where kind is remove_config_key | rm_path | human_action; fault human_action remediations include the canonical logs command. Sorted by scope then name.' },
+            { name: 'checks', type: 'object[]', required: true, constraint: 'Each: {scope, name, status, message, fixed?, remediation?}. status: pass | fail. scope may be user | project | canvas. bin:<name> checks report bare-binary contributions (a `bin` block in a plugin manifest or a scope config.json): a pass names the contributor and the resolved target, a fail names an unsafe/reserved command name, malformed target declaration, missing/non-executable/escaping target, or same-precedence name collision that installed nothing; their remediation is always a human_action. humanActions:<name>@<config-origin> checks validate each user/project scope completion-action declaration: action-name and argv shape, cwd directory, argv[0] regular-file existence, and execute permission; they never execute an action. A malformed effective declaration fails; a malformed shadowed declaration is a pass-level warning that names the winning and shadowed origins. requires:<name> checks report each enabled plugin manifest PATH requirement: a pass names the plugin and resolved executable path; a fail names the plugin and carries its declared install hint as remediation. Runtime checks validate selected and process generation manifests, sealing/containment, and full SHA-256 inventories. terminal:nerd-font (user scope) reports whether a Nerd Font is installed for the viewer\'s icon glyphs; its remediation is always a human_action carrying the platform install command, never auto-fixed. Plugin checks appear as plugin:<name>:commands and plugin:<name>:hooks; both are validated statically and never execute plugin code. Hook failures identify manifest/path/target/event/collision problems and carry disable/update/remove/show remediation; healthy command hooks list effective target, phase, and op, while lifecycle hooks list event, phase, op, and effects. remediation (when present) is {kind, description, ...payload} where kind is remove_config_key | rm_path | human_action; fault human_action remediations include the canonical logs command. Sorted by scope then name.' },
             { name: 'ok', type: 'boolean', required: true, constraint: 'True when no unresolved fail checks remain.' },
         ],
         outputKind: 'object',

package/dist/core/__tests__/canvas-inbox-watcher-hold.test.js

@@ -28,7 +28,7 @@ import { ApiError } from '../../api/errors.js';
 // debounce window before asserting, exactly as against the real 800/1000 cadence.
 const TICK_MS = 20;
 const DEBOUNCE_MS = 25;
-const SETTLE_MS = TICK_MS * 2 + DEBOUNCE_MS + 30;
+const SETTLE_MS = TICK_MS * 2 + DEBOUNCE_MS + 200;
 let origHome;
 let origNode;
 const homes = [];
@@ -302,7 +302,7 @@ describe('canvas inbox watcher — hold + idle delivery', () => {
             },
         };
         const drive = createEngineDriver({
-            registry: { sendFrame: () => undefined },
+            registry: { sendFrame: () => undefined, broadcast: () => undefined },
             replies: {},
             session: () => session,
             dispatches: { track: (promise) => promise },

package/dist/core/__tests__/helpers/harness.js

@@ -282,6 +282,7 @@ export async function createHarness(opts = {}) {
             ...cleanBaseEnv(),
             CRTR_HOME: home,
             HOME: tmpHome,
+            CRTR_RUNTIME_HOME: realRuntimeHome,
             CRTR_PI_BINARY: FAKE_PI_BINARY,
             CRTR_BROKER_ENGINE: FAKE_ENGINE,
         },

package/dist/core/__tests__/human-deliver.test.js

@@ -192,7 +192,7 @@ describe('terminal ticket delivery', () => {
         await deliverTerminalResult(bridge);
         assert.equal(getNode(companion)?.final_report, finalReport, 'terminal replay preserves the first canonical final');
         assert.equal(getNode(companion)?.finalized_at, finalizedAt, 'terminal replay preserves the first finalization time');
-        assert.throws(() => reviveNode(companion, { resume: true, capacity: 'freeze' }), /finalization latch/);
+        await assert.rejects(reviveNode(companion, { resume: true, capacity: 'freeze' }), /finalization latch/);
         const { bridge: dismissedBridge } = bridgeUnder();
         const dismissedDir = submitBridgePage(dismissedBridge);
         const dismissedCompanion = spawnNode({ kind: 'general', parent: dismissedBridge, creator: dismissedBridge, cwd: home, name: 'dismissed feedback companion', lifecycle: 'resident' }).node_id;

package/dist/core/__tests__/integration/lifecycle-hooks.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/integration/lifecycle-hooks.test.js

@@ -0,0 +1,182 @@
+import assert from 'node:assert/strict';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import test from 'node:test';
+import { contextDir, jobDir, nodeDir, reportsDir } from '../../canvas/paths.js';
+import { validateHookManifest } from '../../command-hooks/schema.js';
+import { headlessBrokerHost } from '../../runtime/host.js';
+import { reviveNode } from '../../runtime/revive.js';
+import { createHarness } from '../helpers/harness.js';
+function installLifecyclePlugin(harness, name, op) {
+    const ops = typeof op === 'string' ? [op] : op;
+    const root = join(harness.agentHome, '.crouter', 'plugins', name);
+    mkdirSync(join(root, '.crouter-plugin'), { recursive: true });
+    writeFileSync(join(root, '.crouter-plugin', 'plugin.json'), JSON.stringify({
+        name,
+        version: '0.1.0',
+        description: 'lifecycle hook fixture',
+        hooks: 'hooks.json',
+        hookExecutable: 'bin/hook.js',
+    }));
+    writeFileSync(join(root, 'hooks.json'), JSON.stringify({
+        schemaVersion: 2,
+        lifecycle: ops.map((entry) => ({ event: 'node:start', phase: 'on', op: entry, description: `${entry} fixture`, effects: ['writes fixture state'] })),
+    }));
+    const executable = join(root, 'bin', 'hook.js');
+    mkdirSync(join(root, 'bin'), { recursive: true });
+    writeFileSync(executable, `#!/usr/bin/env node
+const { existsSync, writeFileSync } = require('node:fs');
+const { join } = require('node:path');
+let input = '';
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  const request = JSON.parse(input);
+  writeFileSync(join(request.node.contextDir, 'lifecycle-order'), request.op + '\\n', { flag: 'a' });
+  if (request.op === 'record') writeFileSync(join(request.node.contextDir, 'lifecycle-request.json'), JSON.stringify(request));
+  if (request.op === 'hang') {
+    writeFileSync(join(request.node.contextDir, 'lifecycle-hang-started'), 'started');
+    setInterval(() => {}, 1000);
+    return;
+  }
+  if (request.op === 'bad') {
+    process.stdout.write('not a JSON envelope');
+    return;
+  }
+  if (request.op === 'nonzero') {
+    writeFileSync(join(request.node.contextDir, 'lifecycle-nonzero-started'), 'started');
+    process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: true }));
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: true }));
+});
+`);
+    chmodSync(executable, 0o755);
+}
+function installV1CommandHook(harness) {
+    const root = join(harness.agentHome, '.crouter', 'plugins', 'z-v1-command');
+    mkdirSync(join(root, '.crouter-plugin'), { recursive: true });
+    writeFileSync(join(root, '.crouter-plugin', 'plugin.json'), JSON.stringify({
+        name: 'z-v1-command', version: '0.1.0', description: 'v1 command hook fixture', hooks: 'hooks.json', hookExecutable: 'bin/hook.js',
+    }));
+    writeFileSync(join(root, 'hooks.json'), JSON.stringify({
+        schemaVersion: 1,
+        hooks: [{ target: 'sys version', phase: 'before', op: 'v1_check', description: 'v1 command hook', effects: ['writes fixture state'] }],
+    }));
+    const executable = join(root, 'bin', 'hook.js');
+    mkdirSync(join(root, 'bin'), { recursive: true });
+    writeFileSync(executable, `#!/usr/bin/env node
+const { writeFileSync } = require('node:fs');
+const { join } = require('node:path');
+let input = '';
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  JSON.parse(input);
+  writeFileSync(join(__dirname, '..', 'v1-ran'), 'ran');
+  process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: true }));
+});
+`);
+    chmodSync(executable, 0o755);
+    return join(root, 'v1-ran');
+}
+test('node:start hooks receive resolved paths before broker launch; invalid and hanging hooks do not block launch', async () => {
+    const harness = await createHarness({ headless: true, sessionPrefix: 'crtr-lifecycle-hooks' });
+    const originalLaunch = headlessBrokerHost.launch;
+    try {
+        installLifecyclePlugin(harness, 'aa-lifecycle-order', ['first', 'second']);
+        installLifecyclePlugin(harness, 'a-lifecycle-record', 'record');
+        installLifecyclePlugin(harness, 'b-lifecycle-bad', 'bad');
+        installLifecyclePlugin(harness, 'c-lifecycle-nonzero', 'nonzero');
+        installLifecyclePlugin(harness, 'd-lifecycle-hang', 'hang');
+        const v1Marker = installV1CommandHook(harness);
+        const show = harness.cli(null, ['--json', 'pkg', 'plugin', 'show', 'a-lifecycle-record', '--scope', 'user']);
+        assert.equal(show.code, 0, show.stderr);
+        assert.deepEqual(show.json.hooks.lifecycle, [{
+                event: 'node:start', phase: 'on', op: 'record', description: 'record fixture', effects: ['writes fixture state'],
+            }]);
+        const doctor = harness.cli(null, ['--json', 'sys', 'doctor', '--scope', 'user']);
+        assert.equal(doctor.code, 0, doctor.stderr);
+        const hookCheck = doctor.json.checks.find((check) => check.name === 'plugin:a-lifecycle-record:hooks');
+        assert.match(hookCheck?.message ?? '', /node:start \[on record; effects: writes fixture state\]/);
+        const nodeId = harness.fabricateBrokerNode({ id: 'lifecycle-hook-node', pi_pid: null, pi_session_id: null, pi_session_file: null });
+        const requestPath = join(contextDir(nodeId), 'lifecycle-request.json');
+        let requestExistedBeforeLaunch = false;
+        headlessBrokerHost.launch = ((id, ...args) => {
+            if (id === nodeId)
+                requestExistedBeforeLaunch = existsSync(requestPath);
+            return originalLaunch.call(headlessBrokerHost, id, ...args);
+        });
+        const startedAt = Date.now();
+        const starting = reviveNode(nodeId, { resume: false, capacity: 'freeze' });
+        const contender = await reviveNode(nodeId, { resume: false, capacity: 'freeze' });
+        const result = await starting;
+        const elapsedMs = Date.now() - startedAt;
+        await harness.awaitBoot(nodeId);
+        assert.equal(result.outcome, 'launched');
+        assert.equal(contender.outcome, 'already-live', 'a concurrent revive cannot cross the awaited hook gap');
+        assert.equal(requestExistedBeforeLaunch, true, 'the lifecycle hook finishes before broker launch');
+        assert.equal(existsSync(join(contextDir(nodeId), 'lifecycle-nonzero-started')), true, 'a non-zero executable ran without blocking launch');
+        assert.equal(existsSync(join(contextDir(nodeId), 'lifecycle-hang-started')), true, 'the hanging executable started and was subject to the lifecycle timeout');
+        assert.ok(elapsedMs >= 4_500 && elapsedMs < 8_000, `the 5s hanging hook was bounded before launch (${elapsedMs}ms)`);
+        assert.deepEqual(readFileSync(join(contextDir(nodeId), 'lifecycle-order'), 'utf8').trim().split('\n'), ['record', 'first', 'second', 'bad', 'nonzero', 'hang'], 'lifecycle hooks preserve plugin-name then declaration-index discovery order');
+        assert.equal(existsSync(v1Marker), false, 'a command-only v1 manifest adds no node-start subprocess');
+        const request = JSON.parse(readFileSync(requestPath, 'utf8'));
+        assert.equal(request.protocolVersion, 1);
+        assert.equal(request.op, 'record');
+        assert.equal(request.event, 'node:start');
+        assert.equal(request.phase, 'on');
+        assert.match(request.operationId, /^[0-9a-f]{32}$/);
+        assert.deepEqual(request.context, { cwd: harness.node(nodeId).cwd });
+        assert.deepEqual(request.node, {
+            id: nodeId,
+            name: nodeId,
+            kind: 'developer',
+            mode: 'base',
+            lifecycle: 'terminal',
+            cwd: harness.node(nodeId).cwd,
+            nodeDir: nodeDir(nodeId),
+            contextDir: contextDir(nodeId),
+            jobDir: jobDir(nodeId),
+            reportsDir: reportsDir(nodeId),
+        });
+        assert.deepEqual(request.runtime, { isBirth: true, canvasHome: harness.home, profile: null });
+        const v1Command = harness.cli(null, ['--json', 'sys', 'version']);
+        assert.equal(v1Command.code, 0, v1Command.stderr);
+        assert.equal(existsSync(v1Marker), true, 'a v1 command hook still executes around its declared command');
+    }
+    finally {
+        headlessBrokerHost.launch = originalLaunch;
+        await harness.dispose();
+    }
+});
+test('hooks.json v1 remains command-only while v2 accepts a lifecycle-only declaration', () => {
+    const v1 = validateHookManifest({
+        schemaVersion: 1,
+        hooks: [{ target: 'canvas list', phase: 'before', op: 'check', description: 'check', effects: ['writes a log'] }],
+    });
+    assert.deepEqual(v1, {
+        manifest: {
+            schemaVersion: 1,
+            hooks: [{ target: 'canvas list', phase: 'before', op: 'check', description: 'check', effects: ['writes a log'] }],
+        },
+        issues: [],
+    });
+    const v2 = validateHookManifest({
+        schemaVersion: 2,
+        lifecycle: [{ event: 'node:start', phase: 'on', op: 'prepare', description: 'prepare', effects: ['creates a directory'] }],
+    });
+    assert.deepEqual(v2.issues, []);
+    assert.deepEqual(v2.manifest, {
+        schemaVersion: 2,
+        hooks: [],
+        lifecycle: [{ event: 'node:start', phase: 'on', op: 'prepare', description: 'prepare', effects: ['creates a directory'] }],
+    });
+    for (const manifest of [
+        { schemaVersion: 2, hooks: [], lifecycle: [] },
+        { schemaVersion: 2, lifecycle: [{ event: 'node:stop', phase: 'on', op: 'prepare', description: 'prepare', effects: ['creates a directory'] }] },
+        { schemaVersion: 2, lifecycle: [{ event: 'node:start', phase: 'before', op: 'prepare', description: 'prepare', effects: ['creates a directory'] }] },
+        { schemaVersion: 2, lifecycle: [{ event: 'node:start', phase: 'on', op: 'prepare', description: 'prepare', effects: ['creates a directory'], unexpected: true }] },
+    ]) {
+        assert.equal(validateHookManifest(manifest).manifest, undefined, 'invalid v2 lifecycle declarations are rejected');
+    }
+});

package/dist/core/__tests__/integration/revive.test.js

@@ -231,7 +231,7 @@ test('reviveNode no-ops when the node has a live fleet entry — double-revive g
         });
         h.fleet.register(M, { pid: 424242, exited: new Promise(() => { }) });
         const before = h.node(M).cycles ?? 0;
-        const res = reviveNode(M, { resume: true, capacity: 'freeze' });
+        const res = await reviveNode(M, { resume: true, capacity: 'freeze' });
         assert.equal(res.resumed, false, 'guard path does not re-resume');
         assert.equal(h.node(M).cycles ?? 0, before, 'cycle counter NOT bumped (guard returned early)');
     }
@@ -259,7 +259,7 @@ test('reviveNode PROCEEDS when the node has NO fleet entry — cycle counter bum
             pi_session_file: sessionFile,
         });
         assert.equal(h.node(M).cycles ?? 0, 0, 'fabricated at cycle 0 (no revive yet)');
-        reviveNode(M, { resume: true, capacity: 'freeze' });
+        await reviveNode(M, { resume: true, capacity: 'freeze' });
         const after = h.node(M);
         assert.equal(after.cycles, 1, 'a real (non-guard) revive bumped the cycle counter to 1');
         assert.notEqual(after.pi_pid, stalePid, 'revive records the fresh broker pid immediately, not the stale dead pid');
@@ -303,11 +303,11 @@ test('a recovery relaunch keeps the armed deadline; a wake revive consumes it',
     try {
         const recovered = h.fabricateBrokerNode({ status: 'active', intent: null, pi_pid: deadPid(), pi_session_id: 'uuid-1' });
         armDeadline(recovered, 'cron-recovery');
-        reviveNode(recovered, { resume: true, recovery: true, capacity: 'freeze' });
+        await reviveNode(recovered, { resume: true, recovery: true, capacity: 'freeze' });
         assert.equal(hasPendingCancelOnWakeCron(recovered), true, 'the daemon replacing a dead broker is not a wake — the deadline survives so the wait can still settle');
         const woken = h.fabricateBrokerNode({ status: 'active', intent: null, pi_pid: deadPid(), pi_session_id: 'uuid-2' });
         armDeadline(woken, 'cron-wake');
-        reviveNode(woken, { resume: true, capacity: 'freeze' });
+        await reviveNode(woken, { resume: true, capacity: 'freeze' });
         assert.equal(hasPendingCancelOnWakeCron(woken), false, 'a wake revive won the race and cancels the deadline');
     }
     finally {
@@ -358,7 +358,7 @@ test('reviveNode fresh-fallback clears the stale session identity (Major-3: no p
             pi_session_id: 'uuid-stale',
             pi_session_file: missingFile,
         });
-        const res = reviveNode(M, { resume: true, capacity: 'freeze' });
+        const res = await reviveNode(M, { resume: true, capacity: 'freeze' });
         assert.equal(res.resumed, false, 'a missing .jsonl forces a fresh (non-resuming) launch');
         const after = h.node(M);
         assert.equal(after.pi_session_id, null, 'stale pi_session_id cleared before the fresh launch');
@@ -370,7 +370,7 @@ test('reviveNode fresh-fallback clears the stale session identity (Major-3: no p
         await h.dispose();
     }
 });
-test('unbound forks replay one durable source file for node-id, path, and UUID operands', () => {
+test('unbound forks replay one durable source file for node-id, path, and UUID operands', async () => {
     const originalLaunch = headlessBrokerHost.launch;
     const tf = bindTestFleet();
     const forkFile = join(home, 'ordinary-fork-source.jsonl');
@@ -404,7 +404,7 @@ test('unbound forks replay one durable source file for node-id, path, and UUID o
         deleteNode('ordinary-fork-source');
         for (let index = 0; index < operands.length; index++) {
             const destination = `ordinary-fork-${index}`;
-            reviveNode(destination, { resume: index !== 1, capacity: 'freeze' });
+            await reviveNode(destination, { resume: index !== 1, capacity: 'freeze' });
             const argv = launches[index];
             const fork = argv.indexOf('--fork');
             assert.equal(argv[fork + 1], forkFile, `${operands[index]} retries from the durable resolved file`);
@@ -437,7 +437,7 @@ test('reviveNode throws a typed cwd_missing error and does NOT crash the node wh
             pi_pid: deadPid(),
         });
         updateNode(M, { cwd: missingCwd });
-        assert.throws(() => reviveNode(M, { resume: true, capacity: 'freeze' }), (e) => e instanceof InputError && e.payload.error === 'cwd_missing' && e.message.includes(missingCwd), 'reviveNode must throw a typed InputError naming the missing cwd path');
+        await assert.rejects(reviveNode(M, { resume: true, capacity: 'freeze' }), (e) => e instanceof InputError && e.payload.error === 'cwd_missing' && e.message.includes(missingCwd), 'reviveNode must throw a typed InputError naming the missing cwd path');
         const after = h.node(M);
         assert.equal(after.status, 'active', 'a cwd-missing preflight refusal must NOT crash the node (fixable in place, not a dead engine)');
     }
@@ -455,7 +455,7 @@ test('reviveNode relaunches fresh when the session header cwd was removed (NL-14
         const M = h.fabricateBrokerNode({
             status: 'active', intent: null, pi_pid: deadPid(), pi_session_id: 'stale-session', pi_session_file: sessionFile,
         });
-        const result = reviveNode(M, { resume: true, capacity: 'freeze', recovery: true });
+        const result = await reviveNode(M, { resume: true, capacity: 'freeze', recovery: true });
         assert.equal(result.resumed, false, 'the missing session cwd vetoes --session and launches fresh');
         assert.equal(h.node(M)?.pi_session_id, null, 'the stale session id is cleared before the fresh launch');
         assert.equal(h.node(M)?.pi_session_file, null, 'the stale session file is cleared before the fresh launch');
@@ -479,7 +479,7 @@ test('reviveNode crashes and clears pid when launch/preflight throws', async ()
             pi_session_file: sessionFile,
         });
         headlessBrokerHost.launch = (_nodeId, _inv, _opts) => { throw new Error('boom'); };
-        assert.throws(() => reviveNode(M, { resume: true, capacity: 'freeze' }), /refusing to revive/i);
+        await assert.rejects(reviveNode(M, { resume: true, capacity: 'freeze' }), /refusing to revive/i);
         const after = h.node(M);
         assert.equal(after.status, 'dead', 'failed revive marks the node dead');
         assert.equal(after.pi_pid, null, 'failed revive clears the stale pid');
@@ -512,7 +512,7 @@ test('reviveNode fans a doctrine wake to subscribers when launch/preflight throw
         // was fabricated directly, not spawned through the CLI.
         subscribe(root, M, true);
         headlessBrokerHost.launch = (_nodeId, _inv, _opts) => { throw new Error('boom'); };
-        assert.throws(() => reviveNode(M, { resume: true, capacity: 'freeze' }), /refusing to revive/i);
+        await assert.rejects(reviveNode(M, { resume: true, capacity: 'freeze' }), /refusing to revive/i);
         assert.equal(h.node(M).status, 'dead', 'failed revive marks the node dead');
         const entries = readInboxSince(root, undefined);
         const notice = entries.find((e) => e.data?.['reason'] === 'child-crashed' && e.data?.['child'] === M);
@@ -532,7 +532,7 @@ test('reviveNode fans a doctrine wake to subscribers when launch/preflight throw
 // nothing. It woke, flailed over an empty context dir and reported itself
 // confused. Such a relaunch is a BIRTH: replay the spawn mandate if there is
 // one, else boot promptless and take no turn at all.
-test('an unstarted node relaunches as a birth, not a "revived fresh" kickoff', () => {
+test('an unstarted node relaunches as a birth, not a "revived fresh" kickoff', async () => {
     const originalLaunch = headlessBrokerHost.launch;
     const tf = bindTestFleet();
     const launches = [];
@@ -547,19 +547,19 @@ test('an unstarted node relaunches as a birth, not a "revived fresh" kickoff', (
         const missing = join(home, 'sessions', 'never-written.jsonl');
         // (1) Bare interactive node — nothing on disk anywhere: launch promptless.
         createNode(node('bare-unstarted', { cwd: home, pi_session_id: 'uuid-a', pi_session_file: missing }));
-        reviveNode('bare-unstarted', { resume: true, capacity: 'freeze' });
+        await reviveNode('bare-unstarted', { resume: true, capacity: 'freeze' });
         const bare = launches[0];
         assert.equal(bare.some((a) => isReviveKickoff(a)), false, 'an unstarted node is never told it lost context it never had');
         assert.deepEqual(bare, buildPiArgv(getNode('bare-unstarted'), {}).argv, 'a promptless boot — the argv carries no trailing prompt positional at all');
         // (2) Spawned with a mandate whose first turn never persisted: replay it.
         createNode(node('mandate-unstarted', { cwd: home, pi_session_id: 'uuid-b', pi_session_file: missing }));
         writeGoal('mandate-unstarted', 'do the thing');
-        reviveNode('mandate-unstarted', { resume: true, capacity: 'freeze' });
+        await reviveNode('mandate-unstarted', { resume: true, capacity: 'freeze' });
         assert.equal(launches[1].at(-1), 'do the thing', 'a birth replays the spawn mandate');
         // (3) Real durable progress on disk → still a genuine fresh revive.
         createNode(node('progressed', { cwd: home, pi_session_id: 'uuid-c', pi_session_file: missing }));
         seedRoadmap('progressed', { goal: 'ship it' });
-        reviveNode('progressed', { resume: true, capacity: 'freeze' });
+        await reviveNode('progressed', { resume: true, capacity: 'freeze' });
         assert.equal(isReviveKickoff(launches[2].at(-1)), true, 'a node with a roadmap still rebuilds from the kickoff');
     }
     finally {

package/dist/core/__tests__/push-final-guard.test.js

@@ -179,6 +179,6 @@ test('reviveNode refuses to revive a node that became finalized after the caller
     process.env['CRTR_NODE_ID'] = id;
     await pushFinal(id, 'concurrent final');
     assert.equal(getNode(id)?.status, 'done');
-    assert.throws(() => reviveNode(id, { resume: true, capacity: 'freeze' }), /finaliz/i, 'reviveNode\'s own belt-and-suspenders check refuses a now-latched target');
+    await assert.rejects(reviveNode(id, { resume: true, capacity: 'freeze' }), /finaliz/i, 'reviveNode\'s own belt-and-suspenders check refuses a now-latched target');
     assert.equal(getNode(id)?.status, 'done', 'the node stays done, never silently revived into an unsatisfiable mandate');
 });

package/dist/core/__tests__/revive-capacity.test.js

@@ -52,9 +52,9 @@ function node(id, over = {}) {
     return id;
 }
 /** Fill the ledger to the cap with live brokers. */
-function saturate() {
-    reviveNode(node(`filler-a-${seq}`), { resume: false, capacity: 'refuse' });
-    reviveNode(node(`filler-b-${seq}`), { resume: false, capacity: 'refuse' });
+async function saturate() {
+    await reviveNode(node(`filler-a-${seq}`), { resume: false, capacity: 'refuse' });
+    await reviveNode(node(`filler-b-${seq}`), { resume: false, capacity: 'refuse' });
     assert.equal(tf.fleet.size(), 2, 'precondition: the ledger is at its cap of 2');
 }
 before(() => {
@@ -78,10 +78,10 @@ after(() => {
     delete process.env['CRTR_HOME'];
     rmSync(home, { recursive: true, force: true });
 });
-test('a refusing caller gets an error naming the cap and the live count, never a silent no-op', () => {
-    saturate();
+test('a refusing caller gets an error naming the cap and the live count, never a silent no-op', async () => {
+    await saturate();
     const turned = node('refused', { pi_session_id: 'sess-refused' });
-    assert.throws(() => reviveNode(turned, { resume: true, capacity: 'refuse' }), (err) => {
+    await assert.rejects(() => reviveNode(turned, { resume: true, capacity: 'refuse' }), (err) => {
         const details = err.details ?? {};
         assert.equal(details['error'], 'broker_cap_reached', 'the refusal is a typed InputError, so it survives the /v1 error body');
         assert.match(String(details['message']), /2 live brokers at the cap of 2/, 'the message names both the live count and the cap');
@@ -110,21 +110,21 @@ test('a pre-spawn launch failure releases the reservation', () => {
         stubLaunch();
     }
 });
-test('a freezing caller gets a frozen row, marked once and left otherwise untouched', () => {
-    saturate();
+test('a freezing caller gets a frozen row, marked once and left otherwise untouched', async () => {
+    await saturate();
     const waiting = node('frozen', { pi_session_id: 'sess-frozen' });
-    const first = reviveNode(waiting, { resume: true, capacity: 'freeze' });
+    const first = await reviveNode(waiting, { resume: true, capacity: 'freeze' });
     assert.equal(first.outcome, 'frozen', 'the caller learns it got no engine');
     const marked = getNode(waiting);
     assert.ok(marked.frozen_at != null, 'the row carries the durable wait mark the thaw order reads');
     assert.equal(marked.pi_pid ?? null, null, 'a frozen row holds no pid — every status surface reads it as frozen, not stale-active');
     assert.equal(marked.cycles ?? 0, 0, 'a frozen node never spent a cycle');
-    const second = reviveNode(waiting, { resume: true, capacity: 'freeze' });
+    const second = await reviveNode(waiting, { resume: true, capacity: 'freeze' });
     assert.equal(second.outcome, 'frozen');
     assert.equal(getNode(waiting).frozen_at, marked.frozen_at, 'freezing is once-per-episode: a second saturated tick keeps the original wait timestamp');
 });
 test('a durable daemon message reports capacity_frozen when its wake cannot launch', async () => {
-    saturate();
+    await saturate();
     const waiting = node('message-frozen');
     const delivery = await deliverNodeMessage({
         node_id: waiting,
@@ -137,26 +137,26 @@ test('a durable daemon message reports capacity_frozen when its wake cannot laun
     assert.equal(delivery.revived, false);
     assert.equal(delivery.reason, 'capacity_frozen');
 });
-test('an already-live node is admitted at the cap — it consumes no new slot', () => {
+test('an already-live node is admitted at the cap — it consumes no new slot', async () => {
     const live = node('already-live');
-    reviveNode(live, { resume: false, capacity: 'refuse' });
-    reviveNode(node('already-live-filler'), { resume: false, capacity: 'refuse' });
+    await reviveNode(live, { resume: false, capacity: 'refuse' });
+    await reviveNode(node('already-live-filler'), { resume: false, capacity: 'refuse' });
     assert.equal(tf.fleet.size(), 2, 'precondition: this node holds one of the two slots, and the ledger is full');
     // Both dispositions agree: liveness is answered before capacity ever is.
-    assert.equal(reviveNode(live, { resume: true, capacity: 'refuse' }).outcome, 'already-live');
-    assert.equal(reviveNode(live, { resume: true, capacity: 'freeze' }).outcome, 'already-live');
+    assert.equal((await reviveNode(live, { resume: true, capacity: 'refuse' })).outcome, 'already-live');
+    assert.equal((await reviveNode(live, { resume: true, capacity: 'freeze' })).outcome, 'already-live');
     assert.equal(getNode(live).frozen_at ?? null, null, 'a live node is never marked as waiting for a slot');
 });
 test('a freed slot lets the frozen row launch, and the launch retires the mark', async () => {
     const filler = node('filler-exits');
-    reviveNode(filler, { resume: false, capacity: 'refuse' });
-    reviveNode(node('filler-stays'), { resume: false, capacity: 'refuse' });
+    await reviveNode(filler, { resume: false, capacity: 'refuse' });
+    await reviveNode(node('filler-stays'), { resume: false, capacity: 'refuse' });
     const waiting = node('thaws', { pi_session_id: 'sess-thaws' });
-    assert.equal(reviveNode(waiting, { resume: true, capacity: 'freeze' }).outcome, 'frozen');
+    assert.equal((await reviveNode(waiting, { resume: true, capacity: 'freeze' })).outcome, 'frozen');
     // A real exit frees the slot; its policy job runs on the lane like production.
     tf.fleet.deliverExit(filler, { code: 0, signal: null });
     await tf.drain();
-    assert.equal(reviveNode(waiting, { resume: true, capacity: 'freeze' }).outcome, 'launched');
+    assert.equal((await reviveNode(waiting, { resume: true, capacity: 'freeze' })).outcome, 'launched');
     assert.equal(getNode(waiting).frozen_at ?? null, null, 'a launch is the definition of not-frozen');
     assert.equal(tf.fleet.has(waiting), true, 'the thawed node owns the freed slot');
 });