@north-light/crouter 0.3.198 → 0.3.200

package/dist/core/canvas/canvas.js

@@ -336,6 +336,21 @@ export function migrateLegacyPidIdentities(captureIdentity = (pid) => capturePid
  *  yet — surfacing it would put a phantom empty conversation in the user's
  *  sidebar. Claiming deletes the marker, which is what makes the node visible. */
 const NOT_A_SPARE = 'node_id NOT IN (SELECT node_id FROM warm_pool)';
+/** Every hydrated node whose durable profile identity equals `profileId`.
+ *  Unlike `listNodes`, this includes unclaimed warm-pool spares: profile
+ *  deletion owns every matching row, whether or not it is user-visible. */
+export function listNodesByProfile(profileId) {
+    const ids = openDb()
+        .prepare('SELECT node_id FROM nodes WHERE profile_id = ? ORDER BY created')
+        .all(profileId);
+    return ids.map(({ node_id }) => {
+        const meta = getNode(node_id);
+        if (meta === null) {
+            throw new Error(`profile deletion cannot hydrate indexed node ${node_id}`);
+        }
+        return meta;
+    });
+}
 /** All rows, optionally filtered by status. Unclaimed warm spares are excluded. */
 export function listNodes(filter) {
     const db = openDb();
@@ -744,6 +759,28 @@ export function deleteNode(nodeId) {
     rmSync(nodeDir(nodeId), { recursive: true, force: true });
     return result;
 }
+/** Hard-delete a validated set of nodes in one row transaction, then remove
+ *  their directories. The caller must tear down engines and viewers first. */
+export function deleteNodes(nodeIds) {
+    const ids = [...new Set(nodeIds)];
+    if (ids.length === 0)
+        return [];
+    const blocked = ids.filter(hasOpenManagedWorktree);
+    if (blocked.length > 0) {
+        throw new Error(`refusing to delete nodes with open managed worktrees: ${blocked.join(', ')}`);
+    }
+    const placeholders = ids.map(() => '?').join(',');
+    const deleted = withCanvasWrite((db) => {
+        const existing = db
+            .prepare(`SELECT node_id FROM nodes WHERE node_id IN (${placeholders}) ORDER BY created`)
+            .all(...ids).map(({ node_id }) => node_id);
+        db.prepare(`DELETE FROM nodes WHERE node_id IN (${placeholders})`).run(...ids);
+        return existing;
+    });
+    for (const id of deleted)
+        rmSync(nodeDir(id), { recursive: true, force: true });
+    return deleted;
+}
 /** Retention sweep: remove TERMINAL nodes (status dead | done | canceled) whose
  *  `created` is older than `ttlDays`, bounding the otherwise-unbounded growth of
  *  node rows + dirs. Open managed-worktree nodes are retained so their checkout

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

@@ -159,6 +159,15 @@ export declare function listCrons(scope: {
 export declare function cancelCron(cron_id: string, options?: {
     preserveRunningProcess?: boolean;
 }): boolean;
+/** Cron ids a hard profile deletion will remove: matching execution profile,
+ *  plus every row anchored to a node being deleted. */
+export declare function cronIdsForProfileDeletion(profileId: string, anchorNodeIds: readonly string[]): string[];
+/** Kill any leased matching/anchored runs, then delete their rows together. */
+export declare function deleteCronsForProfile(profileId: string, anchorNodeIds: readonly string[]): string[];
+/** Cron ids whose snapshotted profile will be detached. */
+export declare function cronIdsForProfileDetach(profileId: string): string[];
+/** Preserve matching crons while removing their deleted profile dependency. */
+export declare function globalizeCronsForProfile(profileId: string): string[];
 /** DELETE one cron by id — one-shot consumption after its run settles.
  *  Returns whether a live row was removed, so a consumer racing an explicit
  *  cancel can no-op instead of double-settling. */

package/dist/core/canvas/crons.js

@@ -191,6 +191,57 @@ export function cancelCron(cron_id, options) {
         return true;
     });
 }
+function profileCronWhere(profileId, anchorNodeIds) {
+    const anchors = [...new Set(anchorNodeIds)];
+    if (anchors.length === 0)
+        return { sql: 'profile = ?', params: [profileId] };
+    return {
+        sql: `profile = ? OR anchor_node IN (${anchors.map(() => '?').join(',')})`,
+        params: [profileId, ...anchors],
+    };
+}
+/** Cron ids a hard profile deletion will remove: matching execution profile,
+ *  plus every row anchored to a node being deleted. */
+export function cronIdsForProfileDeletion(profileId, anchorNodeIds) {
+    const where = profileCronWhere(profileId, anchorNodeIds);
+    return openDb()
+        .prepare(`SELECT cron_id FROM crons WHERE ${where.sql} ORDER BY created, cron_id`)
+        .all(...where.params).map(({ cron_id }) => cron_id);
+}
+/** Kill any leased matching/anchored runs, then delete their rows together. */
+export function deleteCronsForProfile(profileId, anchorNodeIds) {
+    return withCanvasWrite((db) => {
+        const where = profileCronWhere(profileId, anchorNodeIds);
+        const rows = db
+            .prepare(`SELECT * FROM crons WHERE ${where.sql} ORDER BY created, cron_id`)
+            .all(...where.params).map(cronFrom);
+        for (const cron of rows) {
+            if (cron.run_state === 'running')
+                killLeasedCronRun(cron);
+        }
+        db.prepare(`DELETE FROM crons WHERE ${where.sql}`).run(...where.params);
+        return rows.map(({ cron_id }) => cron_id);
+    });
+}
+/** Cron ids whose snapshotted profile will be detached. */
+export function cronIdsForProfileDetach(profileId) {
+    return openDb()
+        .prepare('SELECT cron_id FROM crons WHERE profile = ? ORDER BY created, cron_id')
+        .all(profileId).map(({ cron_id }) => cron_id);
+}
+/** Preserve matching crons while removing their deleted profile dependency. */
+export function globalizeCronsForProfile(profileId) {
+    return withCanvasWrite((db) => {
+        const ids = db
+            .prepare('SELECT cron_id FROM crons WHERE profile = ? ORDER BY created, cron_id')
+            .all(profileId).map(({ cron_id }) => cron_id);
+        if (ids.length > 0) {
+            db.prepare("UPDATE crons SET profile = NULL, scope = 'global', updated = ? WHERE profile = ?")
+                .run(new Date().toISOString(), profileId);
+        }
+        return ids;
+    });
+}
 /** DELETE one cron by id — one-shot consumption after its run settles.
  *  Returns whether a live row was removed, so a consumer racing an explicit
  *  cancel can no-op instead of double-settling. */

package/dist/core/canvas/node-order.d.ts

@@ -1,3 +1,24 @@
-import type { NodeStatus } from './types.js';
+import type { NodeStatus, Lifecycle } from './types.js';
 /** Sort live work before terminal work; unknown statuses sort last. */
 export declare function statusRank(status: NodeStatus | undefined): number;
+/** True when the node has a broker the daemon supervises — the statuses that
+ *  mean "a live engine is (or should be) running right now". */
+export declare function isLiveStatus(status: NodeStatus | undefined): boolean;
+/** True when a node's work is FINISHED — a terminal one-shot worker, or any node
+ *  that pushed a final report.
+ *
+ *  This is deliberately NOT "is it running": a non-live status alone conflates two
+ *  unrelated situations. Finished work is archive — opening it is inspection, and
+ *  relaunching it puts a completed worker back to work (the stop-guard reprompts a
+ *  terminal node that never pushed a final). A RESIDENT node with no final report
+ *  is the opposite: its `done` is only `markCleanExitDone` recording a clean broker
+ *  exit, which the stop-guard itself rules a legitimate stop (`reason: 'dormant'`),
+ *  so it never finished anything and resuming it is simply reopening a conversation.
+ *
+ *  `lifecycle` is optional because DashboardRow only carries it on the full browser
+ *  snapshot; absent, this answers `true` (treat as finished), keeping the caller on
+ *  the conservative inspect-don't-revive path. */
+export declare function isFinishedWork(node: {
+    lifecycle?: Lifecycle;
+    finalized: boolean;
+}): boolean;

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

@@ -1,4 +1,7 @@
-// node-order.ts — canonical live-first ordering for canvas node statuses.
+// node-order.ts — canonical ordering and status/lifecycle classification for
+// canvas nodes. Pure (type-only imports) so every surface — the browser model,
+// command leaves, renderers — can share one answer to "is this node live?" and
+// "did this node finish?" without reaching the db.
 /** Sort live work before terminal work; unknown statuses sort last. */
 export function statusRank(status) {
     switch (status) {
@@ -10,3 +13,25 @@ export function statusRank(status) {
         default: return 5;
     }
 }
+/** True when the node has a broker the daemon supervises — the statuses that
+ *  mean "a live engine is (or should be) running right now". */
+export function isLiveStatus(status) {
+    return status === 'active' || status === 'idle';
+}
+/** True when a node's work is FINISHED — a terminal one-shot worker, or any node
+ *  that pushed a final report.
+ *
+ *  This is deliberately NOT "is it running": a non-live status alone conflates two
+ *  unrelated situations. Finished work is archive — opening it is inspection, and
+ *  relaunching it puts a completed worker back to work (the stop-guard reprompts a
+ *  terminal node that never pushed a final). A RESIDENT node with no final report
+ *  is the opposite: its `done` is only `markCleanExitDone` recording a clean broker
+ *  exit, which the stop-guard itself rules a legitimate stop (`reason: 'dormant'`),
+ *  so it never finished anything and resuming it is simply reopening a conversation.
+ *
+ *  `lifecycle` is optional because DashboardRow only carries it on the full browser
+ *  snapshot; absent, this answers `true` (treat as finished), keeping the caller on
+ *  the conservative inspect-don't-revive path. */
+export function isFinishedWork(node) {
+    return node.lifecycle !== 'resident' || node.finalized;
+}

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

@@ -34,6 +34,11 @@ export interface DashboardRow {
      *  agent you come back to. Drives the browser's resident-only lifecycle filter.
      *  Only populated by dashboardRowsAll (the browser snapshot). */
     lifecycle?: Lifecycle;
+    /** True when the node pushed a final report. With `lifecycle` this separates
+     *  work that FINISHED from a resident agent that merely stopped, which the
+     *  status alone cannot (see `isFinishedWork` in node-order.ts). Only populated
+     *  by dashboardRowsAll (the browser snapshot). */
+    finalized?: boolean;
     /** "Most recent activity" sort key — epoch ms. The cheap boot stats the node's
      *  job/telemetry.json (rewritten on every turn_end at a DETERMINISTIC path, so
      *  no meta read), falling back to `created`'s epoch when a node never ran a turn.

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

@@ -372,6 +372,7 @@ export function dashboardRowFromNodeRow(row, focusedNodeIds, remote) {
         profile_id: row.profile_id,
         created: row.created,
         lifecycle: row.lifecycle,
+        finalized: row.final_report != null,
         mtimeMs: sessionMtime(row.node_id, row.created, remote),
         streaming: !remote && hanging === null && live ? isStreaming(row.node_id, row.pi_pid) : false,
         hanging,

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

@@ -49,6 +49,9 @@ export interface LaunchSpec {
 }
 export interface ManagedWorktree {
     state: 'open' | 'closed';
+    /** A closed worktree remains registered until its owner has exited, so Git
+     *  never deletes the caller's live checkout beneath it. */
+    cleanup?: 'pending' | 'complete';
     path: string;
     branch: string;
     repo_root: string;
@@ -57,10 +60,13 @@ export interface ManagedWorktree {
     created: string;
     closed?: string;
 }
-/** Immutable review-companion provenance. The origin session/leaf/model
- *  coordinates remain canonical in the review row rather than being duplicated
- *  into node metadata. */
+/** Immutable companion provenance. The origin session/leaf/model coordinates
+ *  remain canonical in the review row rather than being duplicated into node
+ *  metadata. `kind` names the surface the companion serves: absent or `review`
+ *  is a human document review; `page_feedback` binds a page ticket's feedback
+ *  conversation, with review_id = ticket id and target_file = the page source. */
 export interface ReviewBinding {
+    kind?: 'review' | 'page_feedback';
     review_id: string;
     origin_node_id: string;
     branch_file: string;

package/dist/core/command-plugins/bundle.d.ts

@@ -1,5 +1,5 @@
 import { type ValidatedCommandManifest } from '../command-manifests/manifest.js';
-import type { KindConfig } from '../../types.js';
+import type { KindConfig, PageComponentRegistration } from '../../types.js';
 export interface BundleIssue {
     code: string;
     path?: string;
@@ -15,6 +15,11 @@ export interface ValidatedBundle {
      *  manifest, where `readMergedLaunchConfig` layers it — see
      *  `PluginManifest.kinds`. */
     kinds?: Record<string, Partial<KindConfig>>;
+    /** Page-component contributions declared in `bundle.json` (optional). The
+     *  installer copies this validated block into the synthesized plugin
+     *  manifest, where `resolvePageComponents` reads it — see
+     *  `PluginManifest.page_components`. */
+    page_components?: PageComponentRegistration[];
     commands: ValidatedCommandManifest;
     commandsBytes: Uint8Array;
     directories: ReadonlyArray<{

package/dist/core/command-plugins/bundle.js

@@ -1,6 +1,7 @@
 import { Parser } from 'tar';
 import { validateCommandManifest } from '../command-manifests/manifest.js';
 import { invalidPluginKindsReasons } from '../config.js';
+import { invalidPageComponentsReasons, normalizePageComponents } from '../human/page-catalog.js';
 function issue(code, message, received, expected, next, path) {
     return { code, message, received, expected, next, ...(path !== undefined ? { path } : {}) };
 }
@@ -143,24 +144,35 @@ function parseBundleMetadata(bytes) {
         };
     }
     const record = raw;
-    const unknownKeys = Object.keys(record).filter((key) => key !== 'bundleVersion' && key !== 'kinds');
+    const unknownKeys = Object.keys(record).filter((key) => key !== 'bundleVersion' && key !== 'kinds' && key !== 'page_components');
     if (record['bundleVersion'] !== 1 || unknownKeys.length > 0) {
         return {
-            issue: bundleInvalid('bundle.json must contain bundleVersion 1 and at most a kinds block', JSON.stringify(raw), 'an object with bundleVersion set to 1 and optionally kinds', 'Set bundle.json to {"bundleVersion":1} plus an optional kinds object.', 'bundle.json'),
+            issue: bundleInvalid('bundle.json must contain bundleVersion 1 and at most kinds and page_components blocks', JSON.stringify(raw), 'an object with bundleVersion set to 1 and optionally kinds and page_components', 'Set bundle.json to {"bundleVersion":1} plus an optional kinds object and page_components array.', 'bundle.json'),
         };
     }
-    if (record['kinds'] === undefined)
-        return {};
-    // Install-time strictness: a bad kinds block fails the install loudly here,
-    // because the read side (`mergeKinds`) drops invalid entries silently and
-    // would otherwise ship a kind that never registers.
-    const reasons = invalidPluginKindsReasons(record['kinds']);
-    if (reasons.length > 0) {
-        return {
-            issue: bundleInvalid('bundle.json kinds block is invalid', reasons.join('; '), 'each entry a full KindConfig (whenToUse required) or a sparse patch of launch fields', 'Fix the kinds entries in bundle.json.', 'bundle.json'),
-        };
+    // Install-time strictness: a bad block fails the install loudly here, because
+    // the read side (`mergeKinds`) drops invalid kind entries silently and would
+    // otherwise ship a kind that never registers.
+    if (record['kinds'] !== undefined) {
+        const reasons = invalidPluginKindsReasons(record['kinds']);
+        if (reasons.length > 0) {
+            return {
+                issue: bundleInvalid('bundle.json kinds block is invalid', reasons.join('; '), 'each entry a full KindConfig (whenToUse required) or a sparse patch of launch fields', 'Fix the kinds entries in bundle.json.', 'bundle.json'),
+            };
+        }
     }
-    return { kinds: record['kinds'] };
+    if (record['page_components'] !== undefined) {
+        const reasons = invalidPageComponentsReasons(record['page_components']);
+        if (reasons.length > 0) {
+            return {
+                issue: bundleInvalid('bundle.json page_components block is invalid', reasons.join('; '), 'an array of page component registrations, each a kind string or {kind, description?, useWhen?, doc?, display?}', 'Fix the page_components entries in bundle.json.', 'bundle.json'),
+            };
+        }
+    }
+    return {
+        ...(record['kinds'] !== undefined ? { kinds: record['kinds'] } : {}),
+        ...(record['page_components'] !== undefined ? { page_components: normalizePageComponents(record['page_components']) } : {}),
+    };
 }
 function parseCommands(bytes, reservedCoreNames, coreCommandPaths) {
     let raw;
@@ -206,6 +218,7 @@ export async function validatePluginBundle(archive, options) {
         bundle: {
             bundleVersion: 1,
             ...(metadata.kinds !== undefined ? { kinds: metadata.kinds } : {}),
+            ...(metadata.page_components !== undefined ? { page_components: metadata.page_components } : {}),
             commands: commandValidation.commands,
             commandsBytes: commands.bytes,
             directories: parsed.members

package/dist/core/command.js

@@ -542,7 +542,8 @@ export async function parseArgv(params, tokens, options) {
     const missing = [];
     for (const p of params) {
         const key = flagNameToKey(p.name);
-        if (p.required && (result[key] === undefined || result[key] === null)) {
+        const missingRequiredBool = p.kind === 'flag' && p.type === 'bool' && !provided.has(key);
+        if (p.required && (missingRequiredBool || result[key] === undefined || result[key] === null)) {
             const display = p.kind === 'positional'
                 ? `positional ${p.name.toUpperCase()}`
                 : p.kind === 'flag'

package/dist/core/config.d.ts

@@ -1,4 +1,4 @@
-import type { Scope, ScopeConfig, ScopeState, KindConfig, ModelLaddersConfig, ModelProvider, ModelStrength, ModelRouteConfig, ModelRoutingConfig } from '../types.js';
+import type { PageComponentRegistration, Scope, ScopeConfig, ScopeState, KindConfig, ModelLaddersConfig, ModelProvider, ModelStrength, ModelRouteConfig, ModelRoutingConfig } from '../types.js';
 import { type BindingId } from './keybindings/catalog.js';
 export declare function configPath(scope: Scope): string | null;
 export declare function statePath(scope: Scope): string | null;
@@ -26,6 +26,52 @@ export declare function ensureScopeInitialized(scope: Scope, root: string): void
 /** Normalize the user-owned list of attach actions allowed to bridge through an
  * occupied tmux root binding. Unknown and non-attach ids have no effect. */
 export declare function normalizeTmuxPassthrough(raw: unknown): BindingId[];
+/** One malformed `bin` declaration. The read path retains these as doctor
+ *  findings rather than letting malformed config break a node launch. */
+export interface BinDeclarationIssue {
+    name: string;
+    message: string;
+}
+/** Validate raw `bin` declaration shape without touching the filesystem.
+ *  Install uses these findings as a hard gate for plugin manifests; scope
+ *  resolution reports them through `crtr sys doctor` and continues. */
+export declare function binDeclarationIssues(raw: unknown): BinDeclarationIssue[];
+/** Normalize one raw `bin` block (a scope `config.json`'s or a plugin
+ *  manifest's) to name → root-relative path. Invalid entries never become
+ *  commands; `binDeclarationIssues` keeps them visible to Doctor. */
+export declare function normalizeBin(raw: unknown): Record<string, string>;
+/** STRICT install-time validation for a plugin-declared `bin` block. Target
+ *  filesystem state is checked later by Doctor because it can change after
+ *  install. */
+export declare function invalidPluginBinReasons(raw: unknown): string[];
+/** Normalize a plugin manifest's advisory executable requirements. Invalid
+ *  declarations stay out of the read path; source installs reject them through
+ *  `invalidPluginRequiresReasons`. */
+export declare function normalizeRequires(raw: unknown): Record<string, string>;
+/** STRICT install-time validation for a plugin's advisory `requires` block.
+ *  A missing executable is advisory; only malformed declarations fail install. */
+export declare function invalidPluginRequiresReasons(raw: unknown): string[];
+/** The ACTIVE page-component catalog every authoring, validation, daemon,
+ *  inbox, and TUI consumer resolves: the user scope's own `page_components`
+ *  entries plus the contributions of every ENABLED plugin installed under that
+ *  same root, plugin name-sorted for determinism (directory listing order is
+ *  filesystem-dependent). Installing, updating, or removing a plugin therefore
+ *  adds, changes, or retires its components with no config edit.
+ *
+ *  User scope only, deliberately: this catalog is read from the daemon, the
+ *  CLI, and the inbox TUI, whose ambient cwds differ, and a page slot whose
+ *  validity depended on which directory a process happened to start in would
+ *  validate in one surface and fail in another. `page_components` has always
+ *  been a user-scope block (`readConfig('user')`); its plugin channel keeps
+ *  that boundary.
+ *
+ *  Throws on a duplicate kind or derived JSX tag across sources, and on a
+ *  plugin whose block is malformed — matching the existing catalog validation
+ *  style, where a bad `page_components` block already fails config read rather
+ *  than silently dropping a component the product expects to be authorable.
+ *  Install-time validation (`invalidPageComponentsReasons`) is what keeps a
+ *  malformed block from ever reaching this path. */
+export declare function resolvePageComponents(): PageComponentRegistration[];
 /** STRICT install-time validation for a plugin-declared `kinds` block —
  *  the loud counterpart to `mergeKinds`'s silent read-time dropping. Read
  *  paths must never throw on bad config, but an INSTALL delivering a bad

package/dist/core/config.js

@@ -1,6 +1,6 @@
 import { dirname, join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
-import { CONFIG_FILE, STATE_FILE, CONDENSED_HISTORY_MODES, MOUSE_MODE_DEFAULTS, DEFAULT_WHIP_MESSAGES, defaultScopeConfig, defaultScopeState, defaultModelLaddersConfig, defaultKindsConfig, defaultRemoteCanvasConfig } from '../types.js';
+import { CONFIG_FILE, STATE_FILE, CONDENSED_HISTORY_MODES, MOUSE_MODE_DEFAULTS, WHIP_MESSAGE_MODES, DEFAULT_WHIP_MESSAGES, defaultScopeConfig, defaultScopeState, defaultModelLaddersConfig, defaultKindsConfig, defaultRemoteCanvasConfig } from '../types.js';
 import { BINDING_CATALOG, BINDING_IDS, isAttachPaneBinding } from './keybindings/catalog.js';
 import { emitEvent } from './events/emit.js';
 import { atomicWriteJson, readJsonIfExists, writeJson, ensureDir } from './fs-utils.js';
@@ -10,7 +10,7 @@ import { profileRoot } from './profiles/manifest.js';
 import { withExclusiveDirectoryLock } from './exclusive-lock.js';
 import { SCOPE_CONFIG_KEYS } from './user-settings.js';
 import { normalizeWorkingGerunds } from '../shared/working-activity.js';
-import { normalizePageComponents } from './human/page-catalog.js';
+import { mergePageComponentLayers, normalizePageComponents } from './human/page-catalog.js';
 function configPathFor(root) {
     return join(root, CONFIG_FILE);
 }
@@ -266,6 +266,101 @@ function mergeSpawnEnv(raw, base = []) {
     }
     return { allow: [...new Set([...base, ...extra])] };
 }
+/** The one bare-command-name rule, shared by the read path (`normalizeBin`)
+ *  and the strict install gate (`invalidPluginBinReasons`): a name a shell can
+ *  invoke verbatim and a filesystem can hold as a single symlink entry — no
+ *  separator, no leading dot, no whitespace, no quoting ever required. */
+const BIN_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** Bare names crouter owns on every node's PATH. A contribution may not take
+ *  one: shadowing the CLI a node drives its own canvas with breaks the runtime
+ *  contract rather than extending it. */
+const RESERVED_BIN_NAMES = new Set(['crtr', 'crtrd']);
+/** The one bare-command-name validator shared by `bin` and plugin `requires`.
+ *  `bin` alone reserves crouter's own commands; a plugin may require any safe
+ *  executable name because it does not contribute or shadow that command. */
+function bareCommandNameIssue(name, field) {
+    if (field === 'bin' && RESERVED_BIN_NAMES.has(name))
+        return `${field}.${name} is reserved by crouter — pick another bare command name`;
+    if (!BIN_NAME_PATTERN.test(name))
+        return `${field}.${name} is not a safe bare command name (expected ${BIN_NAME_PATTERN.source})`;
+    return undefined;
+}
+/** Validate raw `bin` declaration shape without touching the filesystem.
+ *  Install uses these findings as a hard gate for plugin manifests; scope
+ *  resolution reports them through `crtr sys doctor` and continues. */
+export function binDeclarationIssues(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return [{ name: 'bin', message: 'bin must be a JSON object mapping bare command name to a relative path' }];
+    }
+    const issues = [];
+    for (const [name, target] of Object.entries(raw)) {
+        const nameIssue = bareCommandNameIssue(name, 'bin');
+        if (nameIssue !== undefined)
+            issues.push({ name, message: nameIssue });
+        if (typeof target !== 'string' || target.trim() === '') {
+            issues.push({ name, message: `bin.${name} must be a non-empty relative path to an executable inside the contributor root` });
+        }
+    }
+    return issues;
+}
+/** Normalize one raw `bin` block (a scope `config.json`'s or a plugin
+ *  manifest's) to name → root-relative path. Invalid entries never become
+ *  commands; `binDeclarationIssues` keeps them visible to Doctor. */
+export function normalizeBin(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [name, target] of Object.entries(raw)) {
+        if (bareCommandNameIssue(name, 'bin') !== undefined)
+            continue;
+        if (typeof target !== 'string' || target.trim() === '')
+            continue;
+        out[name] = target;
+    }
+    return out;
+}
+/** STRICT install-time validation for a plugin-declared `bin` block. Target
+ *  filesystem state is checked later by Doctor because it can change after
+ *  install. */
+export function invalidPluginBinReasons(raw) {
+    return binDeclarationIssues(raw).map((issue) => issue.message);
+}
+/** Normalize a plugin manifest's advisory executable requirements. Invalid
+ *  declarations stay out of the read path; source installs reject them through
+ *  `invalidPluginRequiresReasons`. */
+export function normalizeRequires(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [name, hint] of Object.entries(raw)) {
+        if (bareCommandNameIssue(name, 'requires') !== undefined)
+            continue;
+        if (typeof hint !== 'string' || hint.trim() === '' || /[\r\n]/.test(hint))
+            continue;
+        out[name] = hint;
+    }
+    return out;
+}
+/** STRICT install-time validation for a plugin's advisory `requires` block.
+ *  A missing executable is advisory; only malformed declarations fail install. */
+export function invalidPluginRequiresReasons(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return ['requires must be a JSON object mapping a bare executable name to a one-line install hint'];
+    }
+    const reasons = [];
+    for (const [name, hint] of Object.entries(raw)) {
+        const nameIssue = bareCommandNameIssue(name, 'requires');
+        if (nameIssue !== undefined)
+            reasons.push(nameIssue);
+        if (typeof hint !== 'string' || hint.trim() === '') {
+            reasons.push(`requires.${name} must be a non-empty one-line install hint`);
+        }
+        else if (/[\r\n]/.test(hint)) {
+            reasons.push(`requires.${name} must be a one-line install hint`);
+        }
+    }
+    return reasons;
+}
 /** Collect the valid `KindConfig` fields of one raw `kinds.<name>` entry —
  *  every field is optional here, `whenToUse` included; mistyped fields are
  *  dropped, never thrown (an invalid field in config.json must not break
@@ -341,6 +436,40 @@ function layerPluginKinds(scope, scopeRootPath, base) {
         out = mergeKinds(plugin.manifest.kinds, out);
     return out;
 }
+/** The ACTIVE page-component catalog every authoring, validation, daemon,
+ *  inbox, and TUI consumer resolves: the user scope's own `page_components`
+ *  entries plus the contributions of every ENABLED plugin installed under that
+ *  same root, plugin name-sorted for determinism (directory listing order is
+ *  filesystem-dependent). Installing, updating, or removing a plugin therefore
+ *  adds, changes, or retires its components with no config edit.
+ *
+ *  User scope only, deliberately: this catalog is read from the daemon, the
+ *  CLI, and the inbox TUI, whose ambient cwds differ, and a page slot whose
+ *  validity depended on which directory a process happened to start in would
+ *  validate in one surface and fail in another. `page_components` has always
+ *  been a user-scope block (`readConfig('user')`); its plugin channel keeps
+ *  that boundary.
+ *
+ *  Throws on a duplicate kind or derived JSX tag across sources, and on a
+ *  plugin whose block is malformed — matching the existing catalog validation
+ *  style, where a bad `page_components` block already fails config read rather
+ *  than silently dropping a component the product expects to be authorable.
+ *  Install-time validation (`invalidPageComponentsReasons`) is what keeps a
+ *  malformed block from ever reaching this path. */
+export function resolvePageComponents() {
+    const layers = [{ origin: 'config.json', components: readConfig('user').page_components }];
+    const root = scopeRoot('user');
+    if (root !== null) {
+        const plugins = listInstalledPluginsInRoot('user', root)
+            .filter((plugin) => plugin.enabled && plugin.manifest.page_components !== undefined)
+            .sort((a, b) => a.name.localeCompare(b.name));
+        for (const plugin of plugins) {
+            const label = `plugin "${plugin.name}" page_components`;
+            layers.push({ origin: `plugin "${plugin.name}"`, components: normalizePageComponents(plugin.manifest.page_components, label) });
+        }
+    }
+    return mergePageComponentLayers(layers);
+}
 const KIND_CONFIG_KEYS = new Set(['whenToUse', 'model', 'orchestratorModel', 'tools', 'extensions', 'availableTo']);
 /** STRICT install-time validation for a plugin-declared `kinds` block —
  *  the loud counterpart to `mergeKinds`'s silent read-time dropping. Read
@@ -480,8 +609,11 @@ function mergeConfig(partial) {
         : normalizeWorkingGerunds(partial.working_gerunds);
     const whip_mode = typeof partial.whip_mode === 'boolean' ? partial.whip_mode : defaults.whip_mode;
     const page_components = normalizePageComponents(partial.page_components);
-    const html_surface = typeof partial.html_surface === 'boolean' ? partial.html_surface : defaults.html_surface;
+    const page_surface = typeof partial.page_surface === 'boolean' ? partial.page_surface : defaults.page_surface;
     const whip_messages = normalizeWhipMessages(partial.whip_messages);
+    const whip_message_mode = WHIP_MESSAGE_MODES.includes(partial.whip_message_mode)
+        ? partial.whip_message_mode
+        : defaults.whip_message_mode;
     const mouse_mode_default = MOUSE_MODE_DEFAULTS.includes(partial.mouse_mode_default)
         ? partial.mouse_mode_default
         : defaults.mouse_mode_default;
@@ -501,7 +633,8 @@ function mergeConfig(partial) {
     const kinds = mergeKinds(partial.kinds);
     const remoteCanvas = mergeRemoteCanvas(partial.remoteCanvas);
     const spawnEnv = mergeSpawnEnv(partial.spawnEnv, defaults.spawnEnv?.allow);
-    return { schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, completion_bell, working_gerunds, whip_mode, page_components, html_surface, whip_messages, mouse_mode_default, live_cycles, condensed_history, bash_tool_purpose, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, keybindings, tmux_passthrough, modelLadders, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, spawnEnv };
+    const bin = normalizeBin(partial.bin);
+    return { bin, schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, completion_bell, working_gerunds, whip_mode, page_components, page_surface, whip_messages, whip_message_mode, mouse_mode_default, live_cycles, condensed_history, bash_tool_purpose, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, keybindings, tmux_passthrough, modelLadders, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, spawnEnv };
 }
 /** Raw (un-defaulted) partial config for one scope, or null if the scope has
  *  no root or no config.json. Used by `readMergedLaunchConfig` to layer

package/dist/core/help.js

@@ -223,7 +223,7 @@ function paramDesc(p) {
     // flag
     const f = p;
     if (f.type === 'bool')
-        return `optional boolean. Presence means true. ${f.constraint}`.trim();
+        return `${req} boolean. Presence means true. ${f.constraint}`.trim();
     const dflt = f.default !== undefined ? ` Default: ${String(f.default)}.` : '';
     const choices = f.type === 'enum' && f.choices !== undefined
         ? ` One of: ${f.choices.join(', ')}.`

package/dist/core/human/__tests__/page-catalog.test.js

@@ -14,3 +14,7 @@ test('page component registrations accept legacy names and documented objects',
     assert.throws(() => normalizePageComponents([{ kind: 'approval', display: 'yes' }]), /page_components\[0\]\.display must be a boolean/);
     assert.throws(() => normalizePageComponents([{ kind: 'approval', unexpected: true }]), /unknown field\(s\): unexpected/);
 });
+test('page component registrations reserve derived built-in and product JSX tags', () => {
+    assert.throws(() => normalizePageComponents(['user-question']), /derives JSX tag "UserQuestion", which collides with a built-in page component/);
+    assert.throws(() => normalizePageComponents(['foo-bar', 'foo--bar']), /derives JSX tag "FooBar", which duplicates another product page component/);
+});