@north-light/crouter 0.3.154

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

@@ -0,0 +1,302 @@
+/** What a node is doing right now. `active` means the engine process — a detached
+ *  headless broker — is live, NOT that it holds a window or that anyone is
+ *  watching it (attachment is a separate axis: the `focuses` table tracks each
+ *  node's one viewer pane, and the broker records its helloed-viewer count).
+ *  Crucially, `active` does NOT mean the node is GENERATING right now: a live
+ *  engine sits dormant between turns (waiting on a child, a human, or just left
+ *  open), so `active` ≠ busy — it only means the process was never closed. To tell
+ *  whether an active node is actually working, check its pi session-file mtime or
+ *  CPU, not its status. UI shows active+idle; `done` is hidden but revivable;
+ *  `canceled` is a user-closed node (also hidden, also revivable — not a fault);
+ *  only `dead` is a fault. */
+export type NodeStatus = 'active' | 'idle' | 'done' | 'dead' | 'canceled';
+/** Does stopping finalize the node? terminal = worker (finalizes on push --final);
+ *  resident = manager/orchestrator (stays dormant, woken by inbox). */
+export type Lifecycle = 'terminal' | 'resident';
+/** base = hands-on worker; orchestrator = delegating manager. Bespoke per kind. */
+export type Mode = 'base' | 'orchestrator';
+/** Why a node last stopped — drives the daemon's reap-vs-revive decision. */
+export type ExitIntent = 'done' | 'refresh' | 'idle-release' | null;
+/** The two structural edges. `subscribes_to` is the load-bearing spine (flow,
+ *  org chart, views, completion routing). `spawned_by` is audit only. */
+export type EdgeType = 'subscribes_to' | 'spawned_by';
+/** The pi launch recipe, persisted so the daemon can faithfully revive a node
+ *  as its *current* self. Rewritten on every polymorph (base→orchestrator). */
+export interface LaunchSpec {
+    /** Model id/pattern passed to pi `--model`. */
+    model?: string;
+    /** True only for a caller's explicit `provider/tier` or `provider/id` override. */
+    modelProviderPinned?: boolean;
+    /** True for an exact-consult launch: `model` is the verbatim captured
+     *  `provider/id:thinking` spec, bypassing the review floor/normalize and
+     *  every launch-time/turn-time provider fallback — an unavailable exact
+     *  model must fail rather than substitute. See `buildLaunchSpec`. */
+    modelExact?: boolean;
+    /** pi `--tools` allow-list. */
+    tools?: string[];
+    /** pi `-e` extension paths, loaded once; they self-gate on live {kind,mode}. */
+    extensions: string[];
+    /** Resolved system prompt text (passed via --append-system-prompt / --system-prompt). */
+    systemPrompt?: string;
+    /** Extra env injected into the pi process. */
+    env: Record<string, string>;
+}
+export interface ManagedWorktree {
+    state: 'open' | 'closed';
+    path: string;
+    branch: string;
+    repo_root: string;
+    base_ref: string;
+    base_sha: string;
+    created: string;
+    closed?: string;
+}
+/** The private human task a lifecycle-owned fork answers. The discriminator is
+ *  deliberately closed over the two supported lanes; adding another private
+ *  worker kind requires an explicit contract rather than an untyped target. */
+export type HumanWorkTarget = {
+    work_kind: 'follow_up';
+    dir: string;
+    request_id: string;
+    root: string;
+} | {
+    work_kind: 'visual';
+    dir: string;
+    request_id: string;
+    root: string;
+};
+/** Whether a private human-work fork still needs its first writable Pi session
+ *  created from immutable provenance, or has bound that child session and can
+ *  only resume it. */
+export type PrivateForkPhase = 'fork_pending' | 'session_started';
+/** The one-shot portion of a private fork's persisted launch recipe. The other
+ *  immutable recipe facts stay in their existing canonical fields:
+ *  `NodeIdentity.fork_from` is the absolute provenance file and
+ *  `LaunchSpec.model` with `modelExact` is the exact runtime selection. */
+export interface PrivateForkRecipe {
+    kickoff: string;
+}
+/** A node's DURABLE IDENTITY — the subset that `meta.json` persists on disk.
+ *  Written rarely (birth, polymorph, session-id capture, naming); never touched
+ *  by a status flip, an intent change, a focus swap, or a pid stamp. The db row
+ *  indexes the queryable identity columns; `rebuildIndex()` re-derives them from
+ *  here. (Live runtime state lives in NodeRuntime, authoritative in the row.) */
+export interface NodeIdentity {
+    node_id: string;
+    name: string;
+    /** A 2-4 word kebab-case handle derived from the node's first prompt (named
+     *  headlessly by pi; see runtime/naming.ts). Shown in the editor label. */
+    description?: string;
+    /** How many times this node has been (re)launched — born at 0, bumped on
+     *  every revive. Exposed to the pi footer as CRTR_CYCLES so a refresh/crash
+     *  cycle reads at a glance there. */
+    cycles?: number;
+    created: string;
+    /** The dir this node is pinned to — its cwd (where pi runs, bash executes). */
+    cwd: string;
+    /** Which HOST launches + supervises this node: 'tmux' (a pane) or 'broker' (the
+     *  headless in-process engine). Durable IDENTITY (mirrored to the row like
+     *  `cwd`, re-derived on index rebuild), NOT live runtime like `pane`.
+     *  NULL ⇒ 'tmux' (every pre-broker node). */
+    host_kind?: 'tmux' | 'broker' | null;
+    /** The profile this node runs under, a stable profile-directory id
+     *  (`<slug>-<id>`, see `core/profiles/manifest.ts`). Durable IDENTITY mirrored
+     *  to the row (like `cwd`/`host_kind`), NOT re-derived by `rebuildIndex()` —
+     *  it is chosen once at spawn (inherited from the spawner, or `--profile`) and
+     *  is the runtime→resolver seam (`CRTR_PROFILE_ID`) the memory/gate substrate
+     *  reads. NULL only for historical root/no-profile rows; new root conversations
+     *  use the stable root profile id. */
+    profile_id?: string | null;
+    /** Role the node was born as: explore | developer | plan | review | general… */
+    kind: string;
+    mode: Mode;
+    lifecycle: Lifecycle;
+    /** The last persona state {mode,lifecycle} the node was GIVEN transition
+     *  guidance for. Meta-only (not a db column). Born equal to the node's initial
+     *  {mode,lifecycle} at spawn so a fresh node never gets spurious guidance. The
+     *  persona injector (runtime/persona.ts) compares the live {mode,lifecycle}
+     *  against this and, on drift, injects guidance for the new state then commits
+     *  it here. */
+    persona_ack?: {
+        mode: Mode;
+        lifecycle: Lifecycle;
+    };
+    /** Spine parent — my manager (who subscribes to me); drives canvas nesting +
+     *  orphaning. null for a root (top-level, no manager). */
+    parent?: string | null;
+    /** Provenance — who spawned me (the `spawned_by` edge). Decoupled from
+     *  `parent` so an INDEPENDENT root (parent=null) still records its lineage.
+     *  Audit only; null for a user-opened root. Defaults to `parent` for a child. */
+    spawned_by?: string | null;
+    /** Fork provenance — the `--fork-from` source this node was forked from at
+     *  spawn (the node id / session path / pi session uuid the caller passed). pi
+     *  COPIED that conversation into this node's first session, so the node boots
+     *  carrying the SOURCE's first-person history. Persisted here so the boot
+     *  intro can assert this node's OWN identity over that inherited narrative
+     *  (without it a fork impersonates its source). Undefined for a fresh node;
+     *  identity/audit only. */
+    fork_from?: string | null;
+    /** Immutable private-human-work binding. Delivery remains owned by the
+     *  corresponding outbox protocol; this target identifies what the private
+     *  lifecycle child exists to answer. Undefined for ordinary nodes. */
+    human_work_target?: HumanWorkTarget | null;
+    /** Private fork birth is explicit across the pre-session crash boundary.
+     *  `fork_pending` launches only from the immutable provenance + kickoff;
+     *  `session_started` launches only from the bound child session. */
+    private_fork_phase?: PrivateForkPhase | null;
+    /** Persisted one-shot kickoff for `fork_pending`; ignored after the child
+     *  session is bound. See `PrivateForkRecipe` for the rest of the recipe. */
+    private_fork_recipe?: PrivateForkRecipe | null;
+    /** New subscriptions this node opens default to passive when true. */
+    passive_default?: boolean;
+    /** The pi session id for `--session <id>` revival. */
+    pi_session_id?: string | null;
+    /** Absolute path to pi's session `.jsonl` file, captured at session_start via
+     *  ctx.sessionManager.getSessionFile(). Preferred over pi_session_id when
+     *  resuming: pi resolves a BARE `--session <id>` relative to the launch cwd
+     *  first (and shows an interactive cross-project "Fork? [y/N]" prompt when the
+     *  revive cwd differs from the session's creation cwd), whereas an absolute
+     *  PATH is opened directly — immune to any cwd discrepancy. Null for older
+     *  nodes booted before this field existed → revive falls back to the bare id. */
+    pi_session_file?: string | null;
+    /** True while a cycling (`--crtr-new-cycle`) launch remains unconfirmed. Set
+     *  monotonically by reviveNode before launch and cleared only by the stophook's
+     *  confirmed `session_start`. While true, reviveNode's locked arbitration
+     *  vetoes every caller's strict-resume preference so a failed cycle cannot
+     *  reopen the old context. */
+    cycle_pending?: boolean | null;
+    /** A caller-pinned model TIER (ultra/strong/medium/light) that overrides the
+     *  persona's declared default. Durable so it survives a polymorph: every
+     *  spec-rebuild path (promote/demote/lifecycle/reset) re-passes it to
+     *  buildLaunchSpec, while the persona default is recomputed fresh for the
+     *  (possibly new) kind. Null/undefined ⇒ use the persona default. */
+    model_override?: string | null;
+    /** Full pi launch recipe; rewritten on every polymorph. */
+    launch?: LaunchSpec;
+    /** Managed git worktree owned by this node (if any). */
+    managed_worktree?: ManagedWorktree | null;
+}
+/** A node's LIVE RUNTIME state — authoritative in the WAL'd `nodes` row, each
+ *  field mutated by exactly one atomic single-statement `UPDATE` (setStatus /
+ *  setIntent / setPresence / recordPid+clearPid). NOT persisted to meta.json and
+ *  NOT re-derivable by `rebuildIndex()` — it describes live process/presence
+ *  state that is meaningless after the event that would lose the db; the daemon
+ *  reconciles it from tmux reality, not from a stale file. */
+export interface NodeRuntime {
+    /** What the node is doing right now. */
+    status: NodeStatus;
+    /** Why the node last stopped (done | refresh | idle-release). Drives reap-vs-revive.
+     *  Optional on the hydrated view (a fresh construction omits it); the row
+     *  column is always present, defaulting null. */
+    intent?: ExitIntent;
+    /** Controller whose next inbox delivery permits this terminal node to sleep.
+     * Mutable durable runtime state: ancestry never implies a wait. */
+    waiting_for?: string | null;
+    /** Immutable basename of the committed canonical final report, or null. */
+    final_report?: string | null;
+    /** ISO timestamp carried by the committed canonical final report, or null. */
+    finalized_at?: string | null;
+    /** OS pid of the live broker process, recorded on boot (stophook session_start).
+     *  The daemon's authoritative liveness signal — every node is a detached broker,
+     *  so `isPidAlive(pi_pid)` is the sole liveness check. Cleared to null by
+     *  reviveNode until the fresh broker re-records it, so the relaunch gap reads as
+     *  a dead pid (guarded by the daemon's revive grace, not a double-spawn). */
+    pi_pid?: number | null;
+    /** Stable process-identity fingerprint (`pid.ts`'s `composeIdentity`) captured
+     *  at the SAME moment `pi_pid` is recorded (`recordPid`) — the LAUNCH-time
+     *  baseline `headlessBrokerHost.teardown()` compares `pi_pid`'s CURRENT
+     *  identity against before signaling anything (crouter#98 review finding 1):
+     *  a mismatch proves the OS has already recycled `pi_pid` for an unrelated
+     *  process since this node launched it, and teardown must refuse to signal
+     *  that stranger. `null` for a node booted before this field existed, or if
+     *  the launch-time identity capture itself failed (fail-open — no baseline
+     *  means no guard, not a false mismatch). Cleared to null alongside `pi_pid`
+     *  by `clearPid` and the boot-liveness sweep (a new boot invalidates both). */
+    pi_pid_identity?: string | null;
+    /** Presence: the tmux session (its root's home) and window this node renders
+     *  in while active. Cleared when the node goes done/dead and its window closes.
+     *  The row IS the presence registry (one atomic setPresence per move).
+     *  v3: a DERIVED CACHE of `pane`'s current location — reconciled from the pane,
+     *  never trusted when a user move could have desynced them. */
+    tmux_session?: string | null;
+    window?: string | null;
+    /** LOCATION's authoritative handle — the durable tmux `%pane_id` this node's
+     *  pane is anchored on. tmux preserves it across `move-pane`/`join-pane`/
+     *  `break-pane` and window renumbering, so `window`/`tmux_session` above are a
+     *  cache reconciled from it and pane-existence is the liveness probe. A
+     *  not-focused + not-generating node has `pane = null` (no pane). Authoritative
+     *  in the row exactly like `window`/`tmux_session` — a RUNTIME field, NOT meta
+     *  identity — written by the one atomic `setPresence` UPDATE. */
+    pane?: string | null;
+}
+/** The hydrated node view `getNode()` returns: durable identity (from meta.json)
+ *  ∪ live runtime (from the row). Keeps the historical `NodeMeta` name and field
+ *  set so every `meta.X` read across the codebase typechecks unchanged — but
+ *  `writeMeta` serializes only the NodeIdentity subset and the runtime fields are
+ *  hydrated from the authoritative row. */
+export type NodeMeta = NodeIdentity & NodeRuntime;
+/** The queryable projection of a node stored as a canvas.db row: the indexed
+ *  identity columns PLUS the authoritative runtime columns. */
+export interface NodeRow {
+    node_id: string;
+    name: string;
+    kind: string;
+    mode: Mode;
+    lifecycle: Lifecycle;
+    status: NodeStatus;
+    cwd: string;
+    /** Which HOST launches + supervises this node; see NodeIdentity.host_kind. */
+    host_kind: 'tmux' | 'broker' | null;
+    /** The profile this node runs under; see NodeIdentity.profile_id. NULL only
+     *  for historical root/no-profile rows. */
+    profile_id: string | null;
+    parent: string | null;
+    created: string;
+    /** Authoritative runtime columns (see NodeRuntime). */
+    intent: ExitIntent;
+    waiting_for: string | null;
+    final_report?: string | null;
+    finalized_at?: string | null;
+    pi_pid: number | null;
+    /** See `NodeRuntime.pi_pid_identity`. */
+    pi_pid_identity: string | null;
+    window: string | null;
+    tmux_session: string | null;
+    /** The durable LOCATION handle (the tmux `%pane_id`); see NodeRuntime.pane. */
+    pane: string | null;
+}
+/** An edge as stored. For `subscribes_to`, `from` is the subscriber and `to`
+ *  is the publisher (A subscribes_to B ⇒ A receives B's output). For
+ *  `spawned_by`, `from` is the child and `to` is the parent. */
+export interface Edge {
+    type: EdgeType;
+    from: string;
+    to: string;
+    /** Only meaningful for subscribes_to: active = wake the subscriber on emit;
+     *  passive = accumulate pointers, no wake. */
+    active: boolean;
+    created: string;
+}
+/** A FOCUS row as stored in the `focuses` table (canvas.db, migration v6): one
+ *  durable on-screen viewport the user looks at, bound to one node. Plural —
+ *  many focuses live at once across windows and sessions (the plural
+ *  generalization of the old single focus pointer). Anchored on the durable tmux
+ *  `%pane_id`; `session` is a derived cache reconciled from the pane. `node_id`
+ *  is UNIQUE — a node occupies at most one focus (Q5). */
+export interface FocusRow {
+    /** Stable internal id for the viewport (the table's primary key). */
+    focus_id: string;
+    /** The durable `%pane_id` realizing the focus, or null before it is placed. */
+    pane: string | null;
+    /** Derived cache of the user session the pane lives in (reconciled from pane). */
+    session: string | null;
+    /** The node this focus shows. UNIQUE → a node occupies ≤1 focus. */
+    node_id: string;
+}
+/** A subscription as seen from one endpoint. */
+export interface SubscriptionRef {
+    /** The node id at the other end of the edge. */
+    node_id: string;
+    active: boolean;
+    created: string;
+}

package/dist/core/canvas/types.js

@@ -0,0 +1,8 @@
+// The canvas vocabulary — the node + edge model the whole runtime hangs on.
+//
+// One global canvas (`~/.crouter/canvas/canvas.db`) holds the topology (nodes +
+// edges); each node's flesh lives on disk under `~/.crouter/canvas/nodes/<id>/`. A node's
+// `meta.json` is the source of truth for its own row; the db is a queryable
+// index over those metas, plus the authoritative store for the mutable
+// `subscribes_to` edges (which no single meta owns).
+export {};

package/dist/core/clipboard-text.d.ts

@@ -0,0 +1,3 @@
+/** Write `text` to the system clipboard. Returns true on success, false when no
+ *  clipboard tool is available or every attempt failed. Never throws. */
+export declare function writeClipboardText(text: string): boolean;

package/dist/core/clipboard-text.js

@@ -0,0 +1,39 @@
+// clipboard-text.ts — write text to the system clipboard.
+//
+// pi's clipboard binding is not re-exported (see input/clipboard-image.ts), so we shell
+// out to the platform clipboard tool, mirroring the read path: macOS `pbcopy`
+// (always present), Linux `wl-copy` (Wayland) or `xclip` (X11). Best-effort —
+// returns false (with no throw) when no tool is available or the write fails, so
+// the caller can surface an accurate notice.
+import { spawnSync } from 'node:child_process';
+const SPAWN_TIMEOUT_MS = 3000;
+/** Ordered list of [command, args] clipboard-write tools to try for this
+ *  platform. The first one present on PATH that succeeds wins. */
+function writers() {
+    if (process.platform === 'darwin')
+        return [['pbcopy', []]];
+    const wayland = Boolean(process.env.WAYLAND_DISPLAY) || process.env.XDG_SESSION_TYPE === 'wayland';
+    const xclip = ['xclip', ['-selection', 'clipboard']];
+    const wlcopy = ['wl-copy', []];
+    return wayland ? [wlcopy, xclip] : [xclip, wlcopy];
+}
+/** Write `text` to the system clipboard. Returns true on success, false when no
+ *  clipboard tool is available or every attempt failed. Never throws. */
+export function writeClipboardText(text) {
+    for (const [command, args] of writers()) {
+        const result = spawnSync(command, args, {
+            input: text,
+            timeout: SPAWN_TIMEOUT_MS,
+            encoding: 'utf-8',
+        });
+        // ENOENT → tool not installed; try the next one.
+        if (result.error) {
+            if (result.error.code === 'ENOENT')
+                continue;
+            continue;
+        }
+        if (result.status === 0)
+            return true;
+    }
+    return false;
+}

package/dist/core/command-manifests/registry.d.ts

@@ -0,0 +1,43 @@
+import type { LeafDef } from '../command.js';
+import type { DeclLeafBase, DeclBranch, CommandManifestIssue } from './schema.js';
+/** Reference to an external contributor (plugin or configured CLI). */
+export type CommandContributorRef = {
+    kind: 'plugin' | 'configured-cli';
+    name: string;
+    scope: 'user' | 'project';
+};
+/** Adapter callback to turn a declared leaf into a crtr LeafDef. Takes the
+ *  leaf definition and its resolved command path, returns the outputKind and
+ *  run function to be used by the tree composer. */
+export type LeafAdapter = (leaf: DeclLeafBase, commandPath: readonly string[]) => {
+    outputKind: 'object' | 'jsonl';
+    run: LeafDef['run'];
+};
+/** One accepted external contribution after collision resolution: a validated
+ *  top-level branch node, contributor identity, and the adapter callback that
+ *  will produce its leaves' run implementations. */
+export interface CommandContribution {
+    contributor: CommandContributorRef;
+    node: DeclBranch<DeclLeafBase>;
+    adaptLeaf: LeafAdapter;
+}
+/** Per-contributor collision issue. */
+export interface ContributorIssue extends CommandManifestIssue {
+    contributor: CommandContributorRef;
+}
+/** Invocation-local registry snapshot after collision resolution: the accepted
+ *  contributions and every discovered issue. The amended spec has no freshness
+ *  machinery, so there is no owner-routing map — an unknown-token miss hydrates
+ *  ALL absent-store registrations once (§5.1), never a single known owner. */
+export interface CommandRegistrySnapshot {
+    /** Accepted top-level contributions, deterministically ordered by
+     *  contributor name. */
+    contributions: CommandContribution[];
+    /** Every discovered issue, including collisions. */
+    issues: ContributorIssue[];
+}
+/** Resolve a flat list of candidate contributions into a collision-resolved
+ *  snapshot. Every contribution at a collided path is dropped (all claimants),
+ *  an issue is recorded on each claimant, core names take precedence, and
+ *  results are deterministically ordered by contributor name. */
+export declare function resolveCommandRegistry(candidates: readonly CommandContribution[], reservedCoreNames: ReadonlySet<string>): CommandRegistrySnapshot;

package/dist/core/command-manifests/registry.js

@@ -0,0 +1,103 @@
+// Unified command registry: transport-neutral collision resolution and
+// contributor attribution. This module takes raw candidates (from plugins,
+// configured CLIs, or any external source) and runs one unified pass that:
+//
+// 1. Detects collisions by resolved path (shortest collision wins).
+// 2. Drops all claimants at each collided path.
+// 3. Records issues on every claimant at each collision.
+// 4. Gives core absolute precedence.
+// 5. Returns a deterministically ordered, collision-resolved snapshot.
+//
+// The registry itself is transport-neutral: it knows nothing about plugin
+// executables or HTTP invokers. Each contribution carries its own adapter
+// callback, which the tree composer invokes to turn a leaf into a real crtr
+// LeafDef.
+/** Resolve a flat list of candidate contributions into a collision-resolved
+ *  snapshot. Every contribution at a collided path is dropped (all claimants),
+ *  an issue is recorded on each claimant, core names take precedence, and
+ *  results are deterministically ordered by contributor name. */
+export function resolveCommandRegistry(candidates, reservedCoreNames) {
+    const collisions = new Map();
+    const contributionsByPath = new Map();
+    // Phase 1: Detect collisions. Collect every top-level path (and implicitly,
+    // every ancestor path that the top-level node reaches), detect duplicates.
+    // A collision drops ALL claimants at that path.
+    for (const contrib of candidates) {
+        const { node, contributor } = contrib;
+        const path = [node.name];
+        const pathKey = path.join('/');
+        // Check for core collision at top level.
+        if (reservedCoreNames.has(node.name)) {
+            collisions.set(pathKey, {
+                path,
+                claimants: [contrib],
+                isCoreCollision: true,
+            });
+            continue;
+        }
+        // Check for cross-contributor collision.
+        if (contributionsByPath.has(pathKey)) {
+            const existing = contributionsByPath.get(pathKey);
+            const key = collisions.get(pathKey);
+            if (key === undefined) {
+                collisions.set(pathKey, {
+                    path,
+                    claimants: [existing, contrib],
+                    isCoreCollision: false,
+                });
+            }
+            else {
+                key.claimants.push(contrib);
+            }
+        }
+        else {
+            contributionsByPath.set(pathKey, contrib);
+        }
+    }
+    // Phase 2: Build the final snapshot. Include only non-collided contributions
+    // and record issues on all collided claimants.
+    const accepted = [];
+    const issues = [];
+    for (const contrib of candidates) {
+        const pathKey = [contrib.node.name].join('/');
+        if (collisions.has(pathKey)) {
+            const collision = collisions.get(pathKey);
+            const claimantNames = collision.claimants.map((c) => c.contributor.name).join(', ');
+            const claimantKinds = collision.claimants.map((c) => `${c.contributor.name} (${c.contributor.kind})`).join(', ');
+            // Record an issue on this claimant. A core collision has exactly one
+            // claimant contesting a reserved built-in name, not "multiple contributors".
+            issues.push(collision.isCoreCollision
+                ? {
+                    code: 'command_collision',
+                    contributor: contrib.contributor,
+                    path: contrib.node.name,
+                    message: `top-level command "${contrib.node.name}" collides with a crtr core command and is dropped`,
+                    received: claimantNames,
+                    expected: 'no top-level command name matching a reserved core command',
+                    next: `Rename "${contrib.node.name}" to a name that does not collide with core.`,
+                }
+                : {
+                    code: 'command_collision',
+                    contributor: contrib.contributor,
+                    path: contrib.node.name,
+                    message: `top-level command "${contrib.node.name}" is claimed by multiple contributors: ${claimantKinds}`,
+                    received: claimantNames,
+                    expected: 'exactly one contributor per top-level command',
+                    next: `Remove or disable all but one of: ${claimantNames}.`,
+                });
+        }
+        else {
+            // Not collided — accept it.
+            accepted.push(contrib);
+        }
+    }
+    // Phase 3: Sort accepted contributions deterministically by contributor
+    // name (then by node name for secondary ordering, though each contributor
+    // should have at most one top-level contribution).
+    accepted.sort((a, b) => a.contributor.name.localeCompare(b.contributor.name) ||
+        a.node.name.localeCompare(b.node.name));
+    return {
+        contributions: accepted,
+        issues,
+    };
+}

package/dist/core/command-manifests/schema.d.ts

@@ -0,0 +1,87 @@
+import type { InputParam, Field } from '../help.js';
+export interface DeclRootEntry {
+    concept: string;
+    description: string;
+    whenToUse: string;
+}
+export interface DeclBranch<L = DeclLeafBase> {
+    kind: 'branch';
+    name: string;
+    description: string;
+    whenToUse: string;
+    tier?: 'normal' | 'common' | 'important';
+    /** Required on a top-level branch, forbidden on a nested one. */
+    rootEntry?: DeclRootEntry;
+    summary: string;
+    model?: string;
+    /** Plugin dialect only: forward every argv token after this branch to an
+     *  external binary instead of parsing children. A passthrough branch is
+     *  childless by construction. Forbidden in the configured-CLI dialect — a
+     *  remote manifest naming a local binary to exec is a trust hole. */
+    passthrough?: DeclPassthrough;
+    children: DeclNode<L>[];
+}
+export interface DeclPassthrough {
+    bin: string;
+    installHint: string;
+}
+export interface DeclLeafBase {
+    kind: 'leaf';
+    name: string;
+    description: string;
+    whenToUse: string;
+    tier?: 'normal' | 'common' | 'important';
+    summary: string;
+    params: InputParam[];
+    output: Field[];
+    effects: string[];
+}
+/** Plugin-dialect leaf: requires outputKind: 'object' (no streaming in v1). */
+export interface PluginDeclLeaf extends DeclLeafBase {
+    outputKind: 'object';
+}
+/** Configured CLI REST mapping (placeholder types; full spec in manifest.ts). */
+export type RestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export type RestParamPlacement = 'path' | 'query' | 'body' | 'header';
+export interface RestParamMapping {
+    in: RestParamPlacement;
+    as?: string;
+}
+export interface RestMapping {
+    method: RestMethod;
+    path: string;
+    streaming?: boolean;
+    /** Constant literal body fields merged into the request body (top-level, alongside
+     *  any bodyRoot-nested param values). Forbidden on GET. */
+    body?: Record<string, string | number | boolean>;
+    /** When set, all in:"body" param values nest under this key instead of the body
+     *  top level (constants from `body` stay top-level regardless). Forbidden on GET. */
+    bodyRoot?: string;
+    params: Record<string, RestParamMapping>;
+}
+export interface ManifestTimeouts {
+    connectMs?: number;
+    requestMs?: number;
+    streamIdleMs?: number;
+}
+/** Configured CLI-dialect leaf: requires rest (derives outputKind from streaming). */
+export interface ConfiguredCliDeclLeaf extends DeclLeafBase {
+    rest: RestMapping;
+}
+export type DeclLeaf = PluginDeclLeaf | ConfiguredCliDeclLeaf;
+export type DeclNode<L = DeclLeafBase> = DeclBranch<L> | (L extends DeclLeafBase ? DeclLeaf : never);
+export interface CommandManifestIssue {
+    code: CommandIssueCode;
+    path?: string;
+    message: string;
+    received: string;
+    expected: string;
+    next: string;
+}
+export type CommandIssueCode = 'command_manifest_unreadable' | 'command_manifest_invalid' | 'command_schema_version' | 'command_path_unsafe' | 'command_not_executable' | 'command_parent_invalid' | 'command_node_invalid' | 'command_collision' | 'command_rest_invalid';
+type IssueFn = (code: CommandIssueCode, message: string, received: string, expected: string, next: string, path?: string) => void;
+/** Validate a node for the plugin dialect (leaf must have outputKind: 'object'). */
+export declare function validatePluginNode(raw: unknown, path: string, topLevel: boolean, issue: IssueFn): DeclBranch<PluginDeclLeaf> | PluginDeclLeaf | null;
+/** Validate a node for the configured CLI dialect (leaf must have rest). */
+export declare function validateConfiguredCliNode(raw: unknown, path: string, topLevel: boolean, issue: IssueFn): DeclBranch<ConfiguredCliDeclLeaf> | ConfiguredCliDeclLeaf | null;
+export {};