@crouton-kit/crouter 0.3.28 → 0.3.30

package/dist/commands/node.js

@@ -6,7 +6,6 @@
 // the spine (`focus`/`msg`). The push/feed half lives under `crtr push`.
 import { defineLeaf, defineBranch } from '../core/command.js';
 import { InputError } from '../core/io.js';
-import { readConfig } from '../core/config.js';
 import { spawnChild } from '../core/runtime/spawn.js';
 import { promote, requestYield } from '../core/runtime/promote.js';
 import { writeYieldMessage, readGoal } from '../core/runtime/kickoff.js';
@@ -99,7 +98,7 @@ function callerSubPersonasBlock() {
     }
 }
 // ---------------------------------------------------------------------------
-// node new — spawn a terminal worker as a background window under the root
+// node new — spawn a terminal worker as a detached headless broker under the root
 // ---------------------------------------------------------------------------
 const nodeNew = defineLeaf({
     name: 'new',
@@ -108,7 +107,7 @@ const nodeNew = defineLeaf({
     tier: 'important',
     help: {
         name: 'node new',
-        summary: 'spawn a terminal worker onto the canvas as a background window — returns its node id',
+        summary: 'spawn a terminal worker onto the canvas as a detached broker — returns its node id',
         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; the <sub-personas> block (when present) names the specialist sub-personas available to YOU, each spawnable by its full kind string (e.g. plan/reviewers/security).' },
@@ -118,14 +117,13 @@ const nodeNew = defineLeaf({
             { kind: 'flag', name: 'parent', type: 'string', required: false, constraint: 'Parent node id. Defaults to the calling node (CRTR_NODE_ID).' },
             { 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: 'headless', type: 'bool', required: false, constraint: 'Spawn the node on the HEADLESS broker host (no tmux pane) instead of a tmux window. Overrides the `headless` config default for this spawn; omit to use that default (which itself defaults to a tmux pane).' },
             { 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 (explore=light, every other kind=strong). The override is durable — it survives revives and polymorphs (promote/demote).' },
         ],
         output: [
             { name: 'node_id', type: 'string', required: true, constraint: 'The new node id.' },
             { name: 'name', type: 'string', required: true, constraint: 'Display name.' },
-            { name: 'window', type: 'string', required: false, constraint: 'tmux window id of the background window.' },
-            { name: 'session', type: 'string', required: true, constraint: 'The tmux session the node was placed in — the shared crtr session for a child; your current session for an in-tmux --root.' },
+            { name: 'window', type: 'string', required: false, constraint: 'tmux window id of the viewer opened for an in-tmux --root (a `crtr attach` view onto the node\'s broker); absent for a managed child, which opens no viewer on spawn.' },
+            { name: 'session', type: 'string', required: false, constraint: 'The tmux session a --root\'s viewer opened into (your current session); absent for a managed child and for a --root spawned outside tmux.' },
             { name: 'status', type: 'string', required: true, constraint: 'Always "active" on spawn.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Decision road sign for the caller: 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. If you are an orchestrator already deep in context (>100k), it instead steers you to `crtr node yield` now so your fresh revive absorbs the child\'s result. Read it, then act.' },
         ],
@@ -134,7 +132,7 @@ const nodeNew = defineLeaf({
         effects: [
             '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.',
-            'Opens a tmux window running pi: a background (non-focus-stealing) window in the shared crtr session for a child; with --root, a new window in your current session (in-tmux) or the shared session (outside tmux), with the client switched to it.',
+            'Launches the node\'s engine as a detached broker (the only host). A managed child opens NO viewer — it runs headless and you open one on demand via `crtr node focus` / `crtr attach`. With --root inside tmux, opens one viewer window in your CURRENT session and switches the client to it so the root can be driven directly; outside tmux a --root opens no viewer.',
         ],
     },
     run: async (input) => {
@@ -150,17 +148,15 @@ const nodeNew = defineLeaf({
         const root = input['root'] === true;
         const forkFrom = input['forkFrom'];
         const model = input['model'];
-        // Host precedence: explicit --headless flag > config `headless` default > tmux.
-        const hostKind = input['headless'] === true ? 'broker' : readConfig('user').headless === true ? 'broker' : 'tmux';
-        const res = spawnChild({ kind, mode, cwd, name, prompt, parent, root, forkFrom, hostKind, model });
+        const res = spawnChild({ kind, mode, cwd, name, prompt, parent, root, forkFrom, model });
         return {
             node_id: res.node.node_id,
             name: res.node.name,
             window: res.window ?? undefined,
-            session: res.session,
+            session: res.session ?? undefined,
             status: res.node.status,
             follow_up: root
-                ? "Independent root spawned — it is NOT under you. You are not subscribed, so its finish will NOT wake you and it does not hold you alive; it carries spawned_by=you for lineage only. It opened in its own window and the client was switched to it so it can be driven directly. Hand it off and move on — you will not be notified of its progress."
+                ? "Independent root spawned — it is NOT under you. You are not subscribed, so its finish will NOT wake you and it does not hold you alive; it carries spawned_by=you for lineage only. Inside tmux it opened a viewer in your current session (the client switched to it) so it can be driven directly. Hand it off and move on — you will not be notified of its progress."
                 : childFollowUp(parent ?? process.env['CRTR_NODE_ID']),
         };
     },
@@ -184,7 +180,7 @@ const nodeList = defineLeaf({
         name: 'node inspect list',
         summary: 'list nodes on the canvas, optionally by status',
         params: [
-            { kind: 'flag', name: 'status', type: 'string', required: false, constraint: 'Filter: active | idle | done | dead | canceled. Comma-separated for several.' },
+            { kind: 'flag', name: 'status', type: 'string', required: false, constraint: 'Filter: active | idle | done | dead | canceled. Comma-separated for several. 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.' },
         ],
         output: [
             { name: 'nodes', type: 'object[]', required: true, constraint: 'Rows: {node_id, name, kind, mode, lifecycle, status, cwd, parent, created}.' },
@@ -243,28 +239,28 @@ const nodeInspect = defineBranch({
     children: [nodeList, nodeShow],
 });
 // ---------------------------------------------------------------------------
-// node focus — bring a node's window forefront (across roots if needed)
+// node focus — bring a node's viewer forefront (across roots if needed)
 // ---------------------------------------------------------------------------
 const nodeFocus = defineLeaf({
     name: 'focus',
-    description: 'bring a node window forefront',
-    whenToUse: 'you want to bring a specific node into view — swapped into your current pane — to watch or steer it directly, reviving it first if dormant. Use `node cycle` instead to walk neighbors one window at a time rather than jump to a named node, and `node msg` to steer a node without leaving where you are',
+    description: 'bring a node\'s viewer forefront',
+    whenToUse: 'you want to bring a specific node into view — open or move its viewer beside your current pane — to watch or steer it directly, reviving its broker first if dormant. Use `node cycle` instead to walk neighbors one viewer at a time rather than jump to a named node, and `node msg` to steer a node without leaving where you are',
     help: {
         name: 'node focus',
-        summary: 'bring a node into your CURRENT pane in place (swap-pane) — the agent appears where you are instead of navigating you to its window',
+        summary: 'bring a node\'s viewer forefront — open a `crtr attach` view onto the node\'s broker beside your current pane, or navigate to its existing viewer. The engine runs on the broker (the only host); the pane is just a window onto it.',
         params: [
             { kind: 'positional', name: 'node', required: true, constraint: 'Node id to focus.' },
-            { kind: 'flag', name: 'new-pane', type: 'bool', required: false, constraint: 'Open the node in a NEW viewport SIDE-BY-SIDE with your current pane (a second focus) instead of swapping it into your pane. Two agents on screen at once (F4).' },
-            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id to focus INTO (default: caller TMUX_PANE). Used by the canvas browser popup to focus back into the originating pane.' },
+            { kind: 'flag', name: 'new-pane', type: 'bool', required: false, constraint: 'Always open a NEW viewer SIDE-BY-SIDE with your current pane instead of moving/reusing the node\'s existing viewer. Two agents on screen at once (F4).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id to focus beside (default: caller TMUX_PANE). Used by the canvas browser popup to focus back into the originating pane.' },
         ],
         output: [
-            { name: 'focused', type: 'boolean', required: true, constraint: 'True when the node was brought into view.' },
-            { name: 'session', type: 'string', required: false, constraint: 'The tmux session the node lives in.' },
-            { name: 'revived', type: 'boolean', required: true, constraint: 'True when a dormant node was revived to be focused.' },
-            { name: 'in_place', type: 'boolean', required: true, constraint: 'True when the node was swapped into the caller pane; false when it fell back to window focus (no caller pane).' },
+            { name: 'focused', type: 'boolean', required: true, constraint: 'True when the node\'s viewer was brought into view.' },
+            { name: 'session', type: 'string', required: false, constraint: 'The tmux session the viewer lives in.' },
+            { name: 'revived', type: 'boolean', required: true, constraint: 'True when a dormant node\'s broker was relaunched to be focused.' },
+            { name: 'in_place', type: 'boolean', required: true, constraint: 'True when an existing viewer was navigated to (no new pane); false when a fresh viewer pane was opened or moved beside you.' },
         ],
         outputKind: 'object',
-        effects: ['Swaps the node\'s pane into the caller\'s current pane (tmux swap-pane -d) and retargets the caller\'s focus to it (focus pointer updated).', 'With --new-pane: splits a new viewport beside the caller (a second live focus) instead of swapping in place.', 'Revives a dormant node (resume) into the backstage if it has no live pane, then swaps it into the focus.'],
+        effects: ['Ensures the node\'s broker engine is alive (revives it if dormant) and opens/moves its one viewer pane (a `crtr attach` view) beside the caller, or navigates to it if a live viewer already sits in the caller\'s session.', 'With --new-pane: always splits a fresh viewer beside the caller (two agents on screen) instead of reusing the existing viewer.'],
     },
     run: async (input) => {
         const id = input['node'];
@@ -282,14 +278,13 @@ const nodeFocus = defineLeaf({
                 next: `The pending question is already on the human's screen; see it with \`crtr human list\` / \`crtr human inbox\`, or retract it with \`crtr human cancel ${id}\`.`,
             });
         }
-        // Placement owns the whole act (§2.3): resolve the caller's focus (or open a
-        // new viewport with --new-pane), revive the target into the backstage if it
-        // is dormant, then hot-swap it onto the focus. The reviver is injected so
-        // placement need not import revive.ts.
+        // Placement owns the whole act: ensure the target's broker engine is alive
+        // (revive it if dormant), then open/move its one viewer pane beside the
+        // caller (or split a fresh viewer with --new-pane). The reviver is injected
+        // so placement need not import revive.ts.
         const res = placementFocus(id, {
             pane: input['pane'],
             newPane: input['newPane'] === true,
-            callerNode: process.env['CRTR_NODE_ID'],
             revive: (nid) => { reviveNode(nid, { resume: true }); },
         });
         return { focused: res.focused, session: res.session, revived: res.revived, in_place: res.inPlace };
@@ -314,7 +309,7 @@ function nodeByWindow(win) {
 /** The live node "in front of you" in a tmux pane, HOST-AGNOSTIC. Defaults to
  *  $TMUX_PANE / the caller's current pane when `pane` is omitted — shared by
  *  `node recycle` / `node demote` / `node lifecycle` / `node close` / `node
- *  cycle`, and the `canvas chord` / `canvas tmux-spread` leaves.
+ *  cycle`, and the `canvas chord` leaf.
  *
  *  Two resolutions, tried in order:
  *    1. VIEWER pane (broker host): a `crtr attach` viewer self-tags its pane with
@@ -483,11 +478,11 @@ function liveDfsOrder() {
 }
 const nodeCycle = defineLeaf({
     name: 'cycle',
-    description: 'DFS-walk to the next/prev live node in place',
-    whenToUse: 'sweeping the canvas one window at a time, descending into children before siblings (bound to Alt+] forward / Alt+[ back). Use `node focus` instead to jump straight to a named node',
+    description: 'DFS-walk to the next/prev live node\'s viewer',
+    whenToUse: 'sweeping the canvas one viewer at a time, descending into children before siblings (bound to Alt+] forward / Alt+[ back). Use `node focus` instead to jump straight to a named node',
     help: {
         name: 'node cycle',
-        summary: 'focus the next/previous live node in DFS pre-order — the canvas walked one window at a time, descending into a node\'s children before its siblings (bound to Alt+] forward / Alt+[ back)',
+        summary: 'focus the next/previous live node\'s viewer in DFS pre-order — the canvas walked one viewer at a time, descending into a node\'s children before its siblings (bound to Alt+] forward / Alt+[ back)',
         params: [
             { kind: 'flag', name: 'dir', type: 'enum', choices: ['next', 'prev'], required: false, default: 'next', constraint: 'Direction along the pre-order: next (Alt+], rightward/deeper into children) or prev (Alt+[, back). Wraps at the ends.' },
             { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane to cycle FROM. Defaults to $TMUX_PANE / your current pane. The Alt+] / Alt+[ bindings pass this for you.' },
@@ -499,7 +494,7 @@ const nodeCycle = defineLeaf({
             { name: 'from', type: 'string', required: false, constraint: 'The node you cycled away from.' },
         ],
         outputKind: 'object',
-        effects: ['Swaps the neighbor\'s pane into the caller pane (like `node focus`); the node you were viewing drops to the background.', 'Revives the neighbor first if its window was released.'],
+        effects: ['Brings the neighbor\'s viewer forefront beside the caller (like `node focus`); the viewer you were watching drops to the background.', 'Relaunches the neighbor\'s broker first if it was dormant.'],
     },
     run: async (input) => {
         const pane = input['pane'] ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane ?? undefined;
@@ -516,12 +511,10 @@ const nodeCycle = defineLeaf({
         const target = getNode(targetId);
         if (target === null)
             return { focused: false, from: fromId };
-        // Placement retargets the caller pane's focus to the neighbor (§2.3),
-        // reviving it into the backstage first if its pane was released. callerNode
-        // is the node we cycled AWAY from — the current occupant of the caller pane.
+        // Placement brings the neighbor's viewer forefront beside the caller,
+        // relaunching its broker engine first if it was dormant.
         const res = placementFocus(targetId, {
             pane,
-            callerNode: fromId,
             revive: (nid) => { reviveNode(nid, { resume: true }); },
         });
         return { focused: res.focused, node_id: targetId, name: target.name, from: fromId };
@@ -666,12 +659,14 @@ const nodePromote = defineLeaf({
         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; the <sub-personas> block (when present) names the specialist sub-personas available to YOU, spawnable by full kind string. 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).' },
         ],
         output: [
             { name: 'node_id', type: 'string', required: true, constraint: 'The promoted node.' },
             { name: 'kind', type: 'string', required: true, constraint: 'The kind it now orchestrates as.' },
             { name: 'mode', type: 'string', required: true, constraint: 'Now "orchestrator".' },
+            { name: 'model', type: 'string', required: false, constraint: 'The model tier it now runs on, present only when you changed it with --model.' },
             { name: 'lifecycle', type: 'string', required: true, constraint: '"resident" if you passed --resident, else unchanged (typically "terminal").' },
             { name: 'roadmap_written', type: 'boolean', required: true, constraint: 'True if a roadmap scaffold was seeded by this call.' },
             { name: 'roadmap_path', type: 'string', required: true, constraint: 'Absolute path to your roadmap doc (context/roadmap.md) — edit it to author your plan.' },
@@ -679,7 +674,7 @@ const nodePromote = defineLeaf({
         ],
         dynamicState: () => kindsStateBlock(),
         outputKind: 'object',
-        effects: ['Flips mode→orchestrator + kind→chosen (lifecycle unchanged unless --resident, which also flips lifecycle→resident); rewrites the launch spec to that kind\'s orchestrator persona; seeds context/roadmap.md scaffold if absent.', 'Your new-role guidance is injected automatically at the turn boundary by the persona injector — the command no longer returns it.'],
+        effects: ['Flips mode→orchestrator + kind→chosen (lifecycle unchanged unless --resident, which also flips lifecycle→resident); --model durably pins the model tier; rewrites the launch spec to that kind\'s orchestrator persona; seeds context/roadmap.md scaffold if absent.', 'Your new-role guidance is injected automatically at the turn boundary by the persona injector — the command no longer returns it.'],
     },
     run: async (input) => {
         const id = input['node'] ?? process.env['CRTR_NODE_ID'];
@@ -688,9 +683,10 @@ const nodePromote = defineLeaf({
         const kind = input['kind'];
         if (kind !== undefined)
             assertKind(kind);
+        const model = input['model'];
         const resident = input['resident'] === true;
-        const res = promote(id, { ...(kind !== undefined ? { kind } : {}), ...(resident ? { resident: true } : {}) });
-        return { node_id: res.meta.node_id, kind: res.meta.kind, mode: res.meta.mode, lifecycle: res.meta.lifecycle, roadmap_written: res.roadmapWritten, roadmap_path: res.roadmapPath, goal_path: res.goalPath };
+        const res = promote(id, { ...(kind !== undefined ? { kind } : {}), ...(resident ? { resident: true } : {}), ...(model !== undefined ? { model } : {}) });
+        return { node_id: res.meta.node_id, kind: res.meta.kind, mode: res.meta.mode, lifecycle: res.meta.lifecycle, ...(res.meta.model_override != null ? { model: res.meta.model_override } : {}), roadmap_written: res.roadmapWritten, roadmap_path: res.roadmapPath, goal_path: res.goalPath };
     },
 });
 // ---------------------------------------------------------------------------
@@ -713,8 +709,8 @@ function resolveLifecycleNode(input, pane) {
         throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
     return id;
 }
-/** Set a node's lifecycle axis and, with `detach`, relocate its still-running
- *  pane to the background crtr session. Rebuilds the launch spec so a future
+/** Set a node's lifecycle axis and, with `detach`, close its foreground viewer
+ *  pane (the broker engine keeps running). Rebuilds the launch spec so a future
  *  revive comes back with the new lifecycle's prompt baked in (the live session
  *  is steered by the persona injector; this fixes the static prompt the daemon
  *  replays). Spine is fixed by parent-ness, so it carries through unchanged.
@@ -728,9 +724,9 @@ function setLifecycle(id, value, opts) {
         model: target.model_override ?? undefined,
     });
     const meta = updateNode(id, { lifecycle: value, launch });
-    // --detach: shove the still-running agent into the background crtr session,
-    // freeing the foreground pane. The pi is untouched (it keeps generating); now
-    // terminal, it pushes a final up the spine when it finishes.
+    // --detach: stop foregrounding the agent by closing its viewer pane (the
+    // broker engine keeps generating off-screen); now terminal, it pushes a final
+    // up the spine when it finishes, and a later `focus` reattaches a viewer.
     let detached = false;
     if (opts.detach === true)
         detached = detachToBackground(id, opts.pane);
@@ -745,23 +741,23 @@ function setLifecycle(id, value, opts) {
 // ---------------------------------------------------------------------------
 const nodeDemote = defineLeaf({
     name: 'demote',
-    description: 'demote a node to terminal in place; it stays focused and running but now owes a final; --detach also sends it to the backstage crtr session',
-    whenToUse: 'you are watching a resident/interactive node and want to put it on a finishing track WITHOUT disturbing it: flip it terminal IN PLACE — it keeps its pane and your focus, keeps running, but now owes a final report up the spine and reaps when done. The friendly counterpart to `node promote`. You can also let go entirely and send the still-running agent off-screen to finish in the background. Use `node recycle` instead to FINISH it now and reboot a fresh root in its pane, and `node lifecycle` for the orthogonal low-level flip (incl. terminal→resident)',
+    description: 'demote a node to terminal in place; it stays focused and running but now owes a final; --detach also closes its viewer (broker keeps running off-screen)',
+    whenToUse: 'you are watching a resident/interactive node and want to put it on a finishing track WITHOUT disturbing it: flip it terminal IN PLACE — it keeps its viewer and your focus, keeps running, but now owes a final report up the spine and reaps when done. The friendly counterpart to `node promote`. You can also let go entirely and close its viewer so the agent finishes off-screen on its broker. Use `node recycle` instead to FINISH it now and reboot a fresh root in its pane, and `node lifecycle` for the orthogonal low-level flip (incl. terminal→resident)',
     help: {
         name: 'node demote',
-        summary: 'demote a node to terminal IN PLACE — it stays focused and running but now owes a final up the spine and reaps when done. Pairs with `node promote` (mode↑); `--detach` also relocates the still-running agent to the background crtr session',
+        summary: 'demote a node to terminal IN PLACE — it stays focused and running but now owes a final up the spine and reaps when done. Pairs with `node promote` (mode↑); `--detach` also closes its viewer (the broker engine keeps running off-screen)',
         params: [
             { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node to demote. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
             { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id whose node to demote, when --node is omitted. Defaults to $TMUX_PANE. The Alt+C menu passes this for you.' },
-            { kind: 'flag', name: 'detach', type: 'bool', required: false, constraint: 'After flipping terminal, send the still-running agent to the background crtr session (break its pane out of the foreground). The pi keeps generating and — now terminal — pushes a final up the spine when done. The Alt+C → D move.' },
+            { kind: 'flag', name: 'detach', type: 'bool', required: false, constraint: 'After flipping terminal, stop foregrounding the agent by closing its viewer pane. The broker engine keeps generating off-screen and — now terminal — pushes a final up the spine when done; a later `focus` reattaches a viewer. The Alt+C → D move.' },
         ],
         output: [
             { name: 'node_id', type: 'string', required: true, constraint: 'The demoted node.' },
             { name: 'lifecycle', type: 'string', required: true, constraint: 'Always "terminal" after a demote.' },
-            { name: 'detached', type: 'boolean', required: false, constraint: 'True when --detach relocated the agent to the background crtr session.' },
+            { name: 'detached', type: 'boolean', required: false, constraint: 'True when --detach closed the agent\'s viewer pane (broker keeps running).' },
         ],
         outputKind: 'object',
-        effects: ['Flips the node\'s lifecycle→terminal and rebuilds its launch spec so a future revive boots terminal — it stays focused and running, now owing a final up the spine.', 'The persona injector delivers the transition guidance at the next turn boundary (or on the node\'s next revive if it is dormant).', 'With --detach: relocates the agent\'s live pane to the background crtr session (break-pane) WITHOUT killing the pi — it keeps generating off-screen.'],
+        effects: ['Flips the node\'s lifecycle→terminal and rebuilds its launch spec so a future revive boots terminal — it stays focused and running, now owing a final up the spine.', 'The persona injector delivers the transition guidance at the next turn boundary (or on the node\'s next revive if it is dormant).', 'With --detach: closes the agent\'s viewer pane WITHOUT touching the broker engine — it keeps generating off-screen, reconnectable by a later `focus`.'],
     },
     run: async (input) => {
         const pane = input['pane'] ?? process.env['TMUX_PANE'];
@@ -769,7 +765,7 @@ const nodeDemote = defineLeaf({
         const res = setLifecycle(id, 'terminal', { pane, detach: input['detach'] === true });
         return { node_id: res.node_id, lifecycle: res.lifecycle, detached: res.detached };
     },
-    render: (r) => `Demoted ${r['node_id']} — lifecycle now ${r['lifecycle']} (in place)${r['detached'] === true ? ', relocated to the background crtr session' : ''}.`,
+    render: (r) => `Demoted ${r['node_id']} — lifecycle now ${r['lifecycle']} (in place)${r['detached'] === true ? ', viewer closed (broker still running off-screen)' : ''}.`,
 });
 // ---------------------------------------------------------------------------
 // node lifecycle — flip the lifecycle axis (terminal ↔ resident), independent
@@ -781,20 +777,20 @@ const nodeLifecycle = defineLeaf({
     whenToUse: 'you want to flip a node\'s LIFECYCLE independent of its mode: make a node RESIDENT so it becomes interactable — it stays dormant, wakes on inbox/human, and is never forced to submit a final; or make a node TERMINAL so it owes a final result up the spine and reaps when done. Orthogonal to `node promote`, which changes MODE (base↔orchestrator), not lifecycle. You can also let go of a still-running agent and send it off-screen to finish in the background. For the human-driver flip-to-terminal pair reach for `node demote` (the friendly terminal-only skin over this)',
     help: {
         name: 'node lifecycle',
-        summary: 'set a node\'s lifecycle axis — terminal (owes a final up the spine, reaps when done) or resident (interactable, stays dormant, woken by inbox/human, never forced to submit). Orthogonal to mode; promotion does not touch it. `--detach` also relocates a live agent to the background crtr session',
+        summary: 'set a node\'s lifecycle axis — terminal (owes a final up the spine, reaps when done) or resident (interactable, stays dormant, woken by inbox/human, never forced to submit). Orthogonal to mode; promotion does not touch it. `--detach` also closes a live agent\'s viewer (broker keeps running off-screen)',
         params: [
             { kind: 'positional', name: 'lifecycle', required: true, constraint: 'terminal | resident.' },
             { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node to change. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
             { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id whose node to change, when --node is omitted. Defaults to $TMUX_PANE. The Alt+C menu passes this for you.' },
-            { kind: 'flag', name: 'detach', type: 'bool', required: false, constraint: 'After flipping lifecycle, send the still-running agent to the background crtr session (break its pane out of the foreground). The pi keeps generating and — now terminal — pushes a final up the spine when done. The human-driver "I am done foregrounding this" move (Alt+C → D).' },
+            { kind: 'flag', name: 'detach', type: 'bool', required: false, constraint: 'After flipping lifecycle, stop foregrounding the agent by closing its viewer pane. The broker engine keeps generating off-screen and — now terminal — pushes a final up the spine when done; a later `focus` reattaches a viewer. The human-driver "I am done foregrounding this" move (Alt+C → D).' },
         ],
         output: [
             { name: 'node_id', type: 'string', required: true, constraint: 'The node.' },
             { name: 'lifecycle', type: 'string', required: true, constraint: 'Its new lifecycle (terminal | resident).' },
-            { name: 'detached', type: 'boolean', required: false, constraint: 'True when --detach relocated the agent to the background crtr session.' },
+            { name: 'detached', type: 'boolean', required: false, constraint: 'True when --detach closed the agent\'s viewer pane (broker keeps running).' },
         ],
         outputKind: 'object',
-        effects: ['Sets lifecycle on the node meta and rebuilds its launch spec so a future revive boots with the new lifecycle\'s prompt baked in.', 'The persona injector delivers the transition guidance at the next turn boundary (or on the node\'s next revive if it is dormant).', 'With --detach: relocates the agent\'s live pane to the background crtr session (break-pane) WITHOUT killing the pi — it keeps generating in the background.'],
+        effects: ['Sets lifecycle on the node meta and rebuilds its launch spec so a future revive boots with the new lifecycle\'s prompt baked in.', 'The persona injector delivers the transition guidance at the next turn boundary (or on the node\'s next revive if it is dormant).', 'With --detach: closes the agent\'s viewer pane WITHOUT touching the broker engine — it keeps generating off-screen, reconnectable by a later `focus`.'],
     },
     run: async (input) => {
         const value = input['lifecycle']?.trim().toLowerCase();
@@ -806,7 +802,7 @@ const nodeLifecycle = defineLeaf({
         const res = setLifecycle(id, value, { pane, detach: input['detach'] === true });
         return { node_id: res.node_id, lifecycle: res.lifecycle, detached: res.detached };
     },
-    render: (r) => `Set ${r['node_id']} lifecycle → ${r['lifecycle']}${r['detached'] === true ? ', relocated to the background crtr session' : ''}.`,
+    render: (r) => `Set ${r['node_id']} lifecycle → ${r['lifecycle']}${r['detached'] === true ? ', viewer closed (broker still running off-screen)' : ''}.`,
 });
 // ---------------------------------------------------------------------------
 // node yield — refresh: discard context, revive fresh against the roadmap
@@ -814,21 +810,23 @@ const nodeLifecycle = defineLeaf({
 const nodeYield = defineLeaf({
     name: 'yield',
     description: 'refresh your context against your roadmap',
-    whenToUse: 'your context window is filling up but the mandate is unfinished: request a refresh — end your turn and revive fresh against your roadmap, leaving a note to your future self for the moment you wake. A base node auto-promotes to orchestrator first (a yield needs a roadmap to refresh against). Use `node promote` instead when you need to BECOME an orchestrator with no refresh pending',
+    whenToUse: 'your context window is filling up but the mandate is unfinished: request a refresh — end your turn and revive fresh against your roadmap, leaving a note to your future self for the moment you wake. A base node auto-promotes to orchestrator first (a yield needs a roadmap to refresh against). You may also respecialize (--kind) or raise your model (--model) as you refresh. Use `node promote` instead when you need to BECOME an orchestrator with no refresh pending',
     help: {
         name: 'node yield',
-        summary: 'request a context refresh — you will be respawned fresh against your roadmap on your next stop (a base node auto-promotes to orchestrator first)',
+        summary: 'request a context refresh — you will be respawned fresh against your roadmap on your next stop (a base node auto-promotes to orchestrator first); optionally change your kind or model as you refresh',
         params: [
-            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'If this yield auto-promotes a base node, specialize it as this kind of orchestrator (developer, review, spec, design, plan, explore, general). Defaults to your current kind.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Respecialize as you refresh — change your kind to this (developer, review, spec, design, plan, explore, general); a base node also auto-promotes into an orchestrator of this kind. Defaults to your current kind.' },
+            { kind: 'flag', name: 'model', type: 'enum', choices: ['ultra', 'strong'], required: false, constraint: 'Change the model your fresh revive runs 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. A node steering work is never weaker than opus, so these are the only two choices; the change is durable across future revives.' },
             { kind: 'stdin', name: 'message', required: true, constraint: 'A note to your future self — what to do the moment you wake fresh. Surfaced as <yield-message> in the next revive. Pass as a positional or pipe via heredoc.' },
         ],
         output: [
             { name: 'node_id', type: 'string', required: true, constraint: 'The yielding node.' },
             { name: 'promoted', type: 'boolean', required: true, constraint: 'True if this yield promoted a base node to orchestrator.' },
+            { name: 'model', type: 'string', required: false, constraint: 'The model tier your fresh revive will run on, present only when you changed it with --model.' },
             { name: 'will_refresh', type: 'boolean', required: true, constraint: 'Always true: end your turn and you will revive fresh against your roadmap.' },
         ],
         outputKind: 'object',
-        effects: ['Sets intent=refresh; the stophook shuts the process down on next stop and the daemon revives it fresh.'],
+        effects: ['Sets intent=refresh; the stophook shuts the process down on next stop and the daemon revives it fresh.', '--kind and/or --model durably reshape the node (kind respecialization, model-tier pin) before the refresh-revive; a base node also auto-promotes to orchestrator.'],
     },
     run: async (input) => {
         const id = process.env['CRTR_NODE_ID'];
@@ -837,13 +835,14 @@ const nodeYield = defineLeaf({
         const kind = input['kind'];
         if (kind !== undefined)
             assertKind(kind);
+        const model = input['model'];
         const message = typeof input['message'] === 'string' ? input['message'].trim() : '';
         if (message === '') {
             throw new InputError({ error: 'empty_message', message: 'a yield message is required (stdin or positional)', next: 'Pass a note to your future self as an argument or pipe it on stdin.' });
         }
         writeYieldMessage(id, message);
-        const res = requestYield(id, kind !== undefined ? { kind } : {});
-        return { node_id: res.meta.node_id, promoted: res.promoted, will_refresh: res.willRefresh };
+        const res = requestYield(id, { ...(kind !== undefined ? { kind } : {}), ...(model !== undefined ? { model } : {}) });
+        return { node_id: res.meta.node_id, promoted: res.promoted, ...(res.meta.model_override != null ? { model: res.meta.model_override } : {}), will_refresh: res.willRefresh };
     },
 });
 // ---------------------------------------------------------------------------
@@ -1349,7 +1348,7 @@ export function registerNode() {
             summary: 'spawn and navigate canvas nodes',
             model: 'Every agent is a node in one directed graph (the canvas); `subscribes_to` is the spine — spawn a child and you auto-subscribe (active) to it, so its finish wakes you.\n\n' +
                 'WHEN TO DELEGATE: hand any self-contained unit of work to a child instead of doing it inline — it keeps your own context window (your scarce resource) free for steering. Spawn independent units in PARALLEL; a wake with idle workers is wasted. Serialize only true dependencies, and never let two live children edit the same files.\n\n' +
-                'HOW: `crtr node new "<task>" --kind <kind>` returns a node id immediately and runs the worker in a background window. Match the kind to the work (see `node new -h`). You are woken when a child finishes — the wake message ALREADY IS the coalesced digest (the watcher drains your inbox to wake you), so don\'t re-run `crtr feed read` to "open" it (it would read empty, the cursor already advanced); instead dereference the report paths in that digest that matter, don\'t act on a one-line label. (`crtr feed read` is for proactively polling before a wake, or inspecting a child\'s inbox via `--node`; `--all` re-reads history with full message bodies.) Integrate, then either delegate the next units or finish.\n\n' +
+                'HOW: `crtr node new "<task>" --kind <kind>` returns a node id immediately and runs the worker as a detached headless broker (no window opens; open a viewer on demand with `crtr node focus`). Match the kind to the work (see `node new -h`). You are woken when a child finishes — the wake message ALREADY IS the coalesced digest (the watcher drains your inbox to wake you), so don\'t re-run `crtr feed read` to "open" it (it would read empty, the cursor already advanced); instead dereference the report paths in that digest that matter, don\'t act on a one-line label. (`crtr feed read` is for proactively polling before a wake, or inspecting a child\'s inbox via `--node`; `--all` re-reads history with full message bodies.) Integrate, then either delegate the next units or finish.\n\n' +
                 'FINISH: a worker ends its own work with `crtr push final "<result>"` (writes the canonical result, marks done, closes the window) — stopping without it is not finishing. For a job too big for one context window, `node promote` to an orchestrator (holds a roadmap, delegates phases); when context fills, `node yield` to refresh against that roadmap.',
         },
         children: [nodeNew, nodeInspect, nodeFocus, nodeCycle, nodeRecycle, nodeClose, nodeMsg, nodeSubscribe, nodeUnsubscribe, nodePromote, nodeDemote, nodeLifecycle, nodeYield, nodeWake],

package/dist/commands/pkg.js

@@ -4,7 +4,6 @@
 import { defineBranch } from '../core/command.js';
 import { pluginBranch } from './pkg/plugin.js';
 import { marketBranch } from './pkg/market.js';
-import { bridgeBranch } from './pkg/bridge.js';
 export function registerPkg() {
     return defineBranch({
         name: 'pkg',
@@ -17,6 +16,6 @@ export function registerPkg() {
             name: 'pkg',
             summary: 'manage plugins and plugin marketplaces',
         },
-        children: [pluginBranch, marketBranch, bridgeBranch],
+        children: [pluginBranch, marketBranch],
     });
 }

package/dist/commands/revive.js

@@ -6,6 +6,7 @@
 import { defineLeaf } from '../core/command.js';
 import { InputError } from '../core/io.js';
 import { reviveNode } from '../core/runtime/revive.js';
+import { waitForBrokerViewSocket } from '../core/runtime/placement.js';
 import { getNode } from '../core/canvas/index.js';
 // ---------------------------------------------------------------------------
 // revive node
@@ -34,14 +35,16 @@ export const reviveLeaf = defineLeaf({
             },
         ],
         output: [
-            { name: 'window', type: 'string', required: false, constraint: 'New tmux window id.' },
-            { name: 'session', type: 'string', required: true, constraint: 'Tmux session the node was placed in.' },
+            { name: 'window', type: 'string', required: false, constraint: 'Always null — the revived broker is headless and opens no tmux window. Kept for caller back-compat.' },
+            { name: 'session', type: 'string', required: false, constraint: 'The node\'s last live location session, or null — the headless broker has no tmux session of its own.' },
             { name: 'resumed', type: 'boolean', required: true, constraint: 'True when pi was told to --session the saved conversation.' },
+            { name: 'ready', type: 'boolean', required: true, constraint: 'True when the revived broker\'s view.sock accepted a connection before return — the node is immediately attachable/drivable.' },
         ],
         outputKind: 'object',
         effects: [
-            'Opens a background (non-focus-stealing) tmux window running pi.',
+            'Launches the node\'s detached headless broker engine (no tmux window).',
             'Updates the node\'s canvas record: status=active, intent=null, window=<new>.',
+            'Blocks until the broker\'s view.sock accepts a connection (up to ~30s), so a caller can attach/dial immediately on return.',
         ],
     },
     run: async (input) => {
@@ -57,10 +60,15 @@ export const reviveLeaf = defineLeaf({
             });
         }
         const result = reviveNode(nodeId, { resume: !fresh });
+        // Revive returns once the broker process is launched, which can be seconds
+        // before its view.sock listens. Callers (attach, the web shell's Wake) dial
+        // immediately on return, so block here until the socket accepts.
+        const ready = waitForBrokerViewSocket(nodeId);
         return {
             window: result.window ?? undefined,
             session: result.session,
             resumed: result.resumed,
+            ready,
         };
     },
 });

package/dist/commands/sys/sync.d.ts

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