@north-light/crouter 0.3.263 → 0.3.270

package/dist/commands/canvas-history/grep.js

@@ -1,14 +1,14 @@
 import { defineLeaf } from '../../core/command.js';
 import { usage } from '../../core/errors.js';
 import { cliClient, rethrowAsCliError } from '../api-client.js';
-import { filterParams, parseFilters } from './shared.js';
+import { applyFilters, filterParams, parseFilters } from './shared.js';
 export const grepLeaf = defineLeaf({
     name: 'grep',
     description: 'exact regex line search across the cwd\'s node history',
     whenToUse: 'you know the exact string or pattern you\'re looking for — an error message, a literal identifier, a code fragment — and want every matching body LINE across every node that ran in this cwd, not a relevance ranking. The pattern is required (an ECMAScript regex, case-insensitive). Narrow with --type/--kind/--status/--since, scope elsewhere with --cwd/--all-cwds/--under/--node. Want ranked/browse search instead? Use `canvas history search` — a distinct leaf, not a flag here. Use `canvas history read <ref>` to read a hit\'s full body, `node inspect artifacts <node-id>` to list one node\'s artifacts, and `node lifecycle revive <id>` to reopen a node you found.',
     help: {
         name: 'canvas history grep',
-        summary: 'required-pattern regex line search over the per-cwd episodic record (reports + context docs + meta)',
+        summary: 'required-pattern regex line search over the per-cwd episodic record (reports + context docs + meta; transcripts and inbox opt-in)',
         params: [
             { kind: 'positional', name: 'pattern', required: true, constraint: 'An ECMAScript regex, matched case-insensitively against each body line. One hit per matching line.' },
             ...filterParams,
@@ -43,26 +43,7 @@ export const grepLeaf = defineLeaf({
         // closures cannot cross the wire.
         const f = parseFilters(input);
         const q = { pattern, limit };
-        if (f.cwd !== undefined)
-            q.cwd = f.cwd;
-        if (f.allCwds)
-            q.all_cwds = true;
-        if (f.under !== undefined)
-            q.under = f.under;
-        if (f.nodes !== undefined)
-            q.nodes = f.nodes;
-        if (f.types !== undefined)
-            q.types = f.types;
-        if (f.reportKind !== undefined)
-            q.report_kind = f.reportKind;
-        if (f.kinds !== undefined)
-            q.kinds = f.kinds;
-        if (f.statuses !== undefined)
-            q.statuses = f.statuses;
-        if (f.sinceMs !== undefined)
-            q.since_ms = f.sinceMs;
-        if (f.untilMs !== undefined)
-            q.until_ms = f.untilMs;
+        applyFilters(q, f);
         if (cursor !== undefined)
             q.cursor = cursor;
         try {

package/dist/commands/canvas-history/read.js

@@ -9,13 +9,14 @@ export const readLeaf = defineLeaf({
         name: 'canvas history read',
         summary: 'resolve a <node-id>:<relpath> ref to its full artifact body',
         params: [
-            { kind: 'positional', name: 'ref', required: true, constraint: 'The <node-id>:<relpath> handle from `canvas history search` (e.g. mq186ky0-c754531c:reports/20260607T075536-final.md, or <node-id>:meta for a node\'s identity).' },
+            { kind: 'positional', name: 'ref', required: true, constraint: 'The <node-id>:<relpath> handle from `canvas history search` (e.g. mq186ky0-c754531c:reports/20260607T075536-final.md, or <node-id>:meta for a node\'s identity). <node-id>:session addresses a node\'s whole conversation; <node-id>:session/<index> one message in it.' },
             { kind: 'flag', name: 'frontmatter', type: 'bool', required: false, constraint: 'Include the artifact\'s YAML frontmatter. Stripped by default.' },
+            { kind: 'flag', name: 'format', type: 'enum', choices: ['rendered', 'raw'], required: false, default: 'rendered', constraint: 'raw returns the verbatim bytes behind the ref — the session .jsonl for a bare session ref, the single persisted jsonl entry for one message, the unparsed file for a report or doc. Use it when the rendered view may be hiding what you are chasing.' },
         ],
         output: [
             { name: 'ref', type: 'string', required: true, constraint: 'Echo of the resolved ref.' },
             { name: 'node', type: 'string', required: true, constraint: 'Node name + id.' },
-            { name: 'source', type: 'string', required: true, constraint: 'report | doc | roadmap | meta (+ report-kind for reports).' },
+            { name: 'source', type: 'string', required: true, constraint: 'report | doc | roadmap | meta | inbox | transcript (+ report-kind for reports).' },
             { name: 'ts', type: 'string', required: true, constraint: 'Artifact timestamp.' },
             { name: 'content', type: 'string', required: true, constraint: 'Full body. Frontmatter stripped unless --frontmatter.' },
         ],
@@ -25,6 +26,7 @@ export const readLeaf = defineLeaf({
     run: async (input) => {
         const ref = input['ref'].trim();
         const includeFrontmatter = input['frontmatter'] === true;
+        const format = input['format'] ?? 'rendered';
         // Fast local shape check; ref resolution (+ its usage/not-found errors) runs
         // server-side in crtrd (`GET /v1/canvas/history/read`).
         if (!ref.includes(':')) {
@@ -34,7 +36,7 @@ export const readLeaf = defineLeaf({
             });
         }
         try {
-            const res = await cliClient().historyRead({ ref, frontmatter: includeFrontmatter });
+            const res = await cliClient().historyRead({ ref, frontmatter: includeFrontmatter, format });
             return { ref: res.ref, node: res.node, source: res.source, ts: res.ts, content: res.content };
         }
         catch (err) {

package/dist/commands/canvas-history/search.js

@@ -1,6 +1,6 @@
 import { defineLeaf } from '../../core/command.js';
 import { cliClient, rethrowAsCliError } from '../api-client.js';
-import { filterParams, parseFilters } from './shared.js';
+import { applyFilters, filterParams, parseFilters } from './shared.js';
 const SORTS = ['relevance', 'recency', 'oldest'];
 export const searchLeaf = defineLeaf({
     name: 'search',
@@ -8,7 +8,7 @@ export const searchLeaf = defineLeaf({
     whenToUse: 'you want to find past work by what it SAYS — a design, a final report, a roadmap, a finding — across every node that ran in this cwd, ranked by relevance. Omit the query to browse the record by recency ("what happened here lately"). Narrow with --type/--kind/--status/--since, scope elsewhere with --cwd/--all-cwds/--under/--node. Need an exact regex over bodies instead of ranking? Use `canvas history grep` — a distinct leaf, not a flag here. Use `canvas history read <ref>` to read a hit in full, `node inspect artifacts <node-id>` to list one node\'s artifacts, and `node lifecycle revive <id>` to reopen a node you found.',
     help: {
         name: 'canvas history search',
-        summary: 'ranked/filtered/sorted content search over the per-cwd episodic record (reports + context docs + meta)',
+        summary: 'ranked/filtered/sorted content search over the per-cwd episodic record (reports + context docs + meta; transcripts and inbox opt-in)',
         params: [
             { kind: 'positional', name: 'query', required: false, constraint: 'Whitespace-separated terms, matched case-insensitively and weighted across node name/description, report titles, and doc headings (and full bodies with --body); artifacts matching more/stronger fields rank higher. Omit to browse by recency (no relevance ranking; --sort still applies).' },
             ...filterParams,
@@ -45,26 +45,7 @@ export const searchLeaf = defineLeaf({
         const q = { snippet_lines: snippetLines, limit, sort: sortMode };
         if (query !== '')
             q.query = query;
-        if (f.cwd !== undefined)
-            q.cwd = f.cwd;
-        if (f.allCwds)
-            q.all_cwds = true;
-        if (f.under !== undefined)
-            q.under = f.under;
-        if (f.nodes !== undefined)
-            q.nodes = f.nodes;
-        if (f.types !== undefined)
-            q.types = f.types;
-        if (f.reportKind !== undefined)
-            q.report_kind = f.reportKind;
-        if (f.kinds !== undefined)
-            q.kinds = f.kinds;
-        if (f.statuses !== undefined)
-            q.statuses = f.statuses;
-        if (f.sinceMs !== undefined)
-            q.since_ms = f.sinceMs;
-        if (f.untilMs !== undefined)
-            q.until_ms = f.untilMs;
+        applyFilters(q, f);
         if (weighBody)
             q.weigh_body = true;
         if (full)

package/dist/commands/canvas-history/shared.d.ts

@@ -1,5 +1,7 @@
 import type { InputParam } from '../../core/help.js';
 export declare const TYPES: string[];
+export declare const ORIGINS: string[];
+export declare const ROLES: string[];
 export declare const NODE_KINDS: string[];
 export declare const STATUSES: string[];
 /** ISO 8601 (`2026-06-01`) \u2192 epoch ms (absolute); relative (`7d`, `2w`, `1mo`)
@@ -21,7 +23,13 @@ export interface ParsedFilters {
     statuses: string[] | undefined;
     sinceMs: number | undefined;
     untilMs: number | undefined;
+    origins: string[] | undefined;
+    roles: string[] | undefined;
+    from: string | undefined;
 }
 /** Parse + validate the shared scope/filter flags from a leaf's raw input.
  *  Pure and client-side; the corpus scan itself runs server-side in crtrd. */
 export declare function parseFilters(input: Record<string, unknown>): ParsedFilters;
+/** Copy every parsed filter onto a wire query. search, grep, and stats share
+ *  the whole filter vocabulary, so the mapping lives once. */
+export declare function applyFilters(q: Record<string, unknown>, f: ParsedFilters): void;

package/dist/commands/canvas-history/shared.js

@@ -5,7 +5,12 @@
 // seam. This is internal reuse only: neither leaf's public flag set or output
 // shape is shared, and nothing here is re-exported as a command alias.
 import { usage } from '../../core/errors.js';
-export const TYPES = ['report', 'doc', 'roadmap', 'meta', 'inbox'];
+export const TYPES = ['report', 'doc', 'roadmap', 'meta', 'inbox', 'transcript'];
+export const ORIGINS = [
+    'human', 'inbox', 'wake', 'revive', 'restart-continuation',
+    'stop-guard', 'park', 'recovery', 'context-nudge', 'kickoff', 'unknown',
+];
+export const ROLES = ['user', 'assistant', 'toolResult'];
 export const NODE_KINDS = ['advisor', 'developer', 'spec', 'design', 'review', 'explore', 'plan', 'general'];
 export const STATUSES = ['active', 'idle', 'done', 'dead', 'canceled'];
 const REL_UNITS = {
@@ -47,6 +52,9 @@ export const filterParams = [
     { kind: 'flag', name: 'status', type: 'string', required: false, constraint: `Node lifecycle status; comma-separated for several. One of: ${STATUSES.join(', ')} (e.g. done = completed work only).` },
     { kind: 'flag', name: 'since', type: 'string', required: false, constraint: 'Lower bound on artifact timestamp. ISO 8601 (2026-06-01) or relative (7d, 2w, 1mo).' },
     { kind: 'flag', name: 'until', type: 'string', required: false, constraint: 'Upper bound on artifact timestamp. ISO 8601 or relative.' },
+    { kind: 'flag', name: 'origin', type: 'string', required: false, constraint: `What drove a message to arrive; comma-separated for several. One of: ${ORIGINS.join(', ')}. Applies to transcript + inbox artifacts, which are the only ones that arrive — passing it therefore excludes every generated turn on its own. \`unknown\` is a message carrying no stamp, and is its own bucket rather than a fallback.` },
+    { kind: 'flag', name: 'role', type: 'string', required: false, constraint: `Transcript message role; comma-separated for several. One of: ${ROLES.join(', ')}.` },
+    { kind: 'flag', name: 'from', type: 'string', required: false, constraint: 'Case-insensitive substring against sender attribution — the node that sent a delivery. Applies to transcript + inbox artifacts.' },
 ];
 /** Parse + validate the shared scope/filter flags from a leaf's raw input.
  *  Pure and client-side; the corpus scan itself runs server-side in crtrd. */
@@ -61,6 +69,28 @@ export function parseFilters(input) {
         if (bad !== undefined)
             throw usage(`--type must be one of: ${TYPES.join(', ')}; received: ${bad}`);
     }
+    const origins = splitCsv(input['origin']);
+    if (origins !== undefined) {
+        const bad = origins.find((o) => !ORIGINS.includes(o));
+        if (bad !== undefined)
+            throw usage(`--origin must be one of: ${ORIGINS.join(', ')}; received: ${bad}`);
+    }
+    const roles = splitCsv(input['role']);
+    if (roles !== undefined) {
+        const bad = roles.find((r) => !ROLES.includes(r));
+        if (bad !== undefined)
+            throw usage(`--role must be one of: ${ROLES.join(', ')}; received: ${bad}`);
+    }
+    // Session files are large and there is no persistent index, so the whole
+    // conversation corpus is reachable only through a narrowed scan. The guard
+    // lives in the failure rather than in a permanently visible constraint:
+    // agents who never search transcripts never pay to understand it.
+    if (types !== undefined && types.includes('transcript')) {
+        const narrowed = input['node'] !== undefined || input['under'] !== undefined || input['since'] !== undefined;
+        if (!narrowed) {
+            throw usage('--type transcript needs a narrowing flag: pass --node, --under, or --since.', { next: 'Transcripts are the full conversation corpus — scanning every node in a cwd reads every session file. Narrow first.' });
+        }
+    }
     return {
         cwd,
         allCwds,
@@ -72,5 +102,38 @@ export function parseFilters(input) {
         statuses: splitCsv(input['status']),
         sinceMs: input['since'] !== undefined ? parseWhen('since', input['since']) : undefined,
         untilMs: input['until'] !== undefined ? parseWhen('until', input['until']) : undefined,
+        origins,
+        roles,
+        from: input['from'],
     };
 }
+/** Copy every parsed filter onto a wire query. search, grep, and stats share
+ *  the whole filter vocabulary, so the mapping lives once. */
+export function applyFilters(q, f) {
+    if (f.cwd !== undefined)
+        q['cwd'] = f.cwd;
+    if (f.allCwds)
+        q['all_cwds'] = true;
+    if (f.under !== undefined)
+        q['under'] = f.under;
+    if (f.nodes !== undefined)
+        q['nodes'] = f.nodes;
+    if (f.types !== undefined)
+        q['types'] = f.types;
+    if (f.reportKind !== undefined)
+        q['report_kind'] = f.reportKind;
+    if (f.kinds !== undefined)
+        q['kinds'] = f.kinds;
+    if (f.statuses !== undefined)
+        q['statuses'] = f.statuses;
+    if (f.sinceMs !== undefined)
+        q['since_ms'] = f.sinceMs;
+    if (f.untilMs !== undefined)
+        q['until_ms'] = f.untilMs;
+    if (f.origins !== undefined)
+        q['origins'] = f.origins;
+    if (f.roles !== undefined)
+        q['roles'] = f.roles;
+    if (f.from !== undefined)
+        q['from'] = f.from;
+}

package/dist/commands/canvas-history/stats.d.ts

@@ -0,0 +1 @@
+export declare const statsLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/canvas-history/stats.js

@@ -0,0 +1,68 @@
+// `canvas history stats` — the grouped-count projection over the same corpus
+// search and grep scan. A distinct leaf rather than a flag on search because
+// the output shape differs: counts by one dimension, not a hit list. Grouping
+// by origin is what turns the per-message stamps into a census — "what actually
+// drove work here" — without a second command family.
+import { defineLeaf } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+import { applyFilters, filterParams, parseFilters } from './shared.js';
+const GROUP_KEYS = ['origin', 'node', 'kind', 'day', 'type', 'role'];
+export const statsLeaf = defineLeaf({
+    name: 'stats',
+    description: 'grouped counts over the cwd\'s node history — the projection view',
+    whenToUse: 'you want the SHAPE of the record rather than individual hits — how much of it came from where, who produced it, or when it happened. Group by origin to census what drove agents to run (cron wakes, inbox deliveries, recovery re-drives, people), by node/kind to see who produced the work, by day for volume over time, by type for corpus composition. Takes every scope and filter `canvas history search` takes, so any query you can search you can also count. Want the matching artifacts themselves? Use `canvas history search` or `canvas history grep`.',
+    help: {
+        name: 'canvas history stats',
+        summary: 'counts by one dimension over the per-cwd episodic record — origin census, per-node volume, activity by day',
+        params: [
+            { kind: 'flag', name: 'group-by', type: 'enum', choices: GROUP_KEYS, required: false, default: 'type', constraint: 'The dimension to count by. origin = what drove an inbound message (transcript + inbox only); role = transcript message role; node / kind = who produced it; day = artifact date; type = corpus composition.' },
+            ...filterParams,
+        ],
+        output: [
+            { name: 'group_by', type: 'string', required: true, constraint: 'The dimension counted.' },
+            { name: 'groups', type: 'object[]', required: true, constraint: '{key, count}, descending by count then key.' },
+            { name: 'total', type: 'int', required: true, constraint: 'Artifacts that carried the grouped dimension. Lower than `scanned` when grouping by one not every artifact has (origin, role).' },
+            { name: 'scanned', type: 'int', required: true, constraint: 'Artifacts matched by the filters before grouping.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const by = input['groupBy'] ?? 'type';
+        if (!GROUP_KEYS.includes(by)) {
+            throw usage(`--group-by must be one of: ${GROUP_KEYS.join(', ')}; received: ${by}`);
+        }
+        // Filter validation stays client-side (pure); the corpus scan + grouping
+        // run server-side in crtrd, where canvas.db and the session files live.
+        const f = parseFilters(input);
+        const q = { group_by: by };
+        applyFilters(q, f);
+        try {
+            const res = await cliClient().historyStats(q);
+            return { group_by: res.group_by, groups: res.groups, total: res.total, scanned: res.scanned };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+    render: (r) => {
+        const groups = r['groups'];
+        const by = String(r['group_by']);
+        const total = r['total'];
+        const scanned = r['scanned'];
+        if (groups.length === 0) {
+            return `0 artifacts carried \`${by}\` (${scanned} scanned).`;
+        }
+        const width = Math.max(...groups.map((g) => g.key.length));
+        const max = groups[0].count;
+        const rows = groups
+            .map((g) => {
+            const bar = '█'.repeat(Math.max(1, Math.round((g.count / max) * 24)));
+            return `  ${g.key.padEnd(width)}  ${String(g.count).padStart(6)}  ${bar}`;
+        })
+            .join('\n');
+        const tail = total === scanned ? `${total} artifacts` : `${total} of ${scanned} scanned carried \`${by}\``;
+        return `by ${by}:\n\n${rows}\n\n- ${tail}`;
+    },
+});

package/dist/commands/canvas-history.js

@@ -10,6 +10,7 @@ import { defineBranch } from '../core/command.js';
 import { searchLeaf } from './canvas-history/search.js';
 import { grepLeaf } from './canvas-history/grep.js';
 import { readLeaf } from './canvas-history/read.js';
+import { statsLeaf } from './canvas-history/stats.js';
 /** A tiny per-cwd `<corpus>` marker for branch -h — just enough context to
  *  anchor the help text without scanning nodes or files. Uses only the injected
  *  node cwd env (or the process cwd outside a node), so help stays cheap. */
@@ -19,13 +20,13 @@ function corpusBlock() {
 }
 export const historyBranch = defineBranch({
     name: 'history',
-    description: 'search and recall the cwd-wide content corpus — every node\'s reports and context docs',
+    description: 'search and recall the cwd-wide content corpus — every node\'s reports, context docs, and conversations',
     whenToUse: 'you want to find or re-read what was DONE in a cwd — a past design, a final report, a roadmap, a finding — across every node that ran there, WITHOUT already knowing which node. Use it when picking up prior work ("that caching work from last week"), recovering an artifact, or surveying a project\'s history. Already have the node id and just want everything IT left behind? Use `node inspect artifacts <id>` instead — this branch is the cwd-wide search corpus, not a per-node listing. Distinct from `crtr memory` (curated semantic knowledge, not episodes) and from `canvas dashboard`/`node inspect` (graph topology, not content).',
     help: {
         name: 'canvas history',
         summary: 'search and recall the cwd-wide content corpus — every node\'s reports and context docs in this cwd',
-        model: 'The accumulated record of every node that ran in a cwd and the artifacts it left — its reports (final/update outcome summaries) and context docs (specs, designs, roadmaps, findings). `search` finds by content (ranked, filtered, sorted; omit the query to browse by recency); `grep` finds by an exact ECMAScript regex over body lines (pattern required, one hit per matching line — use this over `search` when you know the literal string/pattern, not just the topic); `read` pulls one hit\'s full body by its <node-id>:<relpath> ref. This is the episodic record of what was DONE — distinct from `crtr memory`, which is curated semantic knowledge. Already have a node id and want everything IT left behind (not a cwd-wide search)? Use `node inspect artifacts <node-id>` instead — that single-node listing moved out of this branch. A node\'s raw inbox history (`--type inbox`) is a separate, opt-in diagnostic corpus — the full cursor-independent inbox.jsonl for one node, including un-clipped direct-message bodies; reach for it only when the curated reports/docs above don\'t already answer the question. To reopen a node you found, use `node lifecycle revive`; for its place in the graph, `node inspect show`.',
+        model: 'The accumulated record of every node that ran in a cwd and the artifacts it left — its reports (final/update outcome summaries), context docs (specs, designs, roadmaps, findings), and the conversations themselves. `search` finds by content (ranked, filtered, sorted; omit the query to browse by recency); `grep` finds by an exact ECMAScript regex over body lines (pattern required, one hit per matching line — use this over `search` when you know the literal string/pattern, not just the topic); `read` pulls one hit\'s full body by its <node-id>:<relpath> ref, `--format raw` for the verbatim bytes; `stats` counts the same filtered corpus by one dimension instead of listing hits. Corpus is a DIMENSION here, not a location: `--type` selects which record you search, and every leaf takes the same scope and filters. This is the episodic record of what was DONE — distinct from `crtr memory`, which is curated semantic knowledge. Already have a node id and want everything IT left behind (not a cwd-wide search)? Use `node inspect artifacts <node-id>` instead. Two corpora are opt-in diagnostics rather than curated work: `--type inbox` is one node\'s full cursor-independent inbox.jsonl including un-clipped message bodies, and `--type transcript` is the conversation itself, message by message, each inbound turn carrying the origin that drove it (`--origin`, `--role`, `--from`, and `stats --group-by origin` for the census). Transcripts require a narrowing flag because there is no index. To reopen a node you found, use `node lifecycle revive`; for its place in the graph, `node inspect show`.',
         dynamicState: corpusBlock,
     },
-    children: [searchLeaf, grepLeaf, readLeaf],
+    children: [searchLeaf, grepLeaf, readLeaf, statsLeaf],
 });

package/dist/commands/node/create.js

@@ -94,8 +94,8 @@ function nodeNewParams() {
                 whenToUse: 'Use only when the user, task, or governing agent guidance already requires a specific provider, model, capability tier, or family. Omit it for routine delegation: the selected persona kind and profile own normal model selection, and review personas may enforce a quality floor.',
                 value: `Accepted forms: ${MODEL_SPEC_FORMS}. Concrete provider/id requests must be registered. Portable provider/tier, bare-tier, and family-alias requests resolve through the configured model ladders.`,
                 effects: [
-                    'The resolved override is stored on the node and in its launch recipe, so future revives preserve it.',
-                    'A concrete provider/id pins that provider. Portable tiers and aliases preserve logical intent for runtime routing; a persona quality floor may raise a weaker request.',
+                    'The resolved concrete override is stored on the node and in its launch recipe, so every launch and revive uses that exact provider/model.',
+                    'Portable tiers and aliases resolve through the configured ladders; a persona quality floor may raise a weaker request before its resolved model is stored.',
                 ],
             },
         },

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/config.js

@@ -39,6 +39,11 @@ function assertUserScopeBrokerThresholds(key, scope) {
         throw usage('brokerThresholds are available only in user scope');
     }
 }
+function assertUserScopeLifecycle(key, scope) {
+    if (key.split('.', 1)[0] === 'lifecycle' && scope !== 'user') {
+        throw usage('lifecycle settings are available only in user scope');
+    }
+}
 function assertWorkingGerundsScope(key, scope) {
     if (key === 'working_gerunds' && scope !== 'user') {
         throw usage('working_gerunds is available only in user scope');
@@ -132,6 +137,16 @@ function setNestedValue(cfg, key, rawValue, value) {
         cfg.brokerThresholds[parts[1]] = threshold;
         return;
     }
+    if (topKey === 'lifecycle') {
+        if (parts.length !== 2 || parts[1] !== 'unattendedParkMs') {
+            throw usage(`lifecycle key must be unattendedParkMs`);
+        }
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < 1) {
+            throw usage(`lifecycle.unattendedParkMs must be an integer >= 1`);
+        }
+        cfg.lifecycle.unattendedParkMs = Math.floor(value);
+        return;
+    }
     throw usage(`unsupported key path for set: ${key}`);
 }
 // Leaf definitions
@@ -143,7 +158,7 @@ const configGet = defineLeaf({
         name: 'sys config get',
         summary: 'read a config value by dotted key',
         params: [
-            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: `Dotted key path. Top-level keys: ${CONFIG_TOP_LEVEL_HELP}. brokerThresholds is user-only; keybindings is readable only as the whole user-scope object and editable only through sys settings.` },
+            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: `Dotted key path. Top-level keys: ${CONFIG_TOP_LEVEL_HELP}. brokerThresholds and lifecycle are user-only; keybindings is readable only as the whole user-scope object and editable only through sys settings.` },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Scope to read from. Default: user.' },
         ],
         output: [
@@ -158,6 +173,7 @@ const configGet = defineLeaf({
         const key = input['key'];
         const scope = resolveScope(input['scope']);
         assertUserScopeBrokerThresholds(key, scope);
+        assertUserScopeLifecycle(key, scope);
         if (key.startsWith('keybindings.') || (key === 'keybindings' && scope !== 'user')) {
             throw notFound('keybindings are available only as the whole user-scope object');
         }
@@ -177,7 +193,7 @@ const configSet = defineLeaf({
         name: 'sys config set',
         summary: 'write a config value by dotted key',
         params: [
-            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: `Dotted key path. User-scope scalar settings: ${SCALAR_SETTING_HELP}. Also supported: working_gerunds and whip_messages (non-empty JSON string arrays), brokerThresholds.warning and brokerThresholds.automaticReviveCap (user scope; integer >= 1), modelLadders.defaultProvider, and modelLadders.<anthropic|openai>.<ultra|strong|medium|light>. Keybindings are edited only through sys settings. humanActions is an object map edited directly in ~/.crouter/config.json or <repo>/.crouter/config.json.` },
+            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: `Dotted key path. User-scope scalar settings: ${SCALAR_SETTING_HELP}. Also supported: working_gerunds and whip_messages (non-empty JSON string arrays), brokerThresholds.warning and brokerThresholds.automaticReviveCap (user scope; integer >= 1), lifecycle.unattendedParkMs (user scope; integer ms >= 1), modelLadders.defaultProvider, and modelLadders.<anthropic|openai>.<ultra|strong|medium|light>. Keybindings are edited only through sys settings. humanActions is an object map edited directly in ~/.crouter/config.json or <repo>/.crouter/config.json.` },
             { kind: 'flag', name: 'value', type: 'string', required: true, constraint: 'value VALUE — string, required. working_gerunds and whip_messages accept JSON arrays; other values are stored as-is if quoted and coerced to number or boolean when unambiguous.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Scope to write to. Default: user. Project scope is supported only for modelLadders.' },
         ],
@@ -193,6 +209,7 @@ const configSet = defineLeaf({
         const rawValue = input['value'];
         const scope = resolveScope(input['scope']);
         assertUserScopeBrokerThresholds(key, scope);
+        assertUserScopeLifecycle(key, scope);
         assertWorkingGerundsScope(key, scope);
         assertWhipMessagesScope(key, scope);
         assertUserSettingScope(key, scope);

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/commands/sys/panels/models-panel.js

@@ -961,7 +961,9 @@ export class ModelsPanel {
         const contentBudget = Math.max(1, height);
         const frame = (lines) => renderRows(lines, width);
         if (this.mode === "dimension-picker")
-            return frame(fitTail(this.renderChoicePicker(), contentBudget));
+            // Provider ids run to dozens of options, so the picker windows on its
+            // selection like the list does — a tail cut would scroll the cursor off.
+            return frame(this.fitBody(this.renderChoicePicker(), MODELS_CHROME_LINES + this.choiceIndex, contentBudget));
         if (this.mode === "model-picker")
             return frame(fitTail(this.modelSelector?.render(width) ?? [], contentBudget));
         if (this.mode === "thinking-picker")

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