@crouton-kit/crouter 0.3.36 → 0.3.38

package/dist/commands/node.js

@@ -26,7 +26,8 @@ import { buildLaunchSpec, normalizeModel } from '../core/runtime/launch.js';
 import { closeNode } from '../core/runtime/close.js';
 import { isBrokerLive, setModelLive, persistDormantModel } from '../core/runtime/model-swap.js';
 import { appendInbox } from '../core/feed/inbox.js';
-import { availableKinds, kindWhenToUse } from '../core/personas/index.js';
+import { readMergedLaunchConfig } from '../core/config.js';
+import { listProfiles } from '../core/profiles/manifest.js';
 import { stateBlock } from '../core/help.js';
 import { getNode, updateNode, listNodes, subscribe, unsubscribe, subscriptionsOf, subscribersOf, readContextTokens, view, armTrigger, listTriggers, cancelTrigger, TriggerArmError, fullName, } from '../core/canvas/index.js';
 // Past this much context, an ORCHESTRATOR that spawns a managed child is better
@@ -54,7 +55,7 @@ export function childFollowUp(spawnerId) {
 }
 /** Validate a `--kind` against the installed personas; throws a listing InputError. */
 function assertKind(kind) {
-    const kinds = availableKinds();
+    const kinds = Object.keys(readMergedLaunchConfig().kinds).sort();
     if (!kinds.includes(kind)) {
         throw new InputError({ error: 'unknown_kind', message: `unknown kind: ${kind}`, field: 'kind', next: `Valid kinds: ${kinds.join(', ')}.` });
     }
@@ -65,12 +66,37 @@ function assertKind(kind) {
  *  `node promote -h` so custom kinds appear in help. Soft-fails via the renderer.
  *
  *  Keep this block cheap and caller-agnostic: help should not depend on the
- *  running node's current persona env, which can lag after polymorph. */
+ *  running node's current persona env, which can lag after polymorph. Sub-kinds
+ *  (e.g. `plan/reviewers/security`) are OMITTED here — `KindConfig.availableTo`
+ *  defaults to the sub-kind's own top-level ancestor, and this generic block has
+ *  no single ancestor to check against, so only an explicit `availableTo: ['*']`
+ *  sub-kind (universally available) earns a place in this list. A direct launch
+ *  by full sub-kind string is always valid regardless (visibility-only
+ *  filtering) — discover the roster for a specific kind via
+ *  `crtr sys prompt-review --list --kind <kind>`. */
+/** A live `<profiles count=N>` state element — one `<profile_id> — <name>` line
+ *  per profile on this host, so `--profile` has an enumerable value set on this
+ *  same leaf (command-surface rule) without a separate `crtr profile list` hop.
+ *  Soft-fails via the renderer like `kindsStateBlock`. */
+function profilesStateBlock() {
+    const all = listProfiles();
+    const lines = all.map((p) => `${p.profileId} — ${p.manifest.name}`).join('\n');
+    return stateBlock('profiles', { count: all.length }, lines);
+}
 function kindsStateBlock() {
-    const kinds = availableKinds();
+    const registry = readMergedLaunchConfig().kinds;
+    const kinds = Object.keys(registry)
+        .filter((k) => {
+        const slash = k.indexOf('/');
+        if (slash === -1)
+            return true;
+        const availableTo = registry[k]?.availableTo ?? [k.slice(0, slash)];
+        return availableTo.includes('*');
+    })
+        .sort();
     const lines = kinds
         .map((k) => {
-        const w = kindWhenToUse(k);
+        const w = registry[k]?.whenToUse ?? '';
         return w ? `${k} — ${w}` : k;
     })
         .join('\n');
@@ -89,7 +115,7 @@ const nodeNew = defineLeaf({
         summary: 'spawn a terminal worker onto the canvas as a detached broker — returns its node id. With --at/--every/--when, arms a node_birth trigger instead: nothing is spawned now, and the full recipe is stored/re-derived at fire time',
         params: [
             { kind: 'stdin', name: 'prompt', required: true, constraint: 'First user message for the spawned node. Deliver it on stdin from a quoted heredoc (`<<\'EOF\'`) or a file (`< prompt.md`).' },
-            { kind: 'flag', name: 'kind', type: 'string', required: false, default: 'general', constraint: 'Persona kind — match the work to the kind. The <kinds> list below names every installable kind and when to use each. For an exact composed persona list, use `crtr sys prompt-review --list --kind <kind>`.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, default: 'general', constraint: 'Persona kind — match the work to the kind. The <kinds> list below names every top-level installable kind and when to use each. Sub-kinds (e.g. plan/reviewers/security) are valid too by exact path but not listed here — for the full roster available to a given kind, use `crtr sys prompt-review --list --kind <kind>`.' },
             { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, default: 'base', constraint: 'Persona mode. base for a worker that finishes in one window; orchestrator to create the child directly as a sub-orchestrator (it boots with the orchestrator persona + a seeded roadmap and fans its scope out) — use it when the unit is too large for one window, e.g. a big review, instead of spawning a base worker and counting on it to promote itself.' },
             { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Dir the node is pinned to. Defaults to the caller cwd, resolved now — for a triggered spawn it must still exist at fire time or the spawn fails loud.' },
             { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Display name (tmux window + resume picker). Defaults to the kind.' },
@@ -97,6 +123,7 @@ const nodeNew = defineLeaf({
             { kind: 'flag', name: 'root', type: 'bool', required: false, constraint: 'Spawn an INDEPENDENT root instead of a managed child: no parent (top-level on the canvas), NO subscription back to you (you are NOT woken by it), resident lifecycle. It records spawned_by=you for provenance and is brought forefront so it can be driven directly. Use for a node you hand off and do not manage (e.g. a sub-orchestrator a human will discuss with).' },
             { kind: 'flag', name: 'fork-from', type: 'string', required: false, constraint: 'FORK the new node from an existing pi conversation instead of starting it fresh: pass a node id (forks from that node\'s session), an absolute session `.jsonl` path, or a partial pi session uuid. pi copies that whole history into a NEW session for the child (the source is untouched), then the prompt is delivered as the next message — i.e. the child wakes up as a continuation of that conversation. Use to branch exploratory work off a node that already built up the context you need, instead of re-deriving it. One-shot at birth: the fork resumes its own session thereafter.' },
             { kind: 'flag', name: 'model', type: 'enum', choices: ['ultra', 'strong', 'medium', 'light'], required: false, constraint: 'Override the model the node runs on, by capability TIER: ultra (frontier), strong (opus), medium (sonnet), light (haiku). Omit to use the kind\'s persona default (advisor=ultra, explore=light, most other builtins=strong). The override is durable — it survives revives and polymorphs (promote/demote).' },
+            { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Select the profile this node runs under — an exact profile id or a unique manifest name (see the <profiles> list below, or `crtr profile list`). Omit to INHERIT the calling node\'s current profile (root has none, so an uninherited child has none either). --root does NOT reset this — it only means top-level, still inherits/uses the selected profile unless this overrides it.' },
             { kind: 'flag', name: 'at', type: 'string', required: false, constraint: 'DEFER the birth to a one-shot clock trigger at this future time instead of spawning now — a duration ("5m","1h30m"), a zoned ISO ("2026-06-07T09:00:00Z"), or a bare ISO ("2026-06-07T09:00", host-local or in --tz). Required unless --every is given (the cadence then sets the first fire). Mutually exclusive with --when.' },
             { kind: 'flag', name: 'every', type: 'string', required: false, constraint: 'SPAWN-CRON: re-birth a fresh node on this cadence — a duration ("6h","30m") or a 5-field cron / @alias ("0 9 * * *","@daily"). Combine with --at to anchor the first fire, then recur normally. Min cadence 60s. With --when, this instead sets the PREDICATE EVALUATION cadence (required), not a repeating birth.' },
             { kind: 'flag', name: 'when', type: 'string', required: false, constraint: 'Arm a daemon-evaluated bash predicate instead of a clock trigger: exit 0 births the node once, non-zero leaves it armed for the next evaluation. Requires --every (eval cadence) and --timeout (wall-clock bound). Mutually exclusive with --at.' },
@@ -118,7 +145,7 @@ const nodeNew = defineLeaf({
             { name: 'recur', type: 'string', required: false, constraint: 'Cadence display ("every 6h", cron, or eval cadence for --when), present only when --every was given.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Decision road sign for the caller. Spawned now: the child runs independently and its finish wakes you on its own, so never wait or poll on it — either pick up other work now or end your turn (an orchestrator already deep in context is instead steered to `crtr node yield`). Armed: no node exists yet — inspect/cancel via `crtr node triggers list`/`cancel <id>`, then pick up other work or end your turn.' },
         ],
-        dynamicState: () => kindsStateBlock(),
+        dynamicState: () => [kindsStateBlock(), profilesStateBlock()].join('\n'),
         outputKind: 'object',
         effects: [
             'Spawning now: creates a node under ~/.crouter/canvas/nodes/<id>/ and indexes it in canvas.db. Default (managed child): parent auto-subscribes (active) and is woken on the child\'s pushes. With --root: no subscription — records a spawned_by edge for provenance only. Launches the node\'s engine as a detached broker (the only host); a managed child opens NO viewer, a --root opens one in your current tmux session.',
@@ -138,6 +165,7 @@ const nodeNew = defineLeaf({
         const root = input['root'] === true;
         const forkFrom = input['forkFrom'];
         const model = input['model'];
+        const profile = input['profile'];
         const at = input['at']?.trim();
         const every = input['every']?.trim();
         const whenRaw = input['when'];
@@ -156,7 +184,7 @@ const nodeNew = defineLeaf({
             throw new InputError({ error: 'tz_needs_clock', message: '--tz has no effect without --at or --every to parse it against', field: 'tz', next: 'Drop --tz, or pass --at/--every.' });
         }
         if (!triggered) {
-            const res = await spawnChild({ kind, mode, cwd, name, prompt, parent, root, forkFrom, model });
+            const res = await spawnChild({ kind, mode, cwd, name, prompt, parent, root, forkFrom, model, profile });
             return {
                 node_id: res.node.node_id,
                 name: res.node.name,
@@ -193,6 +221,7 @@ const nodeNew = defineLeaf({
             ...(root ? { root: true } : {}),
             ...(forkFrom !== undefined ? { forkFrom } : {}),
             ...(model !== undefined ? { model } : {}),
+            ...(profile !== undefined ? { profile } : {}),
         };
         const id = `tr-${newNodeId()}`;
         if (hasWhen) {
@@ -306,7 +335,7 @@ const nodeList = defineLeaf({
         summary: 'list nodes on the canvas, filtered by any combination of attribute slices and a graph-scope (--under) that AND together',
         params: [
             { kind: 'flag', name: 'status', type: 'string', required: false, constraint: 'Filter status (comma-separated for several; accepted values: active, idle, done, dead, canceled). NOTE: `active` means the engine process is live (never closed), NOT that the node is generating right now — an active node is usually dormant between turns. To tell working-vs-idle, check the pi session-file mtime or CPU, not status.' },
-            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Filter by persona kind (comma-separated for several). The <kinds> list below names every installable kind.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Filter by persona kind (comma-separated for several). The <kinds> list below names every top-level installable kind; a sub-kind (e.g. plan/reviewers/security) filters too even though it is not listed.' },
             { kind: 'flag', name: 'mode', type: 'string', required: false, constraint: 'Filter by mode (comma-separated for several; accepted values: base, orchestrator).' },
             { kind: 'flag', name: 'lifecycle', type: 'string', required: false, constraint: 'Filter by lifecycle (comma-separated for several; accepted values: terminal, resident).' },
             { kind: 'flag', name: 'cwd', type: 'string', required: false, constraint: 'Filter to nodes pinned to this exact cwd (absolute path). Roster is canvas-wide (all cwds) by default.' },
@@ -400,15 +429,15 @@ const nodeShow = defineLeaf({
     },
 });
 // ---------------------------------------------------------------------------
-// node inspect — read the graph (list, show, snapshot, context)
+// node inspect — read the graph (list, show, context)
 // ---------------------------------------------------------------------------
 const nodeInspect = defineBranch({
     name: 'inspect',
-    description: 'read the graph (list, show, snapshot, context)',
-    whenToUse: 'reading the graph: enumerate nodes on the canvas (`list`), inspect one and its spine neighbors (`show`), or pull a dormant session snapshot with `node inspect snapshot` / browse on-disk context dirs with `node inspect context` while reading a node. Use `canvas dashboard` instead to render the tree SHAPE, or `canvas attention` to find which nodes are blocked on a human',
+    description: 'read the graph (list, show, context)',
+    whenToUse: 'reading the graph: enumerate nodes on the canvas (`list`), inspect one and its spine neighbors (`show`), or browse on-disk context dirs with `node inspect context` while reading a node. Use `canvas dashboard` instead to render the tree SHAPE, or `canvas attention` to find which nodes are blocked on a human',
     help: {
         name: 'node inspect',
-        summary: 'read the canvas graph — enumerate nodes, inspect one, or pull snapshot/context views for a node (including dormant session snapshots and on-disk context dirs)',
+        summary: 'read the canvas graph — enumerate nodes, inspect one, or browse on-disk context dirs for a node',
     },
     children: [nodeList, nodeShow, nodeSnapshotLeaf, nodeContextLeaf],
 });
@@ -627,7 +656,7 @@ const nodeConfig = defineLeaf({
             { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id to resolve the node from. Defaults to $TMUX_PANE.' },
             { kind: 'flag', name: 'model', type: 'string', required: false, constraint: 'Model spec: exact provider/id, capability tier (ultra|strong|medium|light), family alias (opus|sonnet|haiku), or a free-text substring when the broker is live. Dormant nodes require a provider/id, tier, or alias.' },
             { kind: 'flag', name: 'lifecycle', type: 'enum', choices: ['terminal', 'resident'], required: false, constraint: 'Set lifecycle headlessly without closing the viewer. terminal owes a final and reaps when done; resident stays interactable and wakes on inbox/human.' },
-            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Persona kind. The <kinds> list below names every installable kind and when to use each.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Persona kind. The <kinds> list below names every top-level installable kind and when to use each; a sub-kind (e.g. plan/reviewers/security) is valid too by exact path but not listed here.' },
             { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, constraint: 'Set persona mode headlessly. base is hands-on; orchestrator holds a roadmap and delegates. orchestrator seeds a roadmap scaffold if absent.' },
             { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Rename the node; if the node has a live window, also rename that viewer window.' },
         ],
@@ -962,10 +991,10 @@ function resolveMsgTarget(input) {
 const nodeMsg = defineLeaf({
     name: 'msg',
     description: 'message any node now, or arm a trigger that messages/revives it later',
-    whenToUse: 'you want to address a specific node directly — steer it mid-flight, hand it a correction, ping it, pass it new information, or schedule any of that for later — regardless of subscriptions. Default delivers immediately and revives a dormant target; `--at`/`--every` arm a clock trigger instead of acting now; `--fresh` revives with no inbox entry; `--self --until` puts a deadline backstop on your current inbox-wait; `--when` arms a daemon-evaluated predicate for an external condition (CI, a deploy) you cannot otherwise be pushed for. Use `node subscribe` instead to wire ONGOING push delivery rather than a one-off, `push` to report UP your own spine, and `node new` to schedule the BIRTH of a node rather than message an existing one',
+    whenToUse: 'you want to address a specific node directly — steer it mid-flight, hand it a correction, ping it, pass it new information, or schedule any of that for later — regardless of subscriptions. Default delivers immediately and revives a dormant target; `--at`/`--every` arm a clock trigger instead of acting now; `--fresh` revives with no inbox entry; `--self --until` binds a deadline that changes your task policy if no push arrives by then; `--when` arms a daemon-evaluated predicate for an external condition (CI, a deploy) you cannot otherwise be pushed for. Use `node subscribe` instead to wire ONGOING push delivery rather than a one-off, `push` to report UP your own spine, and `node new` to schedule the BIRTH of a node rather than message an existing one',
     help: {
         name: 'node msg',
-        summary: 'message a node now, or arm a trigger (clock or predicate) that messages/revives it later. No trigger flag → immediate inbox delivery (or immediate fresh revive with --fresh). --at/--every → clock trigger. --self --until → self-only deadline backstop on the current inbox-wait. --when → daemon-evaluated predicate, fires once on exit 0',
+        summary: 'message a node now, or arm a trigger (clock or predicate) that messages/revives it later. No trigger flag → immediate inbox delivery (or immediate fresh revive with --fresh). --at/--every → clock trigger. --self --until → self-only deadline: fires whichever comes first, an inbox message or this time, and that outcome is what should change your next action. --when → daemon-evaluated predicate, fires once on exit 0',
         params: [
             { kind: 'stdin', name: 'body', required: false, constraint: 'Message body. Positional or stdin. Required for a plain or clock-triggered message and for --until. Forbidden with --fresh. Optional with --when — if omitted, the predicate\'s captured stdout becomes the body when it fires.' },
             { kind: 'flag', name: 'to', type: 'string', required: false, constraint: 'Target an existing node by id. Exactly one of --to/--self is required.' },
@@ -975,7 +1004,7 @@ const nodeMsg = defineLeaf({
             { kind: 'flag', name: 'at', type: 'string', required: false, constraint: 'Arm a one-shot clock trigger at this future time instead of acting now — a duration ("5m","1h30m"), a zoned ISO ("2026-06-07T09:00:00Z"), or a bare ISO ("2026-06-07T09:00", host-local or in --tz). Required unless --every is given (the cadence then sets the first fire). Mutually exclusive with --when.' },
             { kind: 'flag', name: 'every', type: 'string', required: false, constraint: 'Arm a recurring clock trigger on this cadence — a duration ("6h","30m") or a 5-field cron / @alias ("0 9 * * *","@daily"). Combine with --at to anchor the first fire, then recur normally. Min cadence 60s. With --when, this instead sets the PREDICATE EVALUATION cadence (required), not a repeating action.' },
             { kind: 'flag', name: 'when', type: 'string', required: false, constraint: 'Arm a daemon-evaluated bash predicate instead of a clock trigger: exit 0 fires the message once, non-zero leaves it armed for the next evaluation. Requires --every (eval cadence) and --timeout (wall-clock bound). Mutually exclusive with --at, --fresh, and --until.' },
-            { kind: 'flag', name: 'until', type: 'string', required: false, constraint: 'Self-only: bind a deadline to your current dormancy — you wake on the first inbox message, or at this time if none arrives (whichever fires first cancels the other). One-shot, urgent tier, ≤ 1 per node (a new --until replaces any prior). Mutually exclusive with --at, --every, --when, --fresh, --tier, and --timeout. Requires --self and a body.' },
+            { kind: 'flag', name: 'until', type: 'string', required: false, constraint: 'Self-only: bind a deadline that decides your next action — you wake on the first inbox message, or at this time if none arrives (whichever fires first cancels the other), and the body is the policy to follow in the no-message case. One-shot, urgent tier, ≤ 1 per node (a new --until replaces any prior). Mutually exclusive with --at, --every, --when, --fresh, --tier, and --timeout. Requires --self and a body.' },
             { kind: 'flag', name: 'timeout', type: 'string', required: false, constraint: 'Wall-clock bound for a --when predicate — a duration or absolute time after which the trigger is consumed and the owner gets one urgent notice. Required with --when; rejected otherwise.' },
             { kind: 'flag', name: 'tz', type: 'string', required: false, constraint: 'IANA zone for a calendar --every, a bare-ISO --at, or a bare-ISO --until (default: host-local). Valid only alongside --at/--every/--until; rejected with --when, and rejected when acting immediately (no trigger flags) since none of those have anything to parse it against.' },
         ],
@@ -1225,8 +1254,9 @@ const nodeMsg = defineLeaf({
         }
         const tier = (hasTier ? tierRaw : 'normal');
         const from = process.env['CRTR_NODE_ID'] ?? 'human';
-        // A long body clips in the receiver's digest; appendInbox mints a short `id`
-        // for it so the receiver can read the full text back via `feed message <id>`.
+        // A body over the preview bound spills to a ref file; appendInbox clips the
+        // inline preview and the receiver dereferences the ref for the full text,
+        // same as any other report.
         appendInbox(targetId, { from, tier, kind: 'message', label: body.split('\n')[0].slice(0, 120), data: { body: body } });
         // A direct message wakes any node: if the target has no live window
         // (done/dead/idle-released), revive it so its inbox-watcher delivers this.
@@ -1338,7 +1368,7 @@ const nodePromote = defineLeaf({
         name: 'node promote',
         summary: 'promote yourself to an orchestrator — do this when your task outgrows one context window (many phases to delegate and persist across refreshes); not for work that fits one window, and not merely because you spawned a child. Mode only — lifecycle stays as-is unless you pass --resident',
         params: [
-            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Specialize as this kind of orchestrator. The <kinds> list below names every installable kind and when to use each. For an exact composed persona list, use `crtr sys prompt-review --list --kind <kind>` with the target kind. Defaults to your current kind. Promoting from a generic kind? CHOOSE a concrete one — it sets the orchestrator persona you revive into.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Specialize as this kind of orchestrator. The <kinds> list below names every top-level installable kind and when to use each; a sub-kind (e.g. plan/reviewers/security) is valid too by exact path but not listed here. For an exact composed persona list, use `crtr sys prompt-review --list --kind <kind>` with the target kind. Defaults to your current kind. Promoting from a generic kind? CHOOSE a concrete one — it sets the orchestrator persona you revive into.' },
             { kind: 'flag', name: 'resident', type: 'bool', required: false, constraint: 'ALSO flip lifecycle→resident: make the node interactable — it stays dormant, woken by inbox/human, and is never forced to submit a final. Omit to stay terminal/orchestrator (delegates + holds a roadmap, but still owes a final up the spine and reaps when done).' },
             { kind: 'flag', name: 'model', type: 'enum', choices: ['ultra', 'strong'], required: false, constraint: 'Change the model you run on, by capability tier: `ultra` (frontier — reserve for high-taste judgment or enormous work: speccing, planning something large, e2e-testing something hard to test) or `strong` (opus — regular dev work). Omit to keep your current model. An orchestrator steering work is never weaker than opus, so these are the only two choices; the change is durable across future revives.' },
             { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node to promote. Defaults to the caller (CRTR_NODE_ID).' },
@@ -1510,7 +1540,7 @@ const nodeYield = defineLeaf({
 const nodeTriggersList = defineLeaf({
     name: 'list',
     description: 'list pending triggers for a scope (default self)',
-    whenToUse: 'before re-arming or finishing, to see what you already have armed and reap stale ones. Defaults to your own triggers, with a --node or --canvas scope for anything wider',
+    whenToUse: 'seeing what triggers (clock or predicate) are currently armed — your own, another node\'s, or the whole canvas. Defaults to your own triggers, with a --node or --canvas scope for anything wider',
     help: {
         name: 'node triggers list',
         summary: 'list pending triggers (clock and predicate, incl. deferred spawns) for a scope — id, owner, target, action/mode, type, next fire/eval, cadence, timeout, label, predicate diagnostics. Fired one-shots are gone; a recurrence shows its NEXT fire/eval, not past slots',
@@ -1602,7 +1632,7 @@ const nodeTriggersList = defineLeaf({
 const nodeTriggersCancel = defineLeaf({
     name: 'cancel',
     description: 'cancel a pending trigger by id (idempotent)',
-    whenToUse: 'a wait you no longer need — a poll whose goal is met, a deferred spawn you reconsidered, a deadline you are replacing. Idempotent: canceling an already-fired or already-canceled id is a no-op. Closing/reaping a node already reaps its own triggers and the detached ones it armed; reach for this to drop a single trigger, or to reap a detached spawn/cron a finished or crashed node left running',
+    whenToUse: 'a wait you no longer need — a poll whose goal is met, a deferred spawn you reconsidered, a deadline you are replacing. Idempotent: canceling an already-fired or already-canceled id is a no-op.',
     help: {
         name: 'node triggers cancel',
         summary: 'cancel a pending trigger by id — it never fires/evaluates again and leaves the list. Idempotent (canceling an already-gone id is a no-op, not an error)',

package/dist/commands/profile/add-project.d.ts

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

package/dist/commands/profile/add-project.js

@@ -0,0 +1,42 @@
+import { defineLeaf } from '../../core/command.js';
+import { addProfileProject, loadProfileManifest } from '../../core/profiles/manifest.js';
+export const addProjectLeaf = defineLeaf({
+    name: 'add-project',
+    description: "add a project directory to a profile's purview",
+    whenToUse: "a profile needs to see (memory + config from) another project directory — extend its purview after creation, including mid-session from a node already running under that profile.",
+    help: {
+        name: 'profile add-project',
+        summary: "append a project directory to a profile's manifest, deduped by real path",
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Exact profile id, or a unique manifest name.',
+            },
+            {
+                kind: 'flag',
+                name: 'dir',
+                type: 'path',
+                required: true,
+                constraint: 'Directory to add. Must exist and be a directory; resolved to its absolute real path before storing. A path already on the manifest is a no-op, not an error.',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'projects', type: 'string[]', required: true, constraint: 'The updated, deduped project list in manifest order.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ["Appends to the profile manifest's `projects` array. Invalidates the process scope cache."],
+    },
+    run: async (input) => {
+        const { profileId } = loadProfileManifest(input['profile']);
+        const { manifest } = addProfileProject(profileId, input['dir']);
+        return {
+            profile_id: profileId,
+            projects: manifest.projects,
+            follow_up: `Show the full manifest with \`crtr profile show ${profileId}\`.`,
+        };
+    },
+});

package/dist/commands/profile/delete.d.ts

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

package/dist/commands/profile/delete.js

@@ -0,0 +1,39 @@
+import { defineLeaf } from '../../core/command.js';
+import { deleteProfile, loadProfileManifest } from '../../core/profiles/manifest.js';
+export const deleteLeaf = defineLeaf({
+    name: 'delete',
+    description: 'remove a profile entirely',
+    whenToUse: 'a profile is no longer needed — deletes its manifest AND its own memory store irreversibly. Does not touch the project directories it pointed at.',
+    help: {
+        name: 'profile delete',
+        summary: 'remove a profile directory (manifest + memory store) after validating it exists',
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Exact profile id, or a unique manifest name.',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'The deleted profile\u2019s stable directory id.' },
+            { name: 'name', type: 'string', required: true, constraint: 'The deleted profile\u2019s manifest name.' },
+            { name: 'deleted', type: 'boolean', required: true, constraint: 'Always true on success.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Recursively removes `<profiles-root>/<profile_id>/` — the manifest and its own memory store. Irreversible. Invalidates the process scope cache.',
+        ],
+    },
+    run: async (input) => {
+        const { profileId, manifest } = loadProfileManifest(input['profile']);
+        deleteProfile(profileId);
+        return {
+            profile_id: profileId,
+            name: manifest.name,
+            deleted: true,
+            follow_up: 'Run `crtr profile list` to see remaining profiles.',
+        };
+    },
+});

package/dist/commands/profile/list.d.ts

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

package/dist/commands/profile/list.js

@@ -0,0 +1,35 @@
+import { defineLeaf } from '../../core/command.js';
+import { emitLine } from '../../core/io.js';
+import { listProfiles } from '../../core/profiles/manifest.js';
+export const listLeaf = defineLeaf({
+    name: 'list',
+    description: 'inventory every profile',
+    whenToUse: 'browse every profile that exists — one line each with its id, name, project count, and last-used time. Reach for `profile show` once you have picked one, for its full project list.',
+    help: {
+        name: 'profile list',
+        summary: 'every profile as JSONL, one line each, sorted by name then profile_id',
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'name', type: 'string', required: true, constraint: 'Manifest name.' },
+            { name: 'projects_count', type: 'int', required: true, constraint: 'Number of project directories on the manifest.' },
+            { name: 'last_used_at', type: 'string | null', required: true, constraint: 'ISO 8601 timestamp of the most recent selection, or null if never selected.' },
+        ],
+        outputKind: 'jsonl',
+        effects: ['None. Read-only.'],
+    },
+    run: async () => {
+        const all = listProfiles().sort((a, b) => {
+            const nc = a.manifest.name.localeCompare(b.manifest.name);
+            return nc !== 0 ? nc : a.profileId.localeCompare(b.profileId);
+        });
+        for (const { profileId, manifest } of all) {
+            emitLine({
+                profile_id: profileId,
+                name: manifest.name,
+                projects_count: manifest.projects.length,
+                last_used_at: manifest.last_used_at,
+            });
+        }
+        emitLine({ follow_up: 'Show one in full with `crtr profile show <profile>`.' });
+    },
+});

package/dist/commands/profile/new.d.ts

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

package/dist/commands/profile/new.js

@@ -0,0 +1,50 @@
+import { defineLeaf } from '../../core/command.js';
+import { createProfile, profileRoot } from '../../core/profiles/manifest.js';
+export const newLeaf = defineLeaf({
+    name: 'new',
+    description: 'create a new profile',
+    whenToUse: 'you are establishing a new agent identity — a stable id, a display name, and its own memory store. Pass at most one initial project directory here (the parser has no repeatable-flag support); use `profile add-project` afterward for every additional one.',
+    help: {
+        name: 'profile new',
+        summary: 'create a profile: `<profiles-root>/<slug>-<id>/` with a manifest + its own `memory/` store',
+        params: [
+            {
+                kind: 'flag',
+                name: 'name',
+                type: 'string',
+                required: true,
+                constraint: 'Display name for the profile. Also slugified into the stable profile id — the id never changes on later rename.',
+            },
+            {
+                kind: 'flag',
+                name: 'project',
+                type: 'path',
+                required: false,
+                constraint: 'One initial project directory. Must already exist and be a directory; resolved to its absolute real path before storing. Singular — add more with `crtr profile add-project` after creation.',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id (`<slug>-<shortid>`). Pass this, or the name, to every other `profile` verb and to `--profile` elsewhere.' },
+            { name: 'name', type: 'string', required: true, constraint: 'The manifest name as given.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the profile directory.' },
+            { name: 'projects', type: 'string[]', required: true, constraint: 'Resolved absolute project directories, in manifest order. Empty when --project was omitted.' },
+            { name: 'created_at', type: 'string', required: true, constraint: 'ISO 8601 creation timestamp.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ['Creates `<profile-dir>/profile.json` and `<profile-dir>/memory/`.'],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const project = input['project'];
+        const { profileId, manifest } = createProfile(name, project !== undefined ? [project] : []);
+        return {
+            profile_id: profileId,
+            name: manifest.name,
+            path: profileRoot(profileId),
+            projects: manifest.projects,
+            created_at: manifest.created_at,
+            follow_up: `Show it with \`crtr profile show ${profileId}\`, add another project with \`crtr profile add-project ${profileId} --dir <path>\`, or list every profile with \`crtr profile list\`.`,
+        };
+    },
+});

package/dist/commands/profile/remove-project.d.ts

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

package/dist/commands/profile/remove-project.js

@@ -0,0 +1,42 @@
+import { defineLeaf } from '../../core/command.js';
+import { loadProfileManifest, removeProfileProject } from '../../core/profiles/manifest.js';
+export const removeProjectLeaf = defineLeaf({
+    name: 'remove-project',
+    description: "remove a project directory from a profile's purview",
+    whenToUse: "a profile no longer needs purview over one of its listed project directories — narrow it back. Works even if the directory itself was since deleted.",
+    help: {
+        name: 'profile remove-project',
+        summary: "remove a project directory from a profile's manifest",
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Exact profile id, or a unique manifest name.',
+            },
+            {
+                kind: 'flag',
+                name: 'dir',
+                type: 'path',
+                required: true,
+                constraint: 'Directory to remove, matched by its resolved real path against the manifest. Does not require the directory to still exist on disk.',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'projects', type: 'string[]', required: true, constraint: 'The updated project list in manifest order.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ["Removes an entry from the profile manifest's `projects` array. Invalidates the process scope cache."],
+    },
+    run: async (input) => {
+        const { profileId } = loadProfileManifest(input['profile']);
+        const { manifest } = removeProfileProject(profileId, input['dir']);
+        return {
+            profile_id: profileId,
+            projects: manifest.projects,
+            follow_up: `Show the full manifest with \`crtr profile show ${profileId}\`.`,
+        };
+    },
+});

package/dist/commands/profile/rename.d.ts

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

package/dist/commands/profile/rename.js

@@ -0,0 +1,42 @@
+import { defineLeaf } from '../../core/command.js';
+import { loadProfileManifest, renameProfile } from '../../core/profiles/manifest.js';
+export const renameLeaf = defineLeaf({
+    name: 'rename',
+    description: "change a profile's display name",
+    whenToUse: "you want to change a profile's display name — the gateable `profile` subject value and the name shown in bearings/listings. The profile id (its directory) never changes.",
+    help: {
+        name: 'profile rename',
+        summary: "change a profile's manifest `name` only — the profile_id is stable and never changes",
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Exact profile id, or a unique manifest name (the CURRENT name, before this rename).',
+            },
+            {
+                kind: 'flag',
+                name: 'name',
+                type: 'string',
+                required: true,
+                constraint: 'New display name.',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id — unchanged by this leaf.' },
+            { name: 'name', type: 'string', required: true, constraint: 'The new manifest name.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ["Changes the profile manifest's `name` field. Invalidates the process scope cache."],
+    },
+    run: async (input) => {
+        const { profileId } = loadProfileManifest(input['profile']);
+        const { manifest } = renameProfile(profileId, input['name']);
+        return {
+            profile_id: profileId,
+            name: manifest.name,
+            follow_up: `Show the full manifest with \`crtr profile show ${profileId}\`.`,
+        };
+    },
+});

package/dist/commands/profile/show.d.ts

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

package/dist/commands/profile/show.js

@@ -0,0 +1,50 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineLeaf } from '../../core/command.js';
+import { loadProfileManifest, profileRoot } from '../../core/profiles/manifest.js';
+import { CONFIG_FILE } from '../../types.js';
+export const showLeaf = defineLeaf({
+    name: 'show',
+    description: "one profile's manifest in full",
+    whenToUse: "you need a profile's full project list, id, and timestamps — after `profile list` narrows to a name, or to inspect what a node's bearings named as its profile.",
+    help: {
+        name: 'profile show',
+        summary: "print one profile's manifest plus its on-disk path and config.json location",
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Exact profile id, or a unique manifest name. An ambiguous name fails listing every matching id.',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'name', type: 'string', required: true, constraint: 'Manifest name.' },
+            { name: 'projects', type: 'string[]', required: true, constraint: 'Absolute project directories, in manifest order.' },
+            { name: 'created_at', type: 'string', required: true, constraint: 'ISO 8601 creation timestamp.' },
+            { name: 'last_used_at', type: 'string | null', required: true, constraint: 'ISO 8601 timestamp of the most recent selection, or null if never selected.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the profile directory.' },
+            { name: 'config_path', type: 'string', required: true, constraint: 'Absolute path to the profile\'s config.json (hand-edited the same way as user/project config.json — no profile-specific editor verb exists).' },
+            { name: 'config_exists', type: 'boolean', required: true, constraint: 'Whether config.json exists at that path yet.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const { profileId, manifest } = loadProfileManifest(input['profile']);
+        const configPath = join(profileRoot(profileId), CONFIG_FILE);
+        return {
+            profile_id: profileId,
+            name: manifest.name,
+            projects: manifest.projects,
+            created_at: manifest.created_at,
+            last_used_at: manifest.last_used_at,
+            path: profileRoot(profileId),
+            config_path: configPath,
+            config_exists: existsSync(configPath),
+            follow_up: `Add a project with \`crtr profile add-project ${profileId} --dir <path>\`, or rename with \`crtr profile rename ${profileId} --name <name>\`.`,
+        };
+    },
+});

package/dist/commands/profile.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerProfile(): BranchDef;

package/dist/commands/profile.js

@@ -0,0 +1,33 @@
+// `crtr profile` subtree — the profile store (spec §2.1/§2.5): agent
+// identities defined at the user root, each owning a manifest naming project
+// directories plus its own memory store. Flat leaves; no sub-branches — 7
+// verbs fits the 5-7 hard cap.
+//
+// Every verb but `new`/`list` takes <profile> as an exact id OR a unique
+// manifest name (never two positionals: `add-project`/`remove-project` pair
+// <profile> with `--dir`, `rename` pairs it with `--name`, matching the
+// one-positional-per-leaf argv contract used across the whole tree).
+import { defineBranch } from '../core/command.js';
+import { newLeaf } from './profile/new.js';
+import { listLeaf } from './profile/list.js';
+import { showLeaf } from './profile/show.js';
+import { addProjectLeaf } from './profile/add-project.js';
+import { removeProjectLeaf } from './profile/remove-project.js';
+import { renameLeaf } from './profile/rename.js';
+import { deleteLeaf } from './profile/delete.js';
+export function registerProfile() {
+    return defineBranch({
+        name: 'profile',
+        rootEntry: {
+            concept: 'an agent identity defined at the user root — a manifest naming project directories plus its own memory store',
+            desc: 'create, inspect, and manage profiles',
+            useWhen: 'creating a new agent identity, inspecting or listing existing ones, or changing a profile\u2019s project purview or display name. Selecting a profile for a running node (`--profile`, startup selection) lives elsewhere; this family only manages the manifest.',
+        },
+        help: {
+            name: 'profile',
+            summary: 'create, inspect, and manage profiles \u2014 agent identities with their own project purview and memory store',
+            model: '`new` creates one from a name (+ at most one initial `--project`). `list` inventories every profile as JSONL. `show` prints one manifest in full. `add-project` / `remove-project` mutate the ordered project list after creation, including mid-session on an already-running profile. `rename` changes only the manifest name \u2014 the profile_id is stable across a rename. `delete` removes a profile\u2019s directory (manifest + its own memory store) entirely and does not touch the project directories it pointed at. Every verb but `new`/`list` takes <profile> as an exact id or a unique manifest name; an ambiguous name fails listing every matching id.',
+        },
+        children: [newLeaf, listLeaf, showLeaf, addProjectLeaf, removeProjectLeaf, renameLeaf, deleteLeaf],
+    });
+}

package/dist/commands/push.d.ts

@@ -2,4 +2,3 @@ import type { BranchDef } from '../core/command.js';
 import { InputError } from '../core/io.js';
 export declare function mapFinalizeTransitionRaceError(nodeStatus: string | null | undefined, err: unknown): InputError | null;
 export declare function registerPush(): BranchDef;
-export declare function registerFeed(): BranchDef;