@north-light/crouter 0.3.197 → 0.3.199

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

@@ -4,19 +4,26 @@
 // it is exhaustively unit-testable. The app layer (app.ts) wires the canvas data
 // access (dashboardRowsAll / listNodes / subscriptionsOf) into buildTree, then
 // drives flatten() on each keystroke.
-import { statusRank } from '../node-order.js';
+import { isFinishedWork, isLiveStatus, statusRank } from '../node-order.js';
 export const TABS = ['All', 'Live', 'Dormant', 'Attention', 'Pinned'];
 export const SORTS = ['tree', 'attention', 'relevance', 'recency'];
 /** Does a node belong to this tab's slice?
  *    All       — every node.
- *    Live      — active | idle.
- *    Dormant   — done | dead | canceled.
+ *    Live      — what you can pick up right now: active | idle, PLUS a resident
+ *                agent that stopped without finishing (its broker exited, but
+ *                Enter resumes the conversation in place — see `isFinishedWork`).
+ *                Finished work never appears here.
+ *    Dormant   — done | dead | canceled: literally "no engine running". A stopped
+ *                resident agent is deliberately on BOTH tabs — it is resumable
+ *                (Live) and it is not running (Dormant); both are true and each
+ *                tab is the one a different search starts from.
  *    Attention — needs a human: has pending asks OR is parked on a fault.
  *    Pinned    — user-starred (a local, view-only preference; `isPinned`). */
 export function tabPredicate(tab, row, isPinned = false) {
     switch (tab) {
         case 'All': return true;
-        case 'Live': return row.status === 'active' || row.status === 'idle';
+        case 'Live': return isLiveStatus(row.status)
+            || !isFinishedWork({ lifecycle: row.lifecycle, finalized: row.finalized === true });
         case 'Dormant': return row.status === 'done' || row.status === 'dead' || row.status === 'canceled';
         case 'Attention': return row.asks > 0 || row.hanging != null;
         case 'Pinned': return isPinned;

package/dist/core/canvas/browse/render.d.ts

@@ -43,6 +43,10 @@ export interface RenderState {
      *  a descendant) is actively streaming. Holds the node id being confirmed; the
      *  footer becomes the y/n prompt. null/undefined = no pending confirm. */
     pendingClose?: string | null;
+    /** One-shot footer confirmation for a keystroke whose whole effect is off-screen
+     *  (`y` yank). Replaces the nav hints for exactly one frame; the app clears it on
+     *  the next key. null/undefined = show the ordinary footer. */
+    flash?: string | null;
     /** Set when the source is a remote canvas: mutation/focus keys (`x`/`K`/Enter)
      *  are disabled, so the footer drops their hints instead of advertising a
      *  dead action. undefined/false = local, byte-identical footer. */

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

@@ -428,7 +428,8 @@ const HELP_ROWS = [
     ['Pin', 'f', 'star / unstar — floats to top, Pinned tab'],
     ['Open', '⏎  o', 'resume the node (closes navigator)'],
     ['', 'O', 'resume, keep browsing (open in background)'],
-    ['Act', 'm', 'message the node (no resume)'],
+    ['Act', 'y', 'copy the node id to the clipboard'],
+    ['', 'm', 'message the node (no resume)'],
     ['', 'R', 'rename the node'],
     ['', 'x', 'close-out node + subtree'],
     ['', 'K', 'revive now (a hanging node)'],
@@ -533,6 +534,9 @@ export function renderFrame(state, size, caps = { color: false, color256: false
         const warn = `⚠ ${who} is ⟳ — close it (and its subtree) anyway?  y / n`;
         lines.push(caps.color ? `${BOLD}${ESC}${FG_BRIGHT_YELLOW}m${clip(warn, width)}${RESET}` : `${REVERSE}${clip(warn, width)}${RESET}`);
     }
+    else if (state.flash !== null && state.flash !== undefined && state.flash !== '') {
+        lines.push(caps.color ? `${BOLD}${clip(state.flash, width)}${RESET}` : `${REVERSE}${clip(state.flash, width)}${RESET}`);
+    }
     else {
         // When the cursor row has an active fault, lead the footer with the on-demand kick
         // hint (K shells `node lifecycle revive <id> --now` — immediate revive instead of

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

@@ -90,6 +90,10 @@ export declare function clearPid(nodeId: string): void;
 export declare function migrateLegacyPidIdentities(captureIdentity?: (pid: number) => string | undefined): {
     migrated: string[];
 };
+/** 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 declare function listNodesByProfile(profileId: string): NodeMeta[];
 /** All rows, optionally filtered by status. Unclaimed warm spares are excluded. */
 export declare function listNodes(filter?: {
     status?: NodeStatus | NodeStatus[];
@@ -206,6 +210,11 @@ export declare function view(root: string): string[];
  *  that's still live (active|idle) — i.e. something that can actually wake it?
  *  If so, stopping is a legitimate await; if not, it must finish or escalate. */
 export declare function hasActiveLiveSubscription(nodeId: string): boolean;
+/** Whether a LIVE node still subscribes to this one. The mirror of
+ * `hasActiveLiveSubscription`: that asks what can still wake this node, this
+ * asks what this node still owes — a subscriber that is itself active or idle
+ * is waiting on a report this node has not delivered. */
+export declare function hasLiveSubscriber(nodeId: string): boolean;
 /** Whether a node explicitly awaits a controller that can still deliver. A
  * parent relationship never implies this wait; the node must declare it. */
 export declare function hasLiveMessageWait(nodeId: string): boolean;
@@ -301,6 +310,9 @@ export interface DeleteNodeResult {
  *  state are removed in one canvas write boundary. Best-effort dir removal
  *  follows the commit. */
 export declare function deleteNode(nodeId: string): DeleteNodeResult;
+/** 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 declare function deleteNodes(nodeIds: readonly string[]): string[];
 /** 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
@@ -324,6 +336,27 @@ export declare function pruneNodes(opts: {
     dryRun?: boolean;
     includeStale?: boolean;
 }): PruneResult;
+/** Drop rows whose on-disk `nodes/<id>/` dir is gone — a node that no longer
+ *  exists in the only place it is durably stored.
+ *
+ *  `createNode` scaffolds the dir and writes meta.json BEFORE seeding the row, and
+ *  both delete paths ({@link deleteNode}, `deletePrunedNodes`) commit the row
+ *  removal BEFORE removing the dir, so a row with no dir is never a transient of
+ *  either — it is a node whose durable state was lost. Nothing about it is
+ *  recoverable: `getNode` reads meta.json and returns null, so every surface that
+ *  resolves a node (revive, focus, close, rename, message) rejects it as unknown
+ *  while the roster keeps listing it. The row IS the residue, so deleting it is
+ *  the whole repair; there is no dir left to remove.
+ *
+ *  Because `active`/`idle` ghosts are the ones that jam surfaces, status is not a
+ *  filter here — count-based pruning protects those rows precisely so daemon
+ *  crash-recovery can resume them, and that reason does not survive the dir being
+ *  gone.
+ *
+ *  Refuses to act on "can't tell": an unreadable nodes root, or a readable one
+ *  holding no node dirs at all while rows exist, reads as a detached or wiped
+ *  store rather than per-node loss, and reaps nothing. Returns the reaped ids. */
+export declare function reapGhostRows(): string[];
 /** Count-based retention sweep: retain the `maxNodes` MOST-RECENTLY-ACTIVE
  *  nodes plus every protected node, so the real retained floor is
  *  `max(maxNodes, protectedCount)`. Bounds the otherwise-unbounded growth the

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();
@@ -591,6 +606,18 @@ export function hasActiveLiveSubscription(nodeId) {
         .get(nodeId);
     return r !== undefined;
 }
+/** Whether a LIVE node still subscribes to this one. The mirror of
+ * `hasActiveLiveSubscription`: that asks what can still wake this node, this
+ * asks what this node still owes — a subscriber that is itself active or idle
+ * is waiting on a report this node has not delivered. */
+export function hasLiveSubscriber(nodeId) {
+    const r = openDb()
+        .prepare(`SELECT 1 FROM edges e JOIN nodes n ON n.node_id = e.from_id
+       WHERE e.type = 'subscribes_to' AND e.to_id = ? AND e.active = 1
+         AND n.status IN ('active', 'idle') LIMIT 1`)
+        .get(nodeId);
+    return r !== undefined;
+}
 /** Whether a node explicitly awaits a controller that can still deliver. A
  * parent relationship never implies this wait; the node must declare it. */
 export function hasLiveMessageWait(nodeId) {
@@ -732,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
@@ -789,6 +838,49 @@ export function pruneNodes(opts) {
     deletePrunedNodes(candidates);
     return { pruned: candidates, dryRun };
 }
+/** Drop rows whose on-disk `nodes/<id>/` dir is gone — a node that no longer
+ *  exists in the only place it is durably stored.
+ *
+ *  `createNode` scaffolds the dir and writes meta.json BEFORE seeding the row, and
+ *  both delete paths ({@link deleteNode}, `deletePrunedNodes`) commit the row
+ *  removal BEFORE removing the dir, so a row with no dir is never a transient of
+ *  either — it is a node whose durable state was lost. Nothing about it is
+ *  recoverable: `getNode` reads meta.json and returns null, so every surface that
+ *  resolves a node (revive, focus, close, rename, message) rejects it as unknown
+ *  while the roster keeps listing it. The row IS the residue, so deleting it is
+ *  the whole repair; there is no dir left to remove.
+ *
+ *  Because `active`/`idle` ghosts are the ones that jam surfaces, status is not a
+ *  filter here — count-based pruning protects those rows precisely so daemon
+ *  crash-recovery can resume them, and that reason does not survive the dir being
+ *  gone.
+ *
+ *  Refuses to act on "can't tell": an unreadable nodes root, or a readable one
+ *  holding no node dirs at all while rows exist, reads as a detached or wiped
+ *  store rather than per-node loss, and reaps nothing. Returns the reaped ids. */
+export function reapGhostRows() {
+    const rows = listNodes();
+    if (rows.length === 0)
+        return [];
+    let onDisk;
+    try {
+        onDisk = new Set(readdirSync(nodesRoot()));
+    }
+    catch {
+        return []; // nodes root absent or unreadable — can't tell, so touch nothing
+    }
+    if (onDisk.size === 0)
+        return [];
+    const ghosts = rows.map((r) => r.node_id).filter((id) => !onDisk.has(id));
+    if (ghosts.length === 0)
+        return [];
+    withCanvasWrite((db) => {
+        const del = db.prepare('DELETE FROM nodes WHERE node_id = ?');
+        for (const id of ghosts)
+            del.run(id);
+    });
+    return ghosts;
+}
 /** Hard-delete a set of pruned nodes in one transaction (the edges→nodes and
  *  anchored-crons FKs cascade their coupled state), followed by best-effort
  *  on-disk `nodes/<id>/` removal. Shared by TTL and count pruning so their

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

@@ -439,9 +439,8 @@ export async function parseArgv(params, tokens, options) {
             throw parseArgvError('bad_invocation', `unexpected extra positional argument: ${token}`, tokens.join(' '), undefined, 'Use --flag for parameters; only one positional allowed.');
         }
         // A bare positional is accepted when the leaf declares a positional param,
-        // OR when it declares a stdin param (the positional supplies the stdin
-        // value as an ergonomic alternative to piping). Otherwise it's an error.
-        if (positionalParam === undefined && stdinParam === undefined) {
+        // or when its stdin parameter explicitly permits a positional body.
+        if (positionalParam === undefined && (stdinParam === undefined || stdinParam.allowPositional === false)) {
             throw parseArgvError('bad_invocation', `this leaf takes no positional arguments: ${token}`, token, undefined, 'Use --flag for parameters. Run -h for the schema.');
         }
         positionalValues.push(token);
@@ -454,16 +453,12 @@ export async function parseArgv(params, tokens, options) {
             ? positionalValues
             : positionalValues[0];
     }
-    // Resolve stdin if declared. A positional token (when there's no dedicated
-    // positional param to claim it) satisfies the stdin param directly, so
-    // `crtr node new "Say hi"` works as well as piping on stdin. `-` is the
-    // standard Unix convention for "read stdin instead" — it always reads,
-    // never becomes the literal value. And a positional alongside genuinely
-    // piped, non-empty stdin is ambiguous: never silently pick one, error loud
-    // and name both sources.
+    // Resolve stdin if declared. Some leaves permit one positional token to
+    // supply the stdin body; `-` then means read stdin. A positional alongside
+    // genuinely piped, non-empty stdin is ambiguous and errors loudly.
     let stdinWasSupplied = false;
     if (stdinParam !== undefined) {
-        if (positionalValues.length > 0 && positionalParam === undefined) {
+        if (positionalValues.length > 0 && positionalParam === undefined && stdinParam.allowPositional !== false) {
             const positionalValue = positionalValues[0];
             if (positionalValue === '-') {
                 const raw = await readStdinRaw();
@@ -547,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