@crouton-kit/crouter 0.3.17 → 0.3.19

package/dist/clients/attach/slash-commands.js

@@ -0,0 +1,200 @@
+// slash-commands.ts — builtin slash-command parse + dispatch for `crtr attach` (C6).
+//
+// Builtin slash commands are NOT engine-interpreted: `session.prompt('/model')`
+// ships "/model" to the LLM as literal text. So the viewer recognizes the 21
+// vendored `BUILTIN_SLASH_COMMANDS` itself and dispatches the matching
+// `ClientToBroker` command frame; only EXTENSION commands (anything the viewer
+// doesn't recognize) fall through to be sent as a `prompt` for the engine's
+// extension runner to handle.
+//
+// SELECTORS — the Phase-4 reality. The plan called for `/model`, `/resume`,
+// `/fork`, `/tree`, `/settings` to open pi's exported `*SelectorComponent`s. The
+// authoritative 0.78.1 .d.ts shows those components require ENGINE-side state a
+// socket-only viewer does not have (`ModelSelectorComponent` needs the
+// `ModelRegistry` + `SettingsManager`; `SessionSelectorComponent` needs session
+// loaders; `TreeSelectorComponent` needs the `SessionTreeNode[]` tree), and the
+// §1.2 command-frame floor set exposes NO read op to fetch any of it. So in
+// Phase 4 these resolve via a TEXT ARGUMENT — `/model <id>`, `/resume <path>`,
+// `/fork <entryId>`, `/tree <entryId>` — which sends the SAME resolved value the
+// selector would have, i.e. zero engine capability is lost; only the interactive
+// picker UI waits for a future read op. A no-arg invocation shows a one-line
+// notice with the arg form. (This protocol gap is reported up to the parent.)
+//
+// SCOPED OUT (review m2 — no engine method): `/login`, `/logout`, `/share`,
+// `/trust` — a brief "not supported in attach" notice, never a frame.
+import { BUILTIN_SLASH_COMMANDS } from '../../core/runtime/pi-vendored.js';
+/** Builtins with no Phase-4 engine method — scoped out (review m2). */
+const SCOPED_OUT = new Set(['login', 'logout', 'share', 'trust']);
+/** Valid `/settings thinking` levels — the `SetThinkingLevelFrame['level']`
+ *  union (= AgentSession['thinkingLevel'], pi-agent-core ThinkingLevel),
+ *  mirrored as a runtime set so an invalid arg is rejected with the options
+ *  rather than shipped as a frame the engine would throw on. Built from a
+ *  `Record<level, true>` so the build fails BOTH ways if the union drifts: a
+ *  missing key (union GAINED a level) or an extra key (union dropped one). */
+const THINKING_LEVELS = new Set(Object.keys({
+    off: true,
+    minimal: true,
+    low: true,
+    medium: true,
+    high: true,
+    xhigh: true,
+}));
+const BUILTIN_NAMES = new Set(BUILTIN_SLASH_COMMANDS.map((c) => c.name));
+/** True if `text` is a leading-slash command (vs. a normal prompt). */
+export function isSlashCommand(text) {
+    return text.trimStart().startsWith('/');
+}
+/**
+ * Parse + dispatch a leading-slash command. Returns `true` if it was handled
+ * (a recognized builtin or a scoped-out notice) — the caller then clears the
+ * editor and sends nothing else. Returns `false` for an UNRECOGNIZED command,
+ * which the caller forwards to the engine as a `prompt` (extension command).
+ */
+export function dispatchSlashCommand(text, ctx) {
+    const m = /^\/(\S+)\s*([\s\S]*)$/.exec(text.trim());
+    if (!m)
+        return false;
+    const name = m[1];
+    const arg = m[2].trim();
+    if (SCOPED_OUT.has(name)) {
+        ctx.notify(`/${name} is not supported in attach (Phase 4)`);
+        return true;
+    }
+    // Unknown to us AND not a builtin → let the engine's extension runner have it.
+    if (!BUILTIN_NAMES.has(name))
+        return false;
+    switch (name) {
+        // --- direct frames -----------------------------------------------------
+        case 'new':
+            ctx.send({ type: 'new_session' });
+            return true;
+        case 'reload':
+            ctx.send({ type: 'reload' });
+            return true;
+        case 'compact':
+            ctx.send({ type: 'compact', instructions: arg || undefined });
+            return true;
+        case 'quit':
+            // A viewer "quit" DETACHES — the shared engine keeps running (one-writer).
+            ctx.send({ type: 'bye' });
+            ctx.notify('Detaching — the engine keeps running');
+            return true;
+        // --- frames needing one argument --------------------------------------
+        case 'name':
+            if (!arg)
+                return usage(ctx, '/name <display name>');
+            ctx.send({ type: 'set_session_name', name: arg });
+            return true;
+        case 'export': {
+            const { path, format } = parseExport(arg, ctx.cwd ?? process.cwd());
+            ctx.send({ type: 'export', path, format });
+            ctx.notify(`Exporting session → ${path}`);
+            return true;
+        }
+        case 'import':
+            // `/import` resumes a session built from a JSONL file → switch_session.
+            if (!arg)
+                return usage(ctx, '/import <path-to-session.jsonl>');
+            ctx.send({ type: 'switch_session', path: arg });
+            return true;
+        // --- value-picker builtins: arg form (selector deferred, see header) ---
+        case 'model':
+            if (!arg)
+                return pickerHint(ctx, 'model', '/model <id>');
+            ctx.send({ type: 'set_model', model: arg });
+            return true;
+        case 'resume':
+            if (!arg)
+                return pickerHint(ctx, 'session', '/resume <session-path>');
+            ctx.send({ type: 'switch_session', path: arg });
+            return true;
+        case 'fork':
+            if (!arg)
+                return pickerHint(ctx, 'fork point', '/fork <entryId>');
+            ctx.send({ type: 'fork', entryId: arg });
+            return true;
+        case 'tree':
+            if (!arg)
+                return pickerHint(ctx, 'tree', '/tree <entryId>');
+            ctx.send({ type: 'navigate_tree', targetId: arg });
+            return true;
+        // --- settings (sub-command form; interactive menu needs read ops) ------
+        case 'settings':
+            return handleSettings(arg, ctx);
+        // --- read-only / informational ----------------------------------------
+        case 'session':
+            ctx.notify(describeSession(ctx.state));
+            return true;
+        // --- recognized builtins with no Phase-4 wire path --------------------
+        case 'copy':
+        case 'changelog':
+        case 'hotkeys':
+        case 'scoped-models':
+        case 'clone':
+            ctx.notify(`/${name} is not available in attach (Phase 4)`);
+            return true;
+        default:
+            // A builtin we listed but didn't special-case: treat as unsupported
+            // rather than leak it to the LLM as literal text.
+            ctx.notify(`/${name} is not available in attach (Phase 4)`);
+            return true;
+    }
+}
+/** Build slash-command autocomplete entries from the merged command list (the
+ *  broker's `get_commands` result, which T7 may inject) — defaults to the
+ *  vendored builtins. Shaped for pi-tui's `CombinedAutocompleteProvider`. */
+export function slashCommandList(commands = BUILTIN_SLASH_COMMANDS) {
+    return commands.map((c) => ({ name: c.name, description: c.description }));
+}
+/** Same list as flat autocomplete items (value/label/description). */
+export function commandAutocompleteItems(commands = BUILTIN_SLASH_COMMANDS) {
+    return commands.map((c) => ({ value: `/${c.name}`, label: `/${c.name}`, description: c.description }));
+}
+// ---------------------------------------------------------------------------
+function usage(ctx, form) {
+    ctx.notify(`Usage: ${form}`);
+    return true;
+}
+function pickerHint(ctx, what, form) {
+    ctx.notify(`Interactive ${what} picker isn't available over view.sock yet — use ${form}`);
+    return true;
+}
+function handleSettings(arg, ctx) {
+    const [sub, ...rest] = arg.split(/\s+/);
+    const value = rest.join(' ').trim();
+    switch (sub) {
+        case 'thinking':
+            if (!value)
+                return usage(ctx, '/settings thinking <level>');
+            if (!THINKING_LEVELS.has(value)) {
+                ctx.notify(`Invalid thinking level "${value}" — choose one of: ${[...THINKING_LEVELS].join(', ')}`);
+                return true;
+            }
+            ctx.send({ type: 'set_thinking_level', level: value });
+            return true;
+        case 'auto-retry':
+            ctx.send({ type: 'set_auto_retry', enabled: parseBool(value) });
+            return true;
+        case 'auto-compaction':
+            ctx.send({ type: 'set_auto_compaction', enabled: parseBool(value) });
+            return true;
+        default:
+            ctx.notify('Settings: /settings thinking <level> | auto-retry on|off | auto-compaction on|off ' +
+                '(the interactive settings menu needs data not exposed over view.sock in Phase 4)');
+            return true;
+    }
+}
+function parseBool(value) {
+    return /^(on|true|yes|1|enabled?)$/i.test(value.trim());
+}
+function parseExport(arg, cwd) {
+    const path = arg || `${cwd}/pi-export-${Date.now()}.html`;
+    const format = path.endsWith('.jsonl') ? 'jsonl' : 'html';
+    return { path, format };
+}
+function describeSession(state) {
+    if (!state)
+        return 'Session info unavailable';
+    const name = state.sessionName ? `"${state.sessionName}" ` : '';
+    return `Session ${name}${state.sessionId} · model ${state.model ?? 'unknown'} · thinking ${state.thinkingLevel}`;
+}

package/dist/clients/attach/view-socket.d.ts

@@ -0,0 +1,48 @@
+import { EventEmitter } from 'node:events';
+import { type BrokerToClient, type ClientToBroker } from '../../core/runtime/broker-protocol.js';
+/** Surfaced when the node has no reachable broker at connect time (no socket
+ *  file, or a stale socket with nothing listening). The command catches this to
+ *  exit non-zero with a focus/revive hint. */
+export declare class BrokerUnavailableError extends Error {
+    readonly nodeId: string;
+    constructor(nodeId: string);
+}
+/** The plan-fixed interface (Wave 3): `connect()`, `on('frame', …)`,
+ *  `send(frame)`, `on('close', …)`, plus `connect`/`error` events. */
+export interface ViewSocketClient {
+    on(event: 'connect', listener: () => void): this;
+    on(event: 'frame', listener: (frame: BrokerToClient) => void): this;
+    on(event: 'close', listener: () => void): this;
+    on(event: 'error', listener: (err: Error) => void): this;
+    once(event: 'connect', listener: () => void): this;
+    once(event: 'frame', listener: (frame: BrokerToClient) => void): this;
+    once(event: 'close', listener: () => void): this;
+    once(event: 'error', listener: (err: Error) => void): this;
+    off(event: 'connect', listener: () => void): this;
+    off(event: 'error', listener: (err: Error) => void): this;
+}
+export declare class ViewSocketClient extends EventEmitter {
+    private readonly nodeId;
+    private socket;
+    private readonly decoder;
+    private closeEmitted;
+    constructor(nodeId: string);
+    /** The broker binds `join(nodeDir(id), 'view.sock')` — resolve it the same way. */
+    get socketPath(): string;
+    /** Open the connection. Wire up listeners; emits `connect` on success or
+     *  `error` (a {@link BrokerUnavailableError} for ECONNREFUSED/ENOENT) on
+     *  failure. Idempotent guard is the caller's job — call once. */
+    connect(): void;
+    /** Encode + write one client→broker frame. No-op on a dead/absent socket
+     *  (a `close` event drives teardown); never throws. */
+    send(frame: ClientToBroker): void;
+    /** Detach: destroy the socket. `close` fires → the caller tears down. */
+    close(): void;
+    private onData;
+    private onError;
+    private onClose;
+    private destroy;
+    /** Emit `error` only when a listener exists — a bare EventEmitter `error`
+     *  with no listener throws, and this client must never throw uncaught. */
+    private emitError;
+}

package/dist/clients/attach/view-socket.js

@@ -0,0 +1,126 @@
+// view-socket.ts — the socket client half of `crtr attach` (Phase 4, T7).
+//
+// The §0 ONE-WRITER INVARIANT lives in this directory: a viewer has ONLY a
+// socket. ViewSocketClient connects to a node's ALREADY-running headless broker
+// over its unix socket (`nodeDir(id)/view.sock`) and speaks the LOCAL
+// broker-protocol codec (`node:net` + the bounded `FrameDecoder`). It NEVER
+// spawns pi, NEVER opens the session `.jsonl`, NEVER constructs an engine — if
+// the broker is not running, connect fails and `attach-cmd` exits (focus/T9 is
+// what keeps a broker alive, not attach). It also never uses pi's `RpcClient`
+// (which would spawn its own engine).
+//
+// No reconnect: a dropped broker means the engine's turn-cycle settled and the
+// broker disposed+exited; a fresh focus re-runs attach. On EOF/close → emit
+// `close` (the caller renders "broker gone" + exits). On a connect-time
+// ECONNREFUSED/ENOENT → a `BrokerUnavailableError` so the command exits non-zero
+// with a clear message. Decode is bounded by `CLIENT_READ_CAPS`; a broker that
+// somehow sends an oversized frame surfaces as a clean error+exit, not a crash.
+import { EventEmitter } from 'node:events';
+import { createConnection } from 'node:net';
+import { join } from 'node:path';
+import { nodeDir } from '../../core/canvas/paths.js';
+import { CLIENT_READ_CAPS, encodeFrame, FrameDecoder, FrameOverflowError, } from '../../core/runtime/broker-protocol.js';
+/** Surfaced when the node has no reachable broker at connect time (no socket
+ *  file, or a stale socket with nothing listening). The command catches this to
+ *  exit non-zero with a focus/revive hint. */
+export class BrokerUnavailableError extends Error {
+    nodeId;
+    constructor(nodeId) {
+        super(`node ${nodeId} has no running broker — focus or revive it first`);
+        this.nodeId = nodeId;
+        this.name = 'BrokerUnavailableError';
+    }
+}
+export class ViewSocketClient extends EventEmitter {
+    nodeId;
+    socket;
+    decoder = new FrameDecoder(CLIENT_READ_CAPS);
+    closeEmitted = false;
+    constructor(nodeId) {
+        super();
+        this.nodeId = nodeId;
+    }
+    /** The broker binds `join(nodeDir(id), 'view.sock')` — resolve it the same way. */
+    get socketPath() {
+        return join(nodeDir(this.nodeId), 'view.sock');
+    }
+    /** Open the connection. Wire up listeners; emits `connect` on success or
+     *  `error` (a {@link BrokerUnavailableError} for ECONNREFUSED/ENOENT) on
+     *  failure. Idempotent guard is the caller's job — call once. */
+    connect() {
+        const socket = createConnection(this.socketPath);
+        this.socket = socket;
+        socket.on('connect', () => this.emit('connect'));
+        socket.on('data', (chunk) => this.onData(chunk));
+        socket.on('error', (err) => this.onError(err));
+        socket.on('close', () => this.onClose());
+    }
+    /** Encode + write one client→broker frame. No-op on a dead/absent socket
+     *  (a `close` event drives teardown); never throws. */
+    send(frame) {
+        const sock = this.socket;
+        if (sock === undefined || sock.destroyed)
+            return;
+        try {
+            sock.write(encodeFrame(frame));
+        }
+        catch {
+            /* dead socket — 'close' will fire and drive teardown */
+        }
+    }
+    /** Detach: destroy the socket. `close` fires → the caller tears down. */
+    close() {
+        this.destroy();
+    }
+    onData(chunk) {
+        let frames;
+        try {
+            frames = this.decoder.push(chunk);
+        }
+        catch (err) {
+            // A broker that somehow emits an oversized frame (or a corrupt stream):
+            // clean error + drop, never a crash.
+            const msg = err instanceof FrameOverflowError
+                ? `broker sent an oversized frame (${err.message}) — disconnecting`
+                : `failed to decode a broker frame: ${String(err)}`;
+            this.emitError(new Error(msg));
+            this.destroy();
+            return;
+        }
+        for (const raw of frames) {
+            this.emit('frame', raw);
+        }
+    }
+    onError(err) {
+        if (err.code === 'ECONNREFUSED' || err.code === 'ENOENT') {
+            this.emitError(new BrokerUnavailableError(this.nodeId));
+        }
+        else {
+            this.emitError(new Error(`view socket error: ${err.message}`));
+        }
+        // 'close' typically follows 'error'; teardown converges there.
+    }
+    onClose() {
+        if (this.closeEmitted)
+            return;
+        this.closeEmitted = true;
+        this.emit('close');
+    }
+    destroy() {
+        const sock = this.socket;
+        if (sock !== undefined && !sock.destroyed) {
+            try {
+                sock.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    /** Emit `error` only when a listener exists — a bare EventEmitter `error`
+     *  with no listener throws, and this client must never throw uncaught. */
+    emitError(err) {
+        if (this.listenerCount('error') > 0)
+            this.emit('error', err);
+    }
+}

package/dist/commands/attention.js

@@ -21,7 +21,7 @@ import { countAsks, pendingAsksForView, asksAcrossCanvas, asksForNodes, } from '
 const attentionCount = defineLeaf({
     name: 'count',
     description: 'total pending ask count (machine-parseable stdout.count)',
-    whenToUse: 'getting a single pending-ask count for a script or nav chrome to read (stdout.count is machine-parseable); scope with --node or --view, or default to canvas-wide',
+    whenToUse: 'getting a single pending-ask count for a script or nav chrome to read; scope it to a node or a sub-DAG, or default to canvas-wide',
     help: {
         name: 'canvas attention count',
         // stdout.count is parsed directly by the nav chrome — keep the contract.
@@ -93,7 +93,7 @@ const attentionCount = defineLeaf({
 const attentionList = defineLeaf({
     name: 'list',
     description: 'itemised list of cwds with pending asks',
-    whenToUse: 'finding which agents are blocked waiting on a human — an itemised list of the cwds with pending asks, oldest first, so you know where to go answer. Scope to a sub-DAG with --view or list canvas-wide. Use `canvas attention count` instead when a script just needs the number, or `canvas attention map` for per-node counts to label a UI',
+    whenToUse: 'finding which agents are blocked waiting on a human — an itemised list of the cwds with pending asks, oldest first, so you know where to go answer. Scope it to a sub-DAG or list canvas-wide. Use `canvas attention count` instead when a script just needs the number, or `canvas attention map` for per-node counts to label a UI',
     help: {
         name: 'canvas attention list',
         summary: 'list nodes with pending human asks, grouped by cwd, oldest first',
@@ -211,7 +211,7 @@ const attentionMap = defineLeaf({
 export const attentionBranch = defineBranch({
     name: 'attention',
     description: 'count/list pending human asks across the graph',
-    whenToUse: 'checking whether any agent on the canvas is blocked waiting on a human, and where: count the pending asks, list the cwds that have them, or map per-node counts. Scope with --node or --view, or go canvas-wide. Use `canvas dashboard` instead for the graph SHAPE, or `node inspect list` for a plain node roster',
+    whenToUse: 'checking whether any agent on the canvas is blocked waiting on a human, and where: count the pending asks, list the cwds that have them, or map per-node counts. Scope it to a node or a sub-DAG, or go canvas-wide. Use `canvas dashboard` instead for the graph SHAPE, or `node inspect list` for a plain node roster',
     help: {
         name: 'canvas attention',
         summary: 'aggregate pending human asks across the canvas',

package/dist/commands/canvas-prune.js

@@ -13,7 +13,7 @@ const DEFAULT_TTL_DAYS = 14;
 export const canvasPruneLeaf = defineLeaf({
     name: 'prune',
     description: 'remove terminal nodes (dead/done/canceled) older than a TTL',
-    whenToUse: 'you want to bound the canvas\u2019s on-disk growth \u2014 sweep away nodes that are finished (done), crashed (dead), or closed (canceled) and older than a retention window, reclaiming their rows, edges (cascade-deleted by the schema), and `nodes/<id>/` dirs. Run it as an operator/cron chore; live nodes (active/idle) are never touched. Pass `--dry-run` first to see exactly what would go, `--ttl <days>` to widen or tighten the window',
+    whenToUse: 'you want to bound the canvas\u2019s on-disk growth \u2014 sweep away nodes that are finished (done), crashed (dead), or closed (canceled) and older than a retention window, reclaiming their rows, edges (cascade-deleted by the schema), and `nodes/<id>/` dirs. Run it as an operator/cron chore; live nodes (active/idle) are never touched, and you can preview the sweep before it deletes anything',
     help: {
         name: 'canvas prune',
         summary: 'delete terminal nodes older than a TTL (edges cascade, dirs removed); --dry-run to preview',

package/dist/commands/daemon.js

@@ -1,7 +1,8 @@
 // `crtr canvas daemon` — thin supervisor daemon management.
 //
-// The daemon (crtrd) polls active+idle nodes and handles window exit:
-//   • crash (window gone, no intent) → mark 'dead'
+// The daemon (crtrd) polls active+idle nodes and handles engine-container exit
+// (a tmux pane or a headless broker process):
+//   • crash (container gone, no intent) → mark 'dead'
 //   • refresh-yield (intent=refresh) → fresh respawn
 //
 // This subtree starts, checks, and stops the daemon process.
@@ -93,7 +94,7 @@ const daemonStop = defineLeaf({
             throw new InputError({
                 error: 'kill_failed',
                 message: `failed to signal pid ${pid}: ${err.message}`,
-                next: 'The pidfile may be stale; remove ~/.crtr/crtrd.pid manually.',
+                next: 'The pidfile may be stale; remove ~/.crouter/canvas/crtrd.pid manually.',
             });
         }
     },

package/dist/commands/human/prompts.js

@@ -2,12 +2,12 @@ import { defineLeaf } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
 import { spawnNode } from '../../core/runtime/nodes.js';
 import { interactionDir } from '../../core/artifact.js';
-import { isInTmux, spawnAndDetach } from '../../core/spawn.js';
+import { isInTmux } from '../../core/spawn.js';
 import { mkdirSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { validateDeck, approveDeck, notifyDeck, atomicWriteJson, deckPath, display, } from '@crouton-kit/humanloop';
-import { DECK_SCHEMA_HINT, followUpReview, spawnHumanJob, pickPlacement, runCmd, resolveMaxPanes, } from './shared.js';
+import { DECK_SCHEMA_HINT, followUpReview, spawnHumanJob, detachHumanTui, resolveMaxPanes, } from './shared.js';
 /** The asking node's id, or null when run from a bare shell (no parent to route to). */
 function askingNode() {
     return process.env['CRTR_NODE_ID'] ?? null;
@@ -132,7 +132,7 @@ export const humanReview = defineLeaf({
         outputKind: 'object',
         effects: [
             'Creates a kind:"human" node under you and writes run.json to the interaction dir.',
-            'Spawns a live, read-only review session (in a detached tmux pane when in tmux) that tracks the file and re-renders on save.',
+            'Spawns a live review surface (detached tmux panes when in tmux): the raw source in a read-only editor for anchoring comments, beside a termrender-rendered view of the doc; both track the file and re-render on save.',
             'Returns instantly; the anchored comments fan into your inbox when the human submits (off-tmux, drain via `crtr human inbox`).',
         ],
     },
@@ -212,13 +212,7 @@ export const humanNotify = defineLeaf({
         atomicWriteJson(join(idir, 'run.json'), rc);
         let shown = false;
         if (isInTmux()) {
-            const spawn = spawnAndDetach({
-                command: runCmd(idir),
-                cwd,
-                placement: pickPlacement(),
-                killAfterSeconds: 0,
-            });
-            shown = spawn.status === 'spawned';
+            shown = detachHumanTui(idir, cwd).status === 'spawned';
         }
         return { shown, dir: idir };
     },

package/dist/commands/human/queue.js

@@ -8,7 +8,7 @@ import { transition } from '../../core/runtime/lifecycle.js';
 import { appendInbox } from '../../core/feed/inbox.js';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { inbox, scanInbox, parseDeck, deckPath, responsePath, isResolved, atomicWriteJson, ask, launchReview, readJson, } from '@crouton-kit/humanloop';
+import { inbox, scanInbox, parseDeck, deckPath, responsePath, isResolved, atomicWriteJson, ask, launchReview, readJson, display, } from '@crouton-kit/humanloop';
 import { killPane } from './shared.js';
 // ---------------------------------------------------------------------------
 // inbox (human-invoked, blocking)
@@ -136,6 +136,13 @@ export const humanCancel = defineLeaf({
         const rc = readJson(join(idir, 'run.json'));
         if (rc?.pane_id !== undefined && rc.pane_id !== '')
             killPane(rc.pane_id, idir);
+        // A review also opened a live termrender render pane beside the editor —
+        // kill it too or it outlives the canceled job. Verified against the
+        // reviewed file path, which termrender bakes into the pane's start command
+        // (`termrender doc watch ... <file>`), so this can only ever hit our pane.
+        if (rc?.render_pane_id !== undefined && rc.render_pane_id !== '' && typeof rc.file === 'string' && rc.file !== '') {
+            killPane(rc.render_pane_id, rc.file);
+        }
         // (2) Drop it from the human queue: a response.json marks the dir resolved,
         //     so scanInbox (human list/inbox) skips it.
         if (existsSync(idir)) {
@@ -218,13 +225,41 @@ export const humanRun = defineLeaf({
             else if (rc.mode === 'review') {
                 // The _run worker is already its own dedicated tmux pane with a TTY, so
                 // run nvim directly in it (noTmux) instead of letting launchReview
-                // split off a SECOND pane and sit polling. This matches how ask/approve
-                // render in-place and avoids the redundant side pane.
-                const res = await launchReview(rc.file, {
-                    output: rc.output,
-                    noTmux: true,
-                });
-                await pushFinal(rc.job_id, JSON.stringify(res));
+                // split off a SECOND pane and sit polling.
+                //
+                // BUG REGRESSION (raw-markdown review): the nvim buffer must stay the
+                // RAW source — anchored comments hang off source line numbers — so the
+                // termrender render the help promises (panels/callouts/mermaid) lives
+                // in its OWN live pane opened beside this worker. `display` spawns the
+                // managed termrender binary in watch mode, so it re-renders on every
+                // save exactly like the nvim buffer reloads. Best-effort: off-tmux or
+                // renderer-unavailable degrades to editor-only. The pane id is merged
+                // into run.json so `human cancel` can kill it; the finally clears it on
+                // every exit of the editor (submit, quit, or failure).
+                let renderPane;
+                try {
+                    renderPane = display(rc.file, { window: 'split' }).paneId;
+                }
+                catch {
+                    /* render pane is best-effort; the review itself must not die */
+                }
+                if (renderPane !== undefined) {
+                    const rcPath = join(dir, 'run.json');
+                    const cur = readJson(rcPath);
+                    if (cur !== null)
+                        atomicWriteJson(rcPath, { ...cur, render_pane_id: renderPane });
+                }
+                try {
+                    const res = await launchReview(rc.file, {
+                        output: rc.output,
+                        noTmux: true,
+                    });
+                    await pushFinal(rc.job_id, JSON.stringify(res));
+                }
+                finally {
+                    if (renderPane !== undefined)
+                        killPane(renderPane, rc.file);
+                }
             }
         }
         catch (e) {

package/dist/commands/human/shared.d.ts

@@ -1,3 +1,4 @@
+import { type DetachResult } from '../../core/spawn.js';
 export declare const DECK_SCHEMA_HINT: string;
 export interface RunRecord {
     mode: 'ask' | 'approve' | 'notify' | 'review';
@@ -7,9 +8,35 @@ export interface RunRecord {
     output?: string;
     /** tmux pane id of the detached TUI, recorded so `human cancel` can kill it. */
     pane_id?: string;
+    /** tmux pane id of a review's live termrender render pane, so cancel/finish can clear it. */
+    render_pane_id?: string;
 }
 export declare function resolveMaxPanes(): number;
-export declare function pickPlacement(): 'split-h' | 'new-window';
+export declare function pickPlacement(targetPane?: string): 'split-h' | 'new-window';
+/**
+ * The tmux pane the humanloop TUI should open BESIDE so a PERSON actually sees
+ * it. A prompt raised by a canvas node must NOT land in the backstage `crtr`
+ * session (the holding ground for un-watched node panes) — it lands in the
+ * session the user is watching that node's graph in:
+ *   1. node prompt (CRTR_NODE_ID set) → the HIGHEST FOCUSED node of its graph
+ *      (`graphSurfaceTarget`, the focused node closest to the graph root): split
+ *      beside it, in the session/window the user already has it open in.
+ *   2. nothing in the graph on screen (or a dead focus pane), or a bare-shell
+ *      prompt → the user's currently-attached pane (`attachedClientPane`).
+ *   3. neither resolvable → undefined (tmux falls back to the caller pane).
+ * The TUI lands in the right place but NEVER switches the user's session/window
+ * (no switch-client / select-window; new-window opens `-d`). They see it when
+ * they look at the node they are already watching.
+ */
+export declare function resolveHumanTarget(): string | undefined;
+/**
+ * Open the detached humanloop `_run` pane for an interaction dir, ROUTED to the
+ * session the user is watching (`resolveHumanTarget`). The single spawn path
+ * behind ask/approve/review (`spawnHumanJob`) and notify. `detached: true` keeps
+ * the user's view put — the prompt lands beside the watched node without
+ * jumping their session/window. `jobId`, when given, is injected as CRTR_JOB_ID.
+ */
+export declare function detachHumanTui(idir: string, cwd: string, jobId?: string): DetachResult;
 export declare function runCmd(dir: string): string;
 export declare function followUpResult(_jobId: string): string;
 export declare function followUpDrain(_jobId: string): string;