@north-light/crouter 0.3.219 → 0.3.221

package/dist/core/canvas/browse/model.js

@@ -160,24 +160,18 @@ export function matchIndices(query, text) {
 }
 /** Chars of leading context kept before the match start when windowing. */
 const SNIPPET_LEAD = 12;
-/** Highlight indices for the preview: the literal case-insensitive SUBSTRING span
- *  when present (so "where does this text appear?" is answered exactly), else the
- *  scattered subsequence indices, else empty (empty query). This is a different,
- *  stricter model than the subsequence super-search on purpose — a contiguous span
- *  is what reads as a highlight. */
+/** The literal case-insensitive substring span in a conversation preview.
+ *  Scattered letters are not a message match and never receive a highlight. */
 export function highlightIndices(query, text) {
     if (query === '')
         return new Set();
-    const lower = text.toLowerCase();
-    const q = query.toLowerCase();
-    const sub = lower.indexOf(q);
-    if (sub >= 0) {
-        const out = new Set();
-        for (let i = sub; i < sub + q.length; i++)
-            out.add(i);
-        return out;
-    }
-    return matchIndices(query, text);
+    const sub = text.toLowerCase().indexOf(query.toLowerCase());
+    if (sub < 0)
+        return new Set();
+    const out = new Set();
+    for (let i = sub; i < sub + query.length; i++)
+        out.add(i);
+    return out;
 }
 /** Greedy word-wrap of single-spaced `s` (caller normalizes whitespace) to `width`
  *  cols × `maxLines` lines, returning each line's text AND its start offset in `s`.
@@ -233,17 +227,7 @@ export function previewSnippet(query, text, width, maxLines) {
         return [];
     // 1. Locate the match in the normalized text + choose a window start that keeps
     //    a little leading context, snapped to a word boundary.
-    let matchStart = -1;
-    if (query !== '') {
-        const sub = norm.toLowerCase().indexOf(query.toLowerCase());
-        if (sub >= 0)
-            matchStart = sub;
-        else {
-            const ix = matchIndices(query, norm);
-            if (ix.size > 0)
-                matchStart = Math.min(...ix);
-        }
-    }
+    const matchStart = query === '' ? -1 : norm.toLowerCase().indexOf(query.toLowerCase());
     let windowStart = 0;
     if (matchStart > SNIPPET_LEAD) {
         let s = matchStart - SNIPPET_LEAD;
@@ -274,52 +258,69 @@ function shortId(id) {
 export function promptText(row) {
     return row.prompts ?? row.goal ?? '';
 }
-/** Does this row match the live query? Super-search spans name (which already
- *  folds in the pi-generated description), kind, short-id, AND every user prompt
- *  in the conversation (`promptText`). Empty query matches everything. */
+/** Does this row match the live query? Empty query matches everything; a
+ *  non-empty query uses the same fields and match tiers as relevance ranking. */
 export function queryMatch(query, row) {
-    if (query === '')
-        return true;
-    const prompt = promptText(row);
-    return (fuzzyMatch(query, row.name) ||
-        fuzzyMatch(query, row.kind) ||
-        fuzzyMatch(query, shortId(row.node_id)) ||
-        (prompt !== '' && fuzzyMatch(query, prompt)));
+    return query === '' || scoreRow(query, row).tier > 0;
 }
-// ---------------------------------------------------------------------------
-// Relevance scoring (super-search)
-// ---------------------------------------------------------------------------
-/** Score how well `query` matches one field, 0 (no match) → 1 (exact). Tiers:
- *  exact > prefix > word-boundary substring > interior substring > subsequence.
- *  An interior match decays slightly the later it starts so leading matches win. */
-export function fieldScore(query, text) {
+const NO_MATCH = { tier: 0, quality: 0 };
+const WORD_CHAR = /[\p{L}\p{N}]/u;
+function isWordChar(char) {
+    return char !== undefined && WORD_CHAR.test(char);
+}
+/** One field's best match. Match class is deliberately separate from quality:
+ *  a bounded literal always outranks a contiguous partial, which always outranks
+ *  a scattered subsequence, regardless of field weights. */
+export function fieldMatch(query, text) {
     if (query === '' || text === '')
-        return 0;
+        return NO_MATCH;
     const q = query.toLowerCase();
     const t = text.toLowerCase();
-    const idx = t.indexOf(q);
-    if (idx === 0)
-        return t.length === q.length ? 1 : 0.85; // exact | prefix
-    if (idx > 0) {
-        const prev = t[idx - 1] ?? '';
-        const boundary = /[\s_\-/.:]/.test(prev) ? 0.1 : 0; // word-boundary bonus
-        return 0.55 + boundary - Math.min(0.2, idx / 400); // interior, decays late
+    const firstIdx = t.indexOf(q);
+    if (firstIdx >= 0) {
+        for (let idx = firstIdx; idx >= 0; idx = t.indexOf(q, idx + 1)) {
+            const end = idx + q.length;
+            const leftBounded = !isWordChar(q[0]) || !isWordChar(t[idx - 1]);
+            const rightBounded = !isWordChar(q[q.length - 1]) || !isWordChar(t[end]);
+            if (leftBounded && rightBounded)
+                return { tier: 3, quality: t === q ? 1 : 0.95 };
+        }
+        const position = Math.min(0.2, firstIdx / 400);
+        return { tier: 2, quality: (firstIdx === 0 ? 1 : 0.8) - position };
     }
-    return fuzzyMatch(q, t) ? 0.2 : 0; // scattered subsequence
+    const indices = [...matchIndices(q, t)];
+    if (indices.length === 0)
+        return NO_MATCH;
+    const span = indices[indices.length - 1] - indices[0] + 1;
+    return { tier: 1, quality: q.length / span };
+}
+/** Explicit handles and user prompts are primary. The generated description is
+ *  searchable but lower-weight; assistant replies are preview-only. */
+const FIELD_WEIGHTS = { handle: 4, prompt: 4, kind: 2, description: 1.5, id: 1 };
+function explicitHandle(row) {
+    const handle = row.handle ?? row.name;
+    return handle === row.kind ? '' : handle;
 }
-/** Per-field weights — name (handle + description) dominates, the conversation
- *  prompts are the long-tail super-search field. */
-const FIELD_WEIGHTS = { name: 4, kind: 2, id: 1, prompt: 1.5 };
-/** Weighted relevance of a row to the query across all searched fields. 0 means
- *  no field matched (excluded from relevance results, same as `queryMatch`). */
+/** Rank a row by its strongest match class, then by weighted evidence only from
+ *  that class. Weaker classes cannot add up to beat one stronger literal match. */
 export function scoreRow(query, row) {
     if (query === '')
-        return 0;
-    const prompt = promptText(row);
-    return (FIELD_WEIGHTS.name * fieldScore(query, row.name) +
-        FIELD_WEIGHTS.kind * fieldScore(query, row.kind) +
-        FIELD_WEIGHTS.id * fieldScore(query, shortId(row.node_id)) +
-        FIELD_WEIGHTS.prompt * (prompt !== '' ? fieldScore(query, prompt) : 0));
+        return { tier: 0, strength: 0 };
+    const fields = [
+        { text: explicitHandle(row), weight: FIELD_WEIGHTS.handle, minimumTier: 1 },
+        // Scattered subsequences in long messages are random noise, not matches.
+        { text: promptText(row), weight: FIELD_WEIGHTS.prompt, minimumTier: 2 },
+        { text: row.kind, weight: FIELD_WEIGHTS.kind, minimumTier: 1 },
+        { text: row.description ?? '', weight: FIELD_WEIGHTS.description, minimumTier: 1 },
+        { text: shortId(row.node_id), weight: FIELD_WEIGHTS.id, minimumTier: 1 },
+    ];
+    const matches = fields.map(({ text, weight, minimumTier }) => {
+        const match = fieldMatch(query, text);
+        return { match: match.tier >= minimumTier ? match : NO_MATCH, weight };
+    });
+    const tier = Math.max(...matches.map(({ match }) => match.tier));
+    const strength = matches.reduce((sum, { match, weight }) => sum + (match.tier === tier ? match.quality * weight : 0), 0);
+    return { tier, strength };
 }
 // ---------------------------------------------------------------------------
 // Attention tiering (default sort)
@@ -339,6 +340,14 @@ export function attentionMtime(row) {
     const t = Date.parse(row.created);
     return Number.isFinite(t) ? t : 0;
 }
+const RELEVANCE_RECENCY_MAX_BOOST = 0.1;
+const RELEVANCE_RECENCY_HALF_LIFE_MS = 7 * 24 * 60 * 60 * 1000;
+/** Up to a 10% relevance lift for recent conversation activity, halving after a
+ *  week. Match tier remains separate, so freshness never promotes fuzzy over literal. */
+export function relevanceFreshness(row, now) {
+    const age = Math.max(0, now - attentionMtime(row));
+    return 1 + RELEVANCE_RECENCY_MAX_BOOST / (1 + age / RELEVANCE_RECENCY_HALF_LIFE_MS);
+}
 /** Attention tier (lower = higher priority, shown first):
  *    T0 — attached AND streaming (`viewed && streaming`)
  *    T1 — attached, not streaming (`viewed`)
@@ -427,9 +436,21 @@ export function flatten(tree, opts) {
         }
         else {
             const score = new Map();
+            const rowOf = (id) => tree.nodes.get(id).row;
+            const now = Date.now();
             for (const id of ids)
-                score.set(id, scoreRow(query, tree.nodes.get(id).row));
-            ids.sort((a, b) => (pinRank(a) - pinRank(b)) || (score.get(b) - score.get(a)) || byRecency(a, b));
+                score.set(id, scoreRow(query, rowOf(id)));
+            ids.sort((a, b) => {
+                const aScore = score.get(a);
+                const bScore = score.get(b);
+                const aStrength = aScore.strength * relevanceFreshness(rowOf(a), now);
+                const bStrength = bScore.strength * relevanceFreshness(rowOf(b), now);
+                return (pinRank(a) - pinRank(b))
+                    || (bScore.tier - aScore.tier)
+                    || (bStrength - aStrength)
+                    || (attentionMtime(rowOf(b)) - attentionMtime(rowOf(a)))
+                    || byRecency(a, b);
+            });
         }
         return ids.map((id) => ({ id, depth: 0, hasChildren: false, collapsed: false, matched: true }));
     }

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

@@ -16,7 +16,13 @@ export declare function renderTreeFromSource(source: CanvasSource, rootId: strin
 export declare function renderForestFromSource(source: CanvasSource): Promise<string>;
 export interface DashboardRow {
     node_id: string;
+    /** Full display label: explicit handle plus generated description. */
     name: string;
+    /** Explicit node handle, kept separate so search does not treat generated text
+     *  as part of the higher-weight name field. */
+    handle?: string;
+    /** Generated first-task description. Searchable below user-authored prompts. */
+    description?: string;
     status: NodeStatus;
     kind: string;
     mode: string;

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

@@ -366,6 +366,7 @@ export function dashboardRowFromNodeRow(row, focusedNodeIds, remote) {
     return {
         node_id: row.node_id,
         name: row.name, // handle only; enrichRow upgrades to fullName (meta.description)
+        handle: row.name,
         status: row.status,
         kind: row.kind,
         mode: row.mode,
@@ -399,6 +400,8 @@ export async function dashboardRowsFromSource(source, rootId) {
         rows.push({
             node_id: id,
             name: fullName(node),
+            handle: node.name,
+            description: node.description,
             status: node.status,
             kind: node.kind,
             mode: node.mode,
@@ -440,8 +443,11 @@ export async function enrichRowsFromSource(source, rows, asks) {
     // 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)
+        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;

package/dist/core/canvas/render.js

@@ -155,6 +155,8 @@ export function dashboardRows(rootId) {
         return [{
                 node_id: id,
                 name: fullName(node),
+                handle: node.name,
+                description: node.description,
                 status: node.status,
                 kind: node.kind,
                 mode: node.mode,
@@ -189,8 +191,11 @@ export function enrichRow(row) {
     if (row.enriched === true)
         return row;
     const meta = getNode(row.node_id);
-    if (meta !== null)
+    if (meta !== null) {
         row.name = fullName(meta);
+        row.handle = meta.name;
+        row.description = meta.description;
+    }
     row.ctx_tokens = readNodeTelemetry(row.node_id).tokens_in ?? 0;
     row.asks = countTickets(row.node_id);
     row.enriched = true;
@@ -206,8 +211,11 @@ export function enrichRows(rows) {
     const asks = ticketCountsForNodes(todo.map((r) => r.node_id));
     for (const row of todo) {
         const meta = getNode(row.node_id);
-        if (meta !== null)
+        if (meta !== null) {
             row.name = fullName(meta);
+            row.handle = meta.name;
+            row.description = meta.description;
+        }
         row.ctx_tokens = readNodeTelemetry(row.node_id).tokens_in ?? 0;
         row.asks = asks[row.node_id] ?? 0;
         row.enriched = true;

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

@@ -0,0 +1,10 @@
+import type { PluginManifest } from '../../types.js';
+import { type HookManifestIssue, type ValidatedHookManifest } from './schema.js';
+export interface HookArtifactValidation {
+    manifestPath?: string;
+    executablePath?: string;
+    manifest?: ValidatedHookManifest;
+    issues: HookManifestIssue[];
+}
+/** Statically validates the local hook artifact a source plugin ships. */
+export declare function validatePluginHookArtifact(root: string, manifest: Pick<PluginManifest, 'hooks' | 'hookExecutable'>): HookArtifactValidation;

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

@@ -0,0 +1,129 @@
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, resolve, sep } from 'node:path';
+import { validateHookManifest } from './schema.js';
+function safeFilePath(root, pointer) {
+    if (isAbsolute(pointer))
+        return null;
+    try {
+        const rootReal = realpathSync(root);
+        const path = realpathSync(resolve(root, pointer));
+        return (path === rootReal || path.startsWith(rootReal + sep)) && statSync(path).isFile() ? path : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Statically validates the local hook artifact a source plugin ships. */
+export function validatePluginHookArtifact(root, manifest) {
+    const hooks = manifest.hooks;
+    const executable = manifest.hookExecutable;
+    const issues = [];
+    const hasHooks = hooks !== undefined;
+    const hasExecutable = executable !== undefined;
+    if (hasHooks !== hasExecutable) {
+        issues.push({
+            code: 'hook_manifest_invalid',
+            path: hasHooks ? 'hookExecutable' : 'hooks',
+            message: 'hooks and hookExecutable must be declared together',
+            received: hasHooks ? 'hooks without hookExecutable' : 'hookExecutable without hooks',
+            expected: 'both hooks and hookExecutable',
+            next: hasHooks ? 'Add plugin.json.hookExecutable or remove hooks.' : 'Add plugin.json.hooks or remove hookExecutable.',
+        });
+        return { issues };
+    }
+    if (!hasHooks)
+        return { issues };
+    if (typeof hooks !== 'string' || hooks.length === 0) {
+        issues.push({
+            code: 'hook_manifest_invalid',
+            path: 'hooks',
+            message: 'hooks must be a non-empty plugin-root-relative path',
+            received: typeof hooks === 'string' ? '(empty)' : Array.isArray(hooks) ? 'array' : typeof hooks,
+            expected: 'a non-empty relative path to hooks.json',
+            next: 'Fix plugin.json.hooks.',
+        });
+    }
+    if (typeof executable !== 'string' || executable.length === 0) {
+        issues.push({
+            code: 'hook_manifest_invalid',
+            path: 'hookExecutable',
+            message: 'hookExecutable must be a non-empty plugin-root-relative path',
+            received: typeof executable === 'string' ? '(empty)' : Array.isArray(executable) ? 'array' : typeof executable,
+            expected: 'a non-empty relative path to an executable file',
+            next: 'Fix plugin.json.hookExecutable.',
+        });
+    }
+    if (issues.length > 0)
+        return { issues };
+    const hooksPointer = hooks;
+    const executablePointer = executable;
+    const manifestPath = safeFilePath(root, hooksPointer);
+    if (manifestPath === null) {
+        issues.push({
+            code: 'hook_path_unsafe',
+            path: 'hooks',
+            message: 'hooks pointer escapes the plugin root or is not a regular file',
+            received: hooksPointer,
+            expected: 'a relative path to a regular file inside the plugin root',
+            next: 'Fix plugin.json.hooks.',
+        });
+    }
+    const executablePath = safeFilePath(root, executablePointer);
+    if (executablePath === null) {
+        issues.push({
+            code: 'hook_path_unsafe',
+            path: 'hookExecutable',
+            message: 'hookExecutable escapes the plugin root or is not a regular file',
+            received: executablePointer,
+            expected: 'a relative path to a regular file inside the plugin root',
+            next: 'Fix plugin.json.hookExecutable.',
+        });
+    }
+    if (executablePath !== null && (statSync(executablePath).mode & 0o111) === 0) {
+        issues.push({
+            code: 'hook_not_executable',
+            path: 'hookExecutable',
+            message: 'hookExecutable lacks the POSIX exec bit',
+            received: executablePointer,
+            expected: 'a file with an executable permission bit',
+            next: 'chmod +x the hook executable, then update the plugin.',
+        });
+    }
+    if (manifestPath === null)
+        return { ...(executablePath === null ? {} : { executablePath }), issues };
+    let text;
+    try {
+        text = readFileSync(manifestPath, 'utf8');
+    }
+    catch {
+        issues.push({
+            code: 'hook_manifest_unreadable',
+            message: 'hooks.json is missing or unreadable',
+            received: manifestPath,
+            expected: 'a readable JSON file',
+            next: 'Reinstall or update the plugin.',
+        });
+        return { manifestPath, ...(executablePath === null ? {} : { executablePath }), issues };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        issues.push({
+            code: 'hook_manifest_invalid',
+            message: 'hooks.json is not valid JSON',
+            received: manifestPath,
+            expected: 'a JSON object',
+            next: 'Regenerate hooks.json.',
+        });
+        return { manifestPath, ...(executablePath === null ? {} : { executablePath }), issues };
+    }
+    const validation = validateHookManifest(raw);
+    return {
+        manifestPath,
+        ...(executablePath === null ? {} : { executablePath }),
+        ...(validation.manifest === undefined ? {} : { manifest: validation.manifest }),
+        issues: [...issues, ...validation.issues],
+    };
+}

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

@@ -0,0 +1,14 @@
+import type { BranchDef, LeafDef } from '../command.js';
+export interface CoreHookTarget {
+    /** Exact space-joined core leaf path named by hooks.json. */
+    path: string;
+    segments: readonly string[];
+    leaf: LeafDef;
+}
+export interface CoreHookCatalog {
+    targets: readonly CoreHookTarget[];
+    byPath: ReadonlyMap<string, CoreHookTarget>;
+    has(path: string): boolean;
+}
+/** Projects every composed core subtree to leaves whose objects flow through central rendering. */
+export declare function createCoreHookCatalog(subtrees: readonly BranchDef[]): CoreHookCatalog;

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

@@ -0,0 +1,38 @@
+const NON_RETURNING_OBJECT_LEAVES = new Set([
+    'pkg browse',
+    'sys settings',
+    'sys setup',
+    'canvas browse',
+    'surface inspect',
+]);
+function excluded(path) {
+    return path === 'sys doctor'
+        || path === 'pkg plugin'
+        || path.startsWith('pkg plugin ')
+        || NON_RETURNING_OBJECT_LEAVES.has(path);
+}
+/** Projects every composed core subtree to leaves whose objects flow through central rendering. */
+export function createCoreHookCatalog(subtrees) {
+    const targets = [];
+    const visit = (node, segments) => {
+        const path = segments.join(' ');
+        if (node.kind === 'leaf') {
+            if (node.help.outputKind === 'object' && node.hookEligible !== false && !excluded(path)) {
+                targets.push({ path, segments: Object.freeze([...segments]), leaf: node });
+            }
+            return;
+        }
+        if (node.passthrough !== undefined || excluded(path))
+            return;
+        for (const child of node.children)
+            visit(child, [...segments, child.name]);
+    };
+    for (const subtree of subtrees)
+        visit(subtree, [subtree.name]);
+    const byPath = new Map(targets.map((target) => [target.path, target]));
+    return Object.freeze({
+        targets: Object.freeze(targets),
+        byPath,
+        has: (path) => byPath.has(path),
+    });
+}

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

@@ -0,0 +1,15 @@
+import type { BranchDef } from '../command.js';
+import type { HookRegistry } from './discovery.js';
+/** Registry compilation never executes hook code. */
+export type HookRegistryLoader = () => Promise<HookRegistry>;
+/** Wrap every hook-eligible core leaf so its run is the before → primary →
+ *  after pipeline. Nothing else about the leaf changes: path, params, frozen
+ *  help, renderer, and output declaration are carried through untouched, and
+ *  ineligible leaves (JSONL, UI/void, `pkg plugin`, `sys doctor`, passthrough)
+ *  keep their original run function so recovery dispatch never depends on hook
+ *  discovery.
+ *
+ *  Eligibility is per-path, so projecting the passed subtrees answers it for
+ *  those subtrees exactly as the complete catalog would; the complete catalog
+ *  is what the loaded registry validates hook targets against. */
+export declare function composeCoreHooks(subtrees: readonly BranchDef[], loadRegistry: HookRegistryLoader): BranchDef[];

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

@@ -0,0 +1,99 @@
+import { ExitCode } from '../../types.js';
+import { CrtrError } from '../errors.js';
+import { operationIdContext } from '../events/operation-id.js';
+import { createCoreHookCatalog } from './catalog.js';
+/** Wrap every hook-eligible core leaf so its run is the before → primary →
+ *  after pipeline. Nothing else about the leaf changes: path, params, frozen
+ *  help, renderer, and output declaration are carried through untouched, and
+ *  ineligible leaves (JSONL, UI/void, `pkg plugin`, `sys doctor`, passthrough)
+ *  keep their original run function so recovery dispatch never depends on hook
+ *  discovery.
+ *
+ *  Eligibility is per-path, so projecting the passed subtrees answers it for
+ *  those subtrees exactly as the complete catalog would; the complete catalog
+ *  is what the loaded registry validates hook targets against. */
+export function composeCoreHooks(subtrees, loadRegistry) {
+    const eligible = createCoreHookCatalog(subtrees);
+    const visit = (node, segments) => {
+        if (node.kind === 'leaf') {
+            const path = segments.join(' ');
+            if (!eligible.has(path))
+                return node;
+            return Object.freeze({
+                ...node,
+                effectiveHelp: projectedHelp(node, path, loadRegistry),
+                run: hookedRun(node, segments, loadRegistry),
+            });
+        }
+        return { ...node, children: node.children.map((child) => visit(child, [...segments, child.name])) };
+    };
+    return subtrees.map((subtree) => visit(subtree, [subtree.name]));
+}
+function projectedHelp(leaf, path, loadRegistry) {
+    return async () => {
+        const { projectEffectiveLeafHelp } = await import('./help.js');
+        try {
+            const registry = await loadRegistry();
+            // Invalid configuration fails closed on dispatch, but help remains the
+            // bounded static core contract so recovery is never stranded.
+            return projectEffectiveLeafHelp(leaf.help, registry.valid ? registry.plans.get(path) : undefined);
+        }
+        catch {
+            return projectEffectiveLeafHelp(leaf.help);
+        }
+    };
+}
+function hookedRun(leaf, segments, loadRegistry) {
+    const core = leaf.run;
+    const path = segments.join(' ');
+    return async (input, context) => {
+        const registry = await loadRegistry();
+        if (!registry.valid)
+            throw registryError(path, registry.issues);
+        const plan = registry.plans.get(path);
+        if (plan === undefined)
+            return core(input, context);
+        // The one fresh operation identity runCli already entered surrounds this
+        // whole pipeline; hooks and the core primary share that ambient ID.
+        const operationId = operationIdContext.current();
+        if (operationId === undefined)
+            throw new CrtrError('internal', `\`${path}\` ran outside a crouter operation identity, so its plugin hooks cannot be dispatched.`, ExitCode.GENERAL, { command: [...segments] });
+        const { invokeExecHook } = await import('./transport/exec-invoke.js');
+        const spec = (hook) => ({
+            plugin: hook.plugin.name,
+            executable: hook.executable,
+            op: hook.op,
+            phase: hook.phase,
+            commandPath: segments,
+            ...(hook.phase === 'replace' ? { output: leaf.help.output } : {}),
+        });
+        const providedParams = [...(context?.providedParams ?? [])];
+        for (const hook of plan.before)
+            await invokeExecHook(spec(hook), { operationId, input, providedParams });
+        const replacement = plan.replacements[0];
+        const result = replacement === undefined
+            ? await core(input, context)
+            : await invokeExecHook(spec(replacement), { operationId, input, providedParams });
+        // `after` is reverse discovery order, preserving middleware nesting.
+        for (const hook of plan.after)
+            await invokeExecHook(spec(hook), { operationId, input, providedParams, ...(result === undefined ? {} : { result }) });
+        return result;
+    };
+}
+/** Fail closed on an invalid manifest, stale target, or replacement collision:
+ *  silently dropping a declared hook would run the command without behavior the
+ *  caller expects. Every issue is spelled out in the message, because the
+ *  central error payload carries only code/message/received/field/next — an
+ *  issue list parked in `details` would never reach the caller. */
+function registryError(path, issues) {
+    const first = issues[0];
+    const detail = issues
+        .map((issue) => `${issue.plugin} (${issue.scope}) ${issue.path ?? 'hooks'}: ${issue.message} — received ${issue.received}, expected ${issue.expected}`)
+        .join('; ');
+    const plugins = [...new Set(issues.map((issue) => issue.plugin))];
+    return new CrtrError(first.code, `\`${path}\` cannot run: ${String(issues.length)} unusable hook declaration${issues.length === 1 ? '' : 's'} — ${detail}.`, ExitCode.GENERAL, {
+        received: first.received,
+        ...(first.path === undefined ? {} : { field: first.path }),
+        next: `${first.next} ${plugins.map((plugin) => `\`crtr pkg plugin show ${plugin}\``).join(' and ')} or \`crtr sys doctor\` reports the same issues; disabling the plugin also clears them.`,
+    });
+}