@crouton-kit/crouter 0.3.12 → 0.3.13

package/dist/builtin-personas/runtime-base.md

@@ -34,6 +34,6 @@ If the work is bigger or different than your task implies, say so in a push to y
 ## When your task is too big for one context window
 If you discover the job is far larger than one node can hold — many phases, work that won't fit before you run low on context — **promote yourself** instead of grinding:
 
-    crtr node promote --goal "<the high-level goal you now own>"
+    crtr node promote --kind <kind>
 
-This makes you a resident orchestrator: you get a roadmap (`context/roadmap.md`), you delegate each phase to children, and when your context fills you `crtr node yield` to refresh against that roadmap. Don't promote for work that fits one window — finish it.
+This makes you a resident orchestrator: you author a roadmap (`context/roadmap.md`), delegate each phase to children, and when your context fills you `crtr node yield` to refresh against that roadmap. `--kind` specializes the orchestrator you revive into (developer, review, spec, design, plan, explore, general); omit it to keep your current kind. Don't promote for work that fits one window — finish it.

package/dist/commands/node.js

@@ -10,8 +10,8 @@ import { spawnChild, bootRoot } from '../core/runtime/spawn.js';
 import { promote, requestYield } from '../core/runtime/promote.js';
 import { writeYieldMessage } from '../core/runtime/kickoff.js';
 import { reviveNode } from '../core/runtime/revive.js';
-import { focusNodeInPlace } from '../core/runtime/presence.js';
-import { windowAlive } from '../core/runtime/tmux.js';
+import { focusNodeInPlace, demoteNode } from '../core/runtime/presence.js';
+import { windowAlive, windowOfPane, currentTmux } from '../core/runtime/tmux.js';
 import { appendInbox } from '../core/feed/inbox.js';
 import { availableKinds } from '../core/personas/index.js';
 import { getNode, listNodes, subscriptionsOf, subscribersOf, } from '../core/canvas/index.js';
@@ -42,7 +42,7 @@ const nodeNew = defineLeaf({
             { 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: 'Root tmux session the node was placed in.' },
+            { name: 'session', type: 'string', required: true, constraint: 'The shared crtr tmux session the node was placed in.' },
             { name: 'status', type: 'string', required: true, constraint: 'Always "active" on spawn.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'A notification to the caller about the spawn: the child runs independently and its finish wakes you automatically, so treat it as fire-and-forget. Read it, then act.' },
         ],
@@ -182,13 +182,65 @@ const nodeFocus = defineLeaf({
     },
 });
 // ---------------------------------------------------------------------------
+// node demote — detach the agent in your pane to the background session
+// ---------------------------------------------------------------------------
+/** First live node whose window id is `win` (each node owns one window). The
+ *  queryable row projection omits `window`, so resolve full meta per candidate. */
+function nodeByWindow(win) {
+    for (const row of listNodes({ status: ['active', 'idle'] })) {
+        if (getNode(row.node_id)?.window === win)
+            return row.node_id;
+    }
+    return undefined;
+}
+const nodeDemote = defineLeaf({
+    name: 'demote',
+    help: {
+        name: 'node demote',
+        summary: 'detach the agent in your current pane to the background — swap a fresh terminal into its place and relocate its running pi to a window in the shared crtr session (the inverse of focus; reattach later with `node focus`)',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node to demote. Defaults to the node occupying --pane (or your current pane).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id to demote out of. Defaults to $TMUX_PANE / your current pane. The Alt+C menu passes this for you.' },
+        ],
+        output: [
+            { name: 'demoted', type: 'boolean', required: true, constraint: 'True when the agent was swapped out to the background.' },
+            { name: 'node_id', type: 'string', required: false, constraint: 'The demoted node.' },
+            { name: 'session', type: 'string', required: false, constraint: 'The shared session the agent now lives in.' },
+            { name: 'window', type: 'string', required: false, constraint: 'The agent\'s new background window id.' },
+        ],
+        outputKind: 'object',
+        effects: ['Swaps a fresh shell into the caller pane (tmux swap-pane) and relocates the node\'s pi window into the shared crtr session.', 'Clears the focus pointer if the demoted node held it. The pi keeps running — nothing is killed.'],
+    },
+    run: async (input) => {
+        const pane = input['pane'] ?? process.env['TMUX_PANE'];
+        let id = input['node'];
+        if (id === undefined || id === '') {
+            // Derive the node from the pane: which node's window holds it?
+            const resolvePane = pane ?? currentTmux()?.pane;
+            const win = resolvePane !== undefined ? windowOfPane(resolvePane) : null;
+            id = win !== null ? nodeByWindow(win) : undefined;
+        }
+        if (id === undefined || id === '') {
+            throw new InputError({ error: 'no_node', message: 'no node found in this pane to demote', next: 'Pass --node <id>, or run from inside a focused node\'s pane.' });
+        }
+        if (getNode(id) === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const res = demoteNode(id, pane);
+        return { demoted: res.demoted, node_id: id, session: res.session ?? undefined, window: res.window ?? undefined };
+    },
+    render: (r) => r['demoted'] === true
+        ? `<demoted id="${r['node_id']}" session="${r['session'] ?? ''}"/>`
+        : `<demote-failed id="${r['node_id'] ?? ''}">not in tmux, or no agent in this pane</demote-failed>`,
+});
+// ---------------------------------------------------------------------------
 // node session — boot a NEW root in its own tmux session (the explicit form)
 // ---------------------------------------------------------------------------
 const nodeSession = defineLeaf({
     name: 'session',
     help: {
         name: 'node session',
-        summary: 'start a fresh root node in its own tmux session and switch to it (use from inside a node to start a new root without taking your pane)',
+        summary: 'start a fresh root node as its own window in the shared crtr session (use from inside a node to start a new root without taking your pane)',
         params: [
             { kind: 'stdin', name: 'prompt', required: false, constraint: 'Optional starter prompt; a root needs none.' },
             { kind: 'flag', name: 'kind', type: 'string', required: false, default: 'general', constraint: 'Persona kind for the root.' },
@@ -197,11 +249,11 @@ const nodeSession = defineLeaf({
         ],
         output: [
             { name: 'node_id', type: 'string', required: true, constraint: 'The root node id.' },
-            { name: 'session', type: 'string', required: true, constraint: 'The dedicated tmux session created for this root.' },
+            { name: 'session', type: 'string', required: true, constraint: 'The shared crtr tmux session this root\'s window was placed in.' },
             { name: 'window', type: 'string', required: false, constraint: 'The root node\'s window id.' },
         ],
         outputKind: 'object',
-        effects: ['Creates a detached tmux session and runs pi in it as a resident root node.'],
+        effects: ['Opens a detached window in the shared crtr session and runs pi in it as a resident root node.'],
     },
     run: async (input) => {
         const prompt = input['prompt'];
@@ -264,9 +316,9 @@ const nodePromote = defineLeaf({
     name: 'promote',
     help: {
         name: 'node promote',
-        summary: 'promote yourself to a resident orchestrator of a chosen kind — flips to that kind\'s orchestrator persona on next revive, dumps its orchestration + roadmap-shaping guidance now, and seeds a roadmap scaffold for you to author',
+        summary: 'promote yourself to a resident 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',
         params: [
-            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Specialize as this kind of orchestrator: developer (own feature delivery), review, spec, design, plan, explore, general. Defaults to your current kind. Promoting from a generic kind? CHOOSE a concrete one — it picks the orchestrator persona you revive into and the roadmap-shaping skill dumped now.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Specialize as this kind of orchestrator: developer (own feature delivery), review, spec, design, plan, explore, general. 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: 'node', type: 'string', required: false, constraint: 'Node to promote. Defaults to the caller (CRTR_NODE_ID).' },
         ],
         output: [
@@ -274,7 +326,7 @@ const nodePromote = defineLeaf({
             { name: 'kind', type: 'string', required: true, constraint: 'The kind it now orchestrates as.' },
             { name: 'mode', type: 'string', required: true, constraint: 'Now "orchestrator".' },
             { name: 'roadmap_written', type: 'boolean', required: true, constraint: 'True if a roadmap scaffold was seeded by this call.' },
-            { name: 'guidance', type: 'string', required: true, constraint: 'Kind-specific orchestration + roadmap-shaping guidance and your roadmap scaffold — read it, then AUTHOR your roadmap (goal, exit criteria, phases) this turn before delegating.' },
+            { name: 'guidance', type: 'string', required: true, constraint: 'Instructions for your new role — read and act on them this turn.' },
         ],
         outputKind: 'object',
         effects: ['Flips lifecycle→resident, mode→orchestrator, kind→chosen; rewrites the launch spec to that kind\'s orchestrator persona; seeds context/roadmap.md scaffold if absent.'],
@@ -343,12 +395,13 @@ export function registerNode() {
                 { name: 'new', desc: 'spawn a terminal worker as a background window', useWhen: 'delegating a self-contained unit of work' },
                 { name: 'inspect', desc: 'read the graph (list nodes / show one)', useWhen: 'surveying the canvas or inspecting a node' },
                 { name: 'focus', desc: 'bring a node window forefront', useWhen: 'jumping to a node to watch or steer it' },
+                { name: 'demote', desc: 'detach the agent in your pane to the background', useWhen: 'parking the agent in front of you and getting your terminal back (Alt+C → d)' },
                 { name: 'session', desc: 'open a fresh root in its own tmux session', useWhen: 'starting a new top-level session from inside a node' },
                 { name: 'msg', desc: 'direct-message any node at a wake tier', useWhen: 'steering or pinging a specific node (wakes it)' },
                 { name: 'promote', desc: 'become a resident orchestrator of a chosen kind', useWhen: 'your task is bigger than one context window and you must delegate + persist' },
                 { name: 'yield', desc: 'refresh your context against your roadmap', useWhen: 'your context window is filling up' },
             ],
         },
-        children: [nodeNew, nodeInspect, nodeFocus, nodeSession, nodeMsg, nodePromote, nodeYield],
+        children: [nodeNew, nodeInspect, nodeFocus, nodeDemote, nodeSession, nodeMsg, nodePromote, nodeYield],
     });
 }

package/dist/core/runtime/presence.d.ts

@@ -36,3 +36,20 @@ export declare function focusNodeInPlace(nodeId: string, callerPane?: string): {
     session: string | null;
     inPlace: boolean;
 };
+/** Send a node's running pi OUT of the caller's pane and into a window in the
+ *  shared global session, leaving a fresh shell where it was — the pane
+ *  "becomes a terminal" and the agent keeps running, detached, in the
+ *  background. The inverse of `focusNodeInPlace`; reversible via `node focus`.
+ *
+ *  Mechanism: open a shell window in the global session, then swap that shell
+ *  pane INTO the caller's pane — tmux exchanges the two panes, so the node's pi
+ *  pane lands in the shell's window (global session) and the shell lands in the
+ *  caller's pane. The node's meta is re-pointed to the new window so the daemon
+ *  keeps supervising it.
+ *
+ *  Best-effort; `demoted:false` when not in tmux or any tmux step fails. */
+export declare function demoteNode(nodeId: string, callerPane?: string): {
+    demoted: boolean;
+    session: string | null;
+    window: string | null;
+};

package/dist/core/runtime/presence.js

@@ -19,7 +19,7 @@ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { join } from 'node:path';
 import { crtrHome, getNode, updateNode } from '../canvas/index.js';
-import { selectWindow, switchClient, windowAlive, currentTmux, paneOfWindow, swapPaneInPlace, windowOfPane } from './tmux.js';
+import { selectWindow, switchClient, windowAlive, currentTmux, paneOfWindow, swapPaneInPlace, windowOfPane, openShellWindow, closeWindow, ensureSession, nodeSession } from './tmux.js';
 // ---------------------------------------------------------------------------
 // Focus pointer
 // ---------------------------------------------------------------------------
@@ -150,3 +150,49 @@ export function focusNodeInPlace(nodeId, callerPane) {
     }
     return { focused: ok, session, inPlace: true };
 }
+// ---------------------------------------------------------------------------
+// Demote — detach the agent in the caller's pane to the background
+// ---------------------------------------------------------------------------
+/** Send a node's running pi OUT of the caller's pane and into a window in the
+ *  shared global session, leaving a fresh shell where it was — the pane
+ *  "becomes a terminal" and the agent keeps running, detached, in the
+ *  background. The inverse of `focusNodeInPlace`; reversible via `node focus`.
+ *
+ *  Mechanism: open a shell window in the global session, then swap that shell
+ *  pane INTO the caller's pane — tmux exchanges the two panes, so the node's pi
+ *  pane lands in the shell's window (global session) and the shell lands in the
+ *  caller's pane. The node's meta is re-pointed to the new window so the daemon
+ *  keeps supervising it.
+ *
+ *  Best-effort; `demoted:false` when not in tmux or any tmux step fails. */
+export function demoteNode(nodeId, callerPane) {
+    const meta = getNode(nodeId);
+    if (meta === null)
+        return { demoted: false, session: null, window: null };
+    const pane = callerPane ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
+    if (pane === undefined || pane === '') {
+        return { demoted: false, session: meta.tmux_session ?? null, window: meta.window ?? null };
+    }
+    const session = nodeSession();
+    ensureSession(session, meta.cwd);
+    const shell = openShellWindow({ session, name: meta.name, cwd: meta.cwd });
+    if (shell === null)
+        return { demoted: false, session, window: meta.window ?? null };
+    // Swap the fresh shell into the caller's pane; the node's pi pane is exchanged
+    // out into the shell's window (now living in the global session).
+    const ok = swapPaneInPlace(shell.pane, pane);
+    if (!ok) {
+        closeWindow(shell.window);
+        return { demoted: false, session, window: meta.window ?? null };
+    }
+    // The node's pi now occupies the shell window; re-point its meta there so
+    // liveness checks resolve the right window.
+    try {
+        updateNode(nodeId, { tmux_session: session, window: shell.window });
+    }
+    catch { /* best-effort */ }
+    // The caller pane reverted to a terminal — if this node held focus, clear it.
+    if (getFocus() === nodeId)
+        setFocus('');
+    return { demoted: true, session, window: shell.window };
+}

package/dist/core/runtime/revive.js

@@ -11,8 +11,7 @@
 import { getNode, updateNode, } from '../canvas/index.js';
 import { buildPiArgv } from './launch.js';
 import { buildReviveKickoff } from './kickoff.js';
-import { ensureSession, openNodeWindow, piCommand, respawnPane, } from './tmux.js';
-import { rootSessionName } from './spawn.js';
+import { ensureSession, openNodeWindow, piCommand, respawnPane, nodeSession, } from './tmux.js';
 // ---------------------------------------------------------------------------
 // reviveNode
 // ---------------------------------------------------------------------------
@@ -26,10 +25,10 @@ export function reviveNode(nodeId, opts) {
     if (meta === null) {
         throw new Error(`reviveNode: unknown node ${nodeId}`);
     }
-    // The node lives in its root's tmux session. Prefer the stored session name;
-    // fall back to deriving it from the parent (or the node itself for roots).
-    const session = meta.tmux_session ??
-        rootSessionName((meta.parent ?? meta.node_id));
+    // The node lives in the shared global session. Prefer its stored session
+    // (an inline root tracks its own real terminal session); fall back to the
+    // shared node session.
+    const session = meta.tmux_session ?? nodeSession();
     ensureSession(session, meta.cwd);
     // Decide whether to wake the saved pi conversation or start fresh.
     const resumeId = opts.resume && meta.pi_session_id != null
@@ -73,8 +72,7 @@ export function reviveInPlace(nodeId, pane) {
     if (meta === null) {
         throw new Error(`reviveInPlace: unknown node ${nodeId}`);
     }
-    const session = meta.tmux_session ??
-        rootSessionName((meta.parent ?? meta.node_id));
+    const session = meta.tmux_session ?? nodeSession();
     // Fresh re-exec: same recipe as a no-resume reviveNode, with the kickoff so
     // the node rebuilds its bearings from disk.
     const inv = buildPiArgv(meta, { prompt: buildReviveKickoff(meta) });

package/dist/core/runtime/spawn.d.ts

@@ -1,6 +1,4 @@
 import { type NodeMeta, type Mode } from '../canvas/index.js';
-/** A root's tmux session name — its home; every descendant is a window in it. */
-export declare function rootSessionName(rootId: string): string;
 export interface BootRootOpts {
     cwd: string;
     kind?: string;

package/dist/core/runtime/spawn.js

@@ -11,13 +11,9 @@ import { FRONT_DOOR_ENV } from './front-door.js';
 import { spawnNode, currentNodeContext } from './nodes.js';
 import { buildLaunchSpec, buildPiArgv } from './launch.js';
 import { writeGoal } from './kickoff.js';
-import { ensureSession, openNodeWindow, piCommand, currentTmux, inTmux, } from './tmux.js';
+import { ensureSession, openNodeWindow, piCommand, currentTmux, inTmux, nodeSession, installMenuBinding, } from './tmux.js';
 import { updateNode, getNode } from '../canvas/index.js';
 import { ensureDaemon } from '../../daemon/manage.js';
-/** A root's tmux session name — its home; every descendant is a window in it. */
-export function rootSessionName(rootId) {
-    return `crtr-${rootId.replace(/[^a-zA-Z0-9]/g, '').slice(0, 12)}`;
-}
 /** Create a root node and bring up its pi. Returns the node; for 'inline' this
  *  only returns after pi exits (it took over the terminal). */
 export function bootRoot(opts) {
@@ -44,9 +40,17 @@ export function bootRoot(opts) {
     // mandate (bare `crtr` has none — writeGoal no-ops on empty).
     if (opts.prompt !== undefined)
         writeGoal(meta.node_id, opts.prompt);
-    const session = rootSessionName(meta.node_id);
+    // Every node window — root or child — lives in the one shared session.
+    const session = nodeSession();
+    ensureSession(session, opts.cwd);
+    // Make the Alt+C action menu live on this server (idempotent, in-tmux only).
+    if (inTmux()) {
+        try {
+            installMenuBinding();
+        }
+        catch { /* best-effort */ }
+    }
     if (opts.placement === 'session') {
-        ensureSession(session, opts.cwd);
         updateNode(meta.node_id, { tmux_session: session });
         const withSession = getNode(meta.node_id);
         const inv = buildPiArgv(withSession, { prompt: opts.prompt });
@@ -61,14 +65,16 @@ export function bootRoot(opts) {
         updateNode(meta.node_id, { window: win });
         return getNode(meta.node_id);
     }
-    // inline: the root adopts the current tmux session (if any) as its home, so
-    // children spawn as windows alongside it. Then exec pi in this terminal.
+    // inline: the root's pi takes over THIS terminal, so its own window stays
+    // where the user is (its tmux_session tracks that real pane so supervision
+    // sees it alive). But its children spawn into the shared global session via
+    // CRTR_ROOT_SESSION — they never clutter the user's working session.
     const here = currentTmux();
     const adopted = here?.session ?? session;
     updateNode(meta.node_id, { tmux_session: adopted, window: here?.window ?? null });
     const withSession = getNode(meta.node_id);
     const inv = buildPiArgv(withSession, { prompt: opts.prompt });
-    const env = { ...process.env, ...inv.env, CRTR_ROOT_SESSION: adopted, [FRONT_DOOR_ENV]: '1' };
+    const env = { ...process.env, ...inv.env, CRTR_ROOT_SESSION: session, [FRONT_DOOR_ENV]: '1' };
     const r = spawnSync('pi', inv.argv, { stdio: 'inherit', env });
     process.exit(r.status ?? 0);
 }
@@ -97,13 +103,12 @@ export function spawnChild(opts) {
     });
     // Persist the task as the child's goal for a fresh revive to re-read.
     writeGoal(meta.node_id, opts.prompt);
-    // Resolve the root session: inherited from env, else derive + create one.
+    // Children always land in the shared global session: inherited from the
+    // parent's CRTR_ROOT_SESSION, else the default node session.
     let session = process.env['CRTR_ROOT_SESSION'];
-    if (session === undefined || session === '') {
-        const here = inTmux() ? currentTmux() : null;
-        session = here?.session ?? rootSessionName(parent);
-        ensureSession(session, opts.cwd);
-    }
+    if (session === undefined || session === '')
+        session = nodeSession();
+    ensureSession(session, opts.cwd);
     const inv = buildPiArgv(meta, { prompt: opts.prompt });
     const env = { ...inv.env, CRTR_ROOT_SESSION: session };
     const window = openNodeWindow({

package/dist/core/runtime/tmux.d.ts

@@ -1,6 +1,11 @@
 /** POSIX single-quote escaping for one shell word. */
 export declare function shellQuote(s: string): string;
 export declare function inTmux(): boolean;
+/** The single, shared tmux session that ALL canvas node windows live in.
+ *  Overridable with CRTR_NODE_SESSION (default `crtr`). Every root and every
+ *  child opens a window here rather than cluttering the user's own working
+ *  session — switch to it to browse the whole live graph, ignore it otherwise. */
+export declare function nodeSession(): string;
 export interface TmuxLocation {
     session: string;
     window: string;
@@ -34,6 +39,18 @@ export interface OpenWindowOpts {
  *  `-a` also keeps node windows off index 0, which is reserved for the optional
  *  dashboard. */
 export declare function openNodeWindow(opts: OpenWindowOpts): string | null;
+/** Open a background window running a plain login shell (no pi) and return its
+ *  window + pane ids. Used by demote: the agent's pi is swapped OUT into this
+ *  window's slot and the shell is swapped INTO the caller's pane. `-a` keeps it
+ *  off index 0 (reserved for a dashboard), `-d` keeps it from stealing focus. */
+export declare function openShellWindow(opts: {
+    session: string;
+    name: string;
+    cwd: string;
+}): {
+    window: string;
+    pane: string;
+} | null;
 /** Bring a node's window forefront. Switches client across roots when needed. */
 export declare function focusWindow(session: string, window: string): boolean;
 /** Close a node's window (drop it from the UI). */
@@ -86,3 +103,5 @@ export declare function selectWindow(session: string, window: string): boolean;
  *  `tmux switch-client -t <session>`. Best-effort; never throws. The caller is
  *  responsible for following up with selectWindow to land on the right window. */
 export declare function switchClient(session: string): boolean;
+/** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails. */
+export declare function installMenuBinding(): boolean;

package/dist/core/runtime/tmux.js

@@ -26,6 +26,14 @@ function tmux(args) {
 export function inTmux() {
     return process.env['TMUX'] !== undefined && process.env['TMUX'] !== '';
 }
+/** The single, shared tmux session that ALL canvas node windows live in.
+ *  Overridable with CRTR_NODE_SESSION (default `crtr`). Every root and every
+ *  child opens a window here rather than cluttering the user's own working
+ *  session — switch to it to browse the whole live graph, ignore it otherwise. */
+export function nodeSession() {
+    const v = process.env['CRTR_NODE_SESSION'];
+    return v !== undefined && v !== '' ? v : 'crtr';
+}
 /** Where the caller currently is, or null if not inside tmux. */
 export function currentTmux() {
     if (!inTmux())
@@ -90,6 +98,25 @@ export function openNodeWindow(opts) {
     ]);
     return r.ok ? r.stdout : null;
 }
+/** Open a background window running a plain login shell (no pi) and return its
+ *  window + pane ids. Used by demote: the agent's pi is swapped OUT into this
+ *  window's slot and the shell is swapped INTO the caller's pane. `-a` keeps it
+ *  off index 0 (reserved for a dashboard), `-d` keeps it from stealing focus. */
+export function openShellWindow(opts) {
+    const r = tmux([
+        'new-window', '-d', '-a', '-P',
+        '-F', '#{window_id}\t#{pane_id}',
+        '-t', `${opts.session}:`,
+        '-n', opts.name,
+        '-c', opts.cwd,
+    ]);
+    if (!r.ok)
+        return null;
+    const [window, pane] = r.stdout.split('\t');
+    if (window === undefined || pane === undefined)
+        return null;
+    return { window, pane };
+}
 /** Bring a node's window forefront. Switches client across roots when needed. */
 export function focusWindow(session, window) {
     const here = currentTmux();
@@ -196,3 +223,22 @@ export function selectWindow(session, window) {
 export function switchClient(session) {
     return tmux(['switch-client', '-t', session]).ok;
 }
+// ---------------------------------------------------------------------------
+// Prefix menu — Alt+C opens a which-key-style tmux display-menu of crouter
+// actions. Installed on the running server at root boot; idempotent (a re-bind
+// overwrites the previous one). Items shell out to `crtr`, passing the active
+// pane so an action targets the agent currently in front of you.
+// ---------------------------------------------------------------------------
+/** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails. */
+export function installMenuBinding() {
+    const sess = nodeSession();
+    return tmux([
+        'bind-key', '-n', 'M-c', 'display-menu',
+        '-T', '#[align=centre] crtr ',
+        // Anchor to the top-right of the pane it was called from (tmux clamps it
+        // back on-screen) rather than centring on the whole terminal.
+        '-x', '#{pane_right}', '-y', '#{pane_top}',
+        'detach agent \u2192 background', 'd', `run-shell "crtr node demote --pane '#{pane_id}'"`,
+        'browse background agents', 'g', `switch-client -t ${sess}`,
+    ]).ok;
+}

package/dist/pi-extensions/canvas-stophook.js

@@ -132,29 +132,52 @@ function extractText(msg) {
         .trim();
 }
 // ---------------------------------------------------------------------------
-// Context-size steering bands — first nudge at 100k input tokens, then one
-// every 50k thereafter (150k, 200k, 250k, …). Unbounded: a long-lived node
-// keeps getting reminded as it grows.
+// Context-size steering bands — mode-specific schedules that ESCALATE in tone
+// as input context grows. The first band is a gentle "consider it"; a later
+// band turns firm. Past the last explicit band the firmest nudge repeats every
+// 50k, so a long-lived node keeps getting reminded.
+//
+//   orchestrator: 130k gentle (consider yielding) → 150k+ firm (do it now)
+//   base worker:  130k suggest promote → 160k+ suggest promote (+ "ignore if
+//                 nearly done")
 // ---------------------------------------------------------------------------
-const STEER_FLOOR = 100_000;
 const STEER_STEP = 50_000;
-/** The highest band boundary at or below `tokens` (100k, 150k, 200k, …), or
- *  null below the floor. */
-function steerBand(tokens) {
-    if (tokens < STEER_FLOOR)
+const ORCH_BANDS = [130_000, 150_000]; // gentle, then firm (firm repeats +50k)
+const WORKER_BANDS = [130_000, 160_000]; // suggest, then suggest+ignore (repeats +50k)
+/** The highest band threshold at or below `tokens` for `mode`. Below the first
+ *  band → null. At/past the last listed band, bands continue every STEER_STEP
+ *  (so the firmest nudge keeps recurring). */
+function steerBand(tokens, mode) {
+    const bands = mode === 'orchestrator' ? ORCH_BANDS : WORKER_BANDS;
+    const first = bands[0];
+    const last = bands[bands.length - 1];
+    if (tokens < first)
         return null;
-    return STEER_FLOOR + Math.floor((tokens - STEER_FLOOR) / STEER_STEP) * STEER_STEP;
+    if (tokens >= last)
+        return last + Math.floor((tokens - last) / STEER_STEP) * STEER_STEP;
+    let chosen = first;
+    for (const b of bands)
+        if (tokens >= b)
+            chosen = b;
+    return chosen;
 }
-/** The nudge text for a crossed band, specialized to the node's mode. An
- *  orchestrator is steered to checkpoint its roadmap and yield; a non-
- *  orchestrator (base worker) is steered to PROMOTE itself — become a resident
- *  orchestrator — when work remains, or finish if it's nearly done. */
+/** The nudge text for a crossed band, specialized to the node's mode + how far
+ *  along the escalation it is. An orchestrator is steered to checkpoint its
+ *  roadmap and yield (gently first, then firmly); a non-orchestrator (base
+ *  worker) is steered to PROMOTE itself — become a resident orchestrator — when
+ *  work remains, with an "ignore if nearly done" once it's deeper in. */
 function steerNote(at, mode) {
     const k = Math.round(at / 1000);
     if (mode === 'orchestrator') {
+        if (at < 150_000) {
+            return `Context ~${k}k and growing. When you reach a good stopping point, consider updating context/roadmap.md and running \`crtr node yield\` to refresh against it — no rush yet.`;
+        }
         return `Context ~${k}k. Update context/roadmap.md so a fresh revive can continue, delegate any outstanding work, then \`crtr node yield\` to refresh.`;
     }
-    return `Context ~${k}k and climbing. If more work remains than this context can finish, \`crtr node promote\` to become a resident orchestrator (seeds a roadmap, lets you delegate and \`crtr node yield\` to refresh). If you're nearly done, finish with \`crtr push final\`.`;
+    const suggest = `If much more work remains than this context can finish, consider \`crtr node promote\` to become a resident orchestrator (seeds a roadmap, lets you delegate and \`crtr node yield\` to refresh).`;
+    if (at < 160_000)
+        return `Context ~${k}k. ${suggest}`;
+    return `Context ~${k}k. ${suggest} If you're nearly done, ignore this suggestion and finish with \`crtr push final\`.`;
 }
 // ---------------------------------------------------------------------------
 // Extension
@@ -179,9 +202,9 @@ export function registerCanvasStophook(pi) {
     let totalOut = 0;
     let model = '';
     // Context-size steering. As input context grows we nudge the node once per
-    // band (100k, then every 50k). The nudge depends on the node's CURRENT mode,
-    // read at fire time since a base worker can promote mid-session: an
-    // orchestrator checkpoints + yields; a base worker is steered to promote.
+    // band on an escalating, mode-specific schedule (see steerBand/steerNote).
+    // Mode is read at fire time since a base worker can promote mid-session: an
+    // orchestrator is steered to checkpoint + yield; a base worker to promote.
     const firedBands = new Set();
     // ---------------------------------------------------------------------------
     // session_start — capture pi's session id, and detect `/new`.
@@ -246,10 +269,10 @@ export function registerCanvasStophook(pi) {
         // Context-size steering: fire the current band once, with mode-specific
         // guidance (mode is read live — a worker may have promoted since launch).
         try {
-            const at = steerBand(totalIn);
+            const mode = getNode(nodeId)?.mode ?? 'base';
+            const at = steerBand(totalIn, mode);
             if (at !== null && !firedBands.has(at)) {
                 firedBands.add(at);
-                const mode = getNode(nodeId)?.mode ?? 'base';
                 pi.sendUserMessage(`[crtr] ${steerNote(at, mode)}`, { deliverAs: 'followUp' });
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.12",
+  "version": "0.3.13",
   "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",