@north-light/crouter 0.3.263 → 0.3.270

package/dist/core/canvas/node-recap.js

@@ -0,0 +1,67 @@
+// node-recap.ts — the node's last Goal/State briefing, persisted.
+//
+// The recap itself is generated in the broker (`pi-extensions/canvas-recap.ts`)
+// and painted above the editor as throwaway chrome. That widget lives in broker
+// memory, so the moment a node goes dormant its briefing is gone — which is
+// exactly when a developer scanning `crtr canvas browse` needs it most ("what was
+// this one for, and where did it stop?"). Persisting the two lines the viewer
+// already produced makes them readable without a broker and without a model call.
+//
+// Stored beside telemetry in `job/` because it is machine-generated runtime
+// state, not a document the node authored: safe to delete, rebuilt on the node's
+// next idle recap. `context/` stays the agent's own document space.
+import { join } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { jobDir } from './paths.js';
+import { readJsonIfExists, atomicWriteJson } from '../fs-utils.js';
+function recapPath(nodeId) {
+    return join(jobDir(nodeId), 'recap.json');
+}
+/** Strip one leading `Goal:` / `State:` label from a briefing line. */
+function stripLabel(line) {
+    return line.replace(/^\s*(goal|state)\s*:\s*/i, '').trim();
+}
+/** Split the model's two-line briefing into its labelled halves. Returns null for
+ *  anything that doesn't yield at least one non-empty line — a garbled recap is
+ *  worse than none, so it is never stored. Missing labels fall back to line order
+ *  (the prompt asks for Goal first, State second). */
+export function parseRecapBriefing(briefing) {
+    const lines = briefing.split('\n').map((l) => l.trim()).filter((l) => l !== '');
+    if (lines.length === 0)
+        return null;
+    const labelled = (prefix) => lines.find((l) => new RegExp(`^${prefix}\\s*:`, 'i').test(l));
+    const goalLine = labelled('goal') ?? lines[0];
+    const stateLine = labelled('state') ?? (lines[1] !== goalLine ? lines[1] : undefined);
+    const goal = goalLine === undefined ? '' : stripLabel(goalLine);
+    const state = stateLine === undefined ? '' : stripLabel(stateLine);
+    if (goal === '' && state === '')
+        return null;
+    return { goal, state };
+}
+/** Persist a freshly generated briefing. Best-effort — a write failure only costs
+ *  the browse preview one stale panel, so it must never disturb the broker. */
+export function writeNodeRecap(nodeId, briefing) {
+    const parsed = parseRecapBriefing(briefing);
+    if (parsed === null)
+        return;
+    try {
+        mkdirSync(jobDir(nodeId), { recursive: true });
+        atomicWriteJson(recapPath(nodeId), { ...parsed, at: new Date().toISOString() });
+    }
+    catch {
+        /* best-effort: the recap is regenerated on the node's next idle window */
+    }
+}
+/** The node's stored briefing, or undefined when it never generated one (a node
+ *  that finished before its first idle window, or one last run before this file
+ *  existed). Never throws. */
+export function readNodeRecap(nodeId) {
+    const raw = readJsonIfExists(recapPath(nodeId));
+    if (raw === null || typeof raw !== 'object')
+        return undefined;
+    const goal = typeof raw.goal === 'string' ? raw.goal : '';
+    const state = typeof raw.state === 'string' ? raw.state : '';
+    if (goal === '' && state === '')
+        return undefined;
+    return { goal, state, at: typeof raw.at === 'string' ? raw.at : '' };
+}

package/dist/core/canvas/render-source.d.ts

@@ -1,4 +1,5 @@
 import type { CanvasSource } from './source.js';
+import { type NodeRecap } from './node-recap.js';
 import { type Fault } from '../runtime/fault.js';
 import type { NodeStatus, Lifecycle, NodeMeta, NodeRow, TerminalReason } from './types.js';
 export declare function activeFaultForDisplay<T extends {
@@ -69,6 +70,15 @@ export interface DashboardRow {
      *  by loadPreview (same single session read as `prompts`); undefined for a node whose
      *  session has no assistant reply yet. Shown in the preview's reply block. */
     lastAssistant?: string;
+    /** The node's last persisted Goal/State briefing (`job/recap.json`, written by the
+     *  broker's recap extension). Populated LAZILY by loadPreview; undefined for a node
+     *  that never generated one. The preview's fastest "what is this / where is it" line. */
+    recap?: NodeRecap;
+    /** The newest report the node pushed (`reports/<ts>-<id>-<kind>.md`). Populated
+     *  LAZILY by loadPreview; undefined when the node has pushed nothing. Residents push
+     *  updates as they work, so this is the last thing the node deliberately DELIVERED —
+     *  usually crisper than its last assistant message. */
+    report?: NodeReportPreview;
     /** True when the node is GENUINELY mid-turn right now — its `busy` marker exists
      *  AND its broker pid is alive (not merely an `active`, between-turns node). The
      *  live "is it generating?" cue. Computed on the cheap boot path for LIVE nodes
@@ -93,8 +103,30 @@ export interface DashboardRow {
     /** Lazy-enrichment guard (internal): true once loadPreview has read goal + the
      *  session (prompts + lastAssistant). Idempotency marker for the selected row. */
     previewLoaded?: boolean;
+    /** The source `NodeRow` this row was built from (dashboardRowFromNodeRow only).
+     *  Carries every column listNodes already fetched — the runtime fields
+     *  (host_kind/parent/waiting_for/final_report/finalized_at/pi_pid) plus the
+     *  mirrored identity fields (description/cycles) — so the snapshot handler
+     *  reads them here instead of opening meta.json.
+     *  Undefined for rows built by other paths (dashboardRowsFromSource). */
+    srcRow?: NodeRow;
 }
 export declare function readGoalText(nodeId: string): string | undefined;
+/** The newest pushed report, reduced to what a preview panel can use. */
+export interface NodeReportPreview {
+    /** final | update | urgent (frontmatter, else the filename suffix). */
+    kind: string;
+    /** ISO 8601 push time (frontmatter, else the filename stamp). */
+    ts: string;
+    /** The report's first markdown heading, or its first non-empty line. */
+    heading: string;
+    /** The body after that heading, whitespace-normalized + capped. */
+    body: string;
+}
+/** The node's newest report, read straight off disk. Report filenames lead with a
+ *  compact timestamp, so the lexicographic maximum is the latest one — no stat of
+ *  the whole directory. Never throws; undefined when the node pushed nothing. */
+export declare function readNewestReport(nodeId: string): NodeReportPreview | undefined;
 interface SessionParts {
     prompts?: string;
     lastAssistant?: string;
@@ -138,7 +170,7 @@ export declare function dashboardRowsFromSource(source: CanvasSource, rootId: st
  *  coupling the canvas source to local viewer state. Remote sources ignore that
  *  set. Local disk telemetry/fault/streaming are likewise suppressed remotely. */
 export declare function dashboardRowsAllFromSource(source: CanvasSource, localFocusedNodeIds?: ReadonlySet<string>, liveOnly?: boolean): Promise<DashboardRow[]>;
-export declare function enrichRowsFromSource(source: CanvasSource, rows: DashboardRow[], asks?: Record<string, number>): Promise<void>;
+export declare function enrichRowsFromSource(_source: CanvasSource, rows: DashboardRow[], asks?: Record<string, number>): Promise<void>;
 /** goal (initial-prompt.md) and session parts are local disk reads — suppressed
  *  to undefined for a remote source. */
 export declare function loadPreviewFromSource(source: CanvasSource, row: DashboardRow): Promise<DashboardRow>;

package/dist/core/canvas/render-source.js

@@ -9,14 +9,16 @@
 // migrated onto these `*FromSource` variants directly.
 //
 // ALLOWED imports (verified openDb-free): node:fs/path, ./pid.js, ./labels.js,
-// ./status-glyph.js, ../runtime/fault.js, ./paths.js, ./remote-canvas-source.js,
-// and TYPE-ONLY ./source.js + ./types.js. Do NOT import ./canvas.js, ./attention.js,
+// ./status-glyph.js, ./node-recap.js, ../runtime/fault.js, ../frontmatter.js,
+// ./paths.js, ./remote-canvas-source.js, and TYPE-ONLY ./source.js + ./types.js. Do NOT import ./canvas.js, ./attention.js,
 // ./focuses.js, or ./db.js here — that is the whole point of the split.
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { RemoteCanvasSource } from './remote-canvas-source.js';
 import { fullName } from './labels.js';
-import { jobDir, contextDir } from './paths.js';
+import { jobDir, contextDir, reportsDir } from './paths.js';
+import { readNodeRecap } from './node-recap.js';
+import { parseFrontmatterGeneric } from '../frontmatter.js';
 import { isPidAlive } from './pid.js';
 import { isFrozenRow, resolveNodeVisual, faultSummary } from './status-glyph.js';
 import { readFault } from '../runtime/fault.js';
@@ -168,6 +170,63 @@ export function readGoalText(nodeId) {
         return undefined;
     }
 }
+const REPORT_BODY_CAP = 1024;
+/** Compact report stamp `20260810T190533286` → an ISO 8601 instant. */
+function reportStampToIso(stamp) {
+    const m = stamp.match(/^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})(\d{3})?$/);
+    if (m === null)
+        return undefined;
+    return `${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}.${m[7] ?? '000'}Z`;
+}
+/** The node's newest report, read straight off disk. Report filenames lead with a
+ *  compact timestamp, so the lexicographic maximum is the latest one — no stat of
+ *  the whole directory. Never throws; undefined when the node pushed nothing. */
+export function readNewestReport(nodeId) {
+    let newest;
+    try {
+        for (const f of readdirSync(reportsDir(nodeId))) {
+            if (!f.endsWith('.md'))
+                continue;
+            if (newest === undefined || f > newest)
+                newest = f;
+        }
+    }
+    catch {
+        return undefined; // no reports dir
+    }
+    if (newest === undefined)
+        return undefined;
+    let raw;
+    try {
+        raw = readFileSync(join(reportsDir(nodeId), newest), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const { data, body } = parseFrontmatterGeneric(raw);
+    const name = newest.replace(/\.md$/, '');
+    const kind = typeof data?.['kind'] === 'string'
+        ? data['kind']
+        : (name.split('-').pop() ?? 'report');
+    const ts = typeof data?.['ts'] === 'string'
+        ? data['ts']
+        : (reportStampToIso(name.split('-')[0] ?? '') ?? '');
+    // The heading is the report's own headline; everything after it is the detail the
+    // preview shows next, so a panel never repeats the heading twice.
+    const lines = body.split('\n');
+    let heading = '';
+    let rest = body;
+    for (let i = 0; i < lines.length; i++) {
+        const t = (lines[i] ?? '').trim();
+        if (t === '')
+            continue;
+        heading = t.startsWith('#') ? t.replace(/^#+\s*/, '').trim() : t;
+        rest = lines.slice(i + 1).join('\n');
+        break;
+    }
+    const text = rest.replace(/\s+/g, ' ').trim();
+    return { kind, ts, heading, body: text.length > REPORT_BODY_CAP ? text.slice(0, REPORT_BODY_CAP) : text };
+}
 /** The node's session-derived preview text in ONE file read (today's two reads,
  *  folded): EVERY user prompt across the pi session (`prompts` — the whole
  *  conversation, not just the spawn prompt) AND the LAST assistant message text
@@ -385,8 +444,9 @@ export function dashboardRowFromNodeRow(row, focusedNodeIds, remote) {
     const hanging = remote ? null : activeFaultForDisplay(row, readFault(row.node_id));
     return {
         node_id: row.node_id,
-        name: row.name, // handle only; enrichRow upgrades to fullName (meta.description)
+        name: fullName(row), // description is a row column (v38) — no meta read needed
         handle: row.name,
+        description: row.description,
         status: row.status,
         frozen_at: row.frozen_at ?? null,
         terminal_reason: row.terminal_reason ?? null,
@@ -403,6 +463,7 @@ export function dashboardRowFromNodeRow(row, focusedNodeIds, remote) {
         streaming: !remote && hanging === null && live ? isStreaming(row.node_id, row.pi_pid) : false,
         hanging,
         viewed: remote ? false : focusedNodeIds.has(row.node_id) || hasLiveBrokerViewer(row),
+        srcRow: row,
     };
 }
 /** One row per node visible in the sub-DAG of `rootId` (including root), read
@@ -449,28 +510,23 @@ export async function dashboardRowsAllFromSource(source, localFocusedNodeIds = n
     const rows = await source.listNodes(liveOnly ? { status: ['active', 'idle'] } : undefined);
     return rows.map((row) => dashboardRowFromNodeRow(row, focusedNodeIds, remote));
 }
-// Lazy enrichment (source-driven) — fold expensive per-node reads into rows on
-// demand. Ask counts are supplied by the caller (`asks` — a pre-fetched
-// `ticketCountsForView` map merged across the visible roots), NOT scanned here
-// (`ticketCountsForNodes` reaches openDb). Telemetry (ctx tokens) + goal/session
-// are LOCAL disk reads, suppressed for a `RemoteCanvasSource`.
-export async function enrichRowsFromSource(source, rows, asks) {
+// Lazy enrichment (source-driven) — fold the per-node reads the cheap boot skips
+// into rows on demand. Ask counts are supplied by the caller (`asks` — a
+// pre-fetched `ticketCountsForView` map merged across the visible roots), NOT
+// scanned here (`ticketCountsForNodes` reaches openDb). Telemetry (ctx tokens) is
+// a LOCAL disk read, suppressed for a `RemoteCanvasSource`.
+//
+// This does NO source read. The label fields it used to re-fetch per node
+// (name/handle/description) are set by the row builders: `description` became a
+// nodes-table column in v38, so both builders already hold the full label and a
+// per-node getNode here would re-read what the caller's single listNodes returned.
+export async function enrichRowsFromSource(_source, rows, asks) {
     const todo = rows.filter((r) => r.enriched !== true);
     if (todo.length === 0)
         return;
-    const remote = source instanceof RemoteCanvasSource;
+    const remote = _source instanceof RemoteCanvasSource;
     const askMap = asks ?? {};
-    // A full dashboard may contain thousands of rows. Keep source reads serial:
-    // ApiCanvasSource turns each into a unix-socket request, and an unbounded
-    // Promise.all can overflow crtrd's accept backlog then spuriously trigger
-    // the client's cold-daemon path even though the daemon is still running.
     for (const row of todo) {
-        const meta = await source.getNode(row.node_id);
-        if (meta !== null) {
-            row.name = fullName(meta);
-            row.handle = meta.name;
-            row.description = meta.description;
-        }
         row.ctx_tokens = remote ? 0 : (readNodeTelemetry(row.node_id).tokens_in ?? 0);
         row.asks = askMap[row.node_id] ?? 0;
         row.enriched = true;
@@ -488,6 +544,8 @@ export async function loadPreviewFromSource(source, row) {
         const { prompts, lastAssistant } = readSessionParts(meta?.pi_session_file);
         row.prompts = prompts;
         row.lastAssistant = lastAssistant;
+        row.recap = readNodeRecap(row.node_id);
+        row.report = readNewestReport(row.node_id);
     }
     row.previewLoaded = true;
     return row;

package/dist/core/canvas/types.d.ts

@@ -292,6 +292,15 @@ export type NodeMeta = NodeIdentity & NodeRuntime;
 export interface NodeRow {
     node_id: string;
     name: string;
+    /** The pi-generated first-task description; see NodeIdentity.description.
+     *  Durable IDENTITY mirrored to the row (like `cwd`/`host_kind`) so a roster
+     *  read can build the full display label without opening meta.json. Absent for
+     *  a node not yet named — the column's NULL is mapped to undefined at `rowFrom`
+     *  so identity, row, and DTO all spell "unnamed" the same way. */
+    description?: string;
+    /** Relaunch count; see NodeIdentity.cycles. Mirrored to the row for the same
+     *  reason as `description`; absent on a row written before this column. */
+    cycles?: number;
     kind: string;
     mode: Mode;
     lifecycle: Lifecycle;

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;