@crouton-kit/crouter 0.3.82 → 0.3.83

package/dist/clients/attach/attach-def.d.ts

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

package/dist/clients/attach/attach-def.js

@@ -0,0 +1,93 @@
+// attach-def.ts — the LIGHT `crtr surface attach` command definition.
+//
+// This module holds only the command metadata (help schema, flags) and the
+// thin `run` entry. It is deliberately kept OFF the heavy pi-coding-agent module
+// graph so that registering the `surface` subtree — for `surface view`,
+// `surface web`, `surface workspace`, `surface tmux-spread`, and every
+// `surface -h` render — costs a cheap command-framework load, not the ~363ms
+// ESM load of the esbuild-bundled attach viewer (`attach-cmd.ts`, which pulls
+// pi-coding-agent's babel/highlight.js). The viewer runtime is dynamically
+// imported inside `run`, so the bundle loads ONLY when a viewer actually opens.
+import { defineBranch, defineLeaf } from '../../core/command.js';
+const attachToLeaf = defineLeaf({
+    name: 'to',
+    description: 'attach an interactive terminal viewer to a node\'s running broker',
+    whenToUse: 'you want to WATCH or DRIVE a headless node live in this pane — it connects over the node\'s unix socket to the broker that is already hosting the engine and renders the same chat stream, letting you type prompts (as the controller) or follow read-only (as an observer). It does NOT start the engine: the node must already have a running headless broker (focus or revive it first). One controller drives; extra viewers are read-only. The configured detach shortcuts leave the engine running',
+    help: {
+        name: 'attach to',
+        summary: 'attach a terminal viewer to a headless node\'s running broker (controller by default, --observer for read-only); configured detach shortcuts leave the engine running',
+        params: [
+            {
+                kind: 'positional',
+                name: 'node',
+                required: true,
+                constraint: 'Node id to attach to. Must already have a running headless broker.',
+            },
+            {
+                kind: 'flag',
+                name: 'observer',
+                type: 'bool',
+                required: false,
+                default: false,
+                constraint: 'Attach READ-ONLY: never claim control even if it is free. Default: drive (claim control if available, else fall back to read-only).',
+            },
+            {
+                kind: 'flag',
+                name: 'canvas',
+                type: 'string',
+                required: false,
+                constraint: 'Attach against a remote canvas target configured via `crtr canvas config add` instead of the local canvas — connects over a relayed WebSocket to the target\'s preview endpoint using the relay token from the 0600 secrets store. Omit for local (default): connects to the node\'s local unix socket, which must already exist in THIS machine\'s canvas.db. Does NOT honor `crtr canvas use` — this flag is the only way to attach remotely.',
+            },
+        ],
+        output: [
+            {
+                name: 'note',
+                type: 'string',
+                required: false,
+                constraint: 'Only set on the non-TTY/piped path (a static notice); the interactive path returns nothing.',
+            },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Takes over the current pane in raw mode and renders the node\'s live engine stream until you use a configured detach shortcut or the broker exits.',
+            'As controller: sends prompts/steers/dialog answers to the engine over the socket. As observer: read-only.',
+            'NEVER spawns pi and NEVER writes the session — it holds only a socket to the existing broker.',
+            'Outside a TTY (piped): prints a short notice and exits 0 — attach is an interactive program, not a pipe stage.',
+        ],
+    },
+    run: async (input) => {
+        const nodeId = input['node'];
+        const observer = input['observer'] ?? false;
+        const canvasName = input['canvas'];
+        // attach IS the in-pane interactive program — it only needs a TTY (crtr is
+        // tmux-only, but the pane itself is the surface). Non-TTY (piped) → static
+        // notice + exit, never a non-tmux interactive fallback. Guarded BEFORE the
+        // heavy import so a piped invocation never pays the viewer's load cost.
+        if (!process.stdout.isTTY) {
+            return {
+                note: `crtr surface attach is an interactive terminal viewer — run it in a tmux pane (a TTY), not a pipe. Node: ${nodeId}`,
+            };
+        }
+        // The viewer runtime (the pi-coding-agent-heavy bundle) loads only here.
+        const { runAttach } = await import('./attach-cmd.js');
+        await runAttach(nodeId, observer, canvasName);
+        return;
+    },
+    render: (result) => (result['note'] !== undefined ? String(result['note']) : ''),
+});
+export function registerAttach() {
+    return defineBranch({
+        name: 'attach',
+        rootEntry: {
+            concept: 'a terminal viewer for a headless node — connect over its socket and drive (or watch) the live engine',
+            desc: 'attach a terminal viewer to a headless node',
+            useWhen: 'you want to open a headless node live in this pane — watch its engine stream and drive it by typing, without the node ever running pi in your window. The node must already have a running headless broker; attach connects to it over a unix socket and never starts the engine itself. Configured detach shortcuts leave the engine running.',
+        },
+        help: {
+            name: 'attach',
+            summary: 'attach a terminal viewer to a headless node\'s running broker',
+            model: 'The branch opens a viewer in the current pane. A TTY is required; piped invocation prints a notice and exits. By default it claims control and drives the engine; --observer follows read-only. One controller plus any number of observers may watch a node. Configured detach shortcuts detach cleanly and the engine runs on. If the broker exits, the viewer holds the pane and auto-reconnects — through a yield/refresh relaunch, and across dormancy until the node wakes again — reporting "broker gone" and exiting only when the node is terminal (done/dead/canceled) or deleted. attach NEVER spawns pi or writes the session — it holds only a socket to the broker, which must already be running. --canvas <name> is the escape hatch for a node hosted on a different machine\'s canvas — see the leaf\'s own -h.',
+        },
+        children: [attachToLeaf],
+    });
+}

package/dist/clients/attach/canvas-panels.d.ts

@@ -3,10 +3,17 @@ import type { AttachPalette } from './config-load.js';
 export interface CanvasPanelLines {
     /** Above-editor manager line(s) — empty for a root node (no manager). */
     managers: string[];
-    /** Below-editor report row(s) + self's trailing ⚑ asks line — empty when none. */
+    /** Below-editor report row(s) + self's trailing ⚑ pending-ticket line — empty when none. */
     reports: string[];
+    /** Node ids backing the manager row(s), in render order — the roster's UP leg
+     *  (toward main). Drives the attach viewer's inline scroll+swap selection. */
+    managerIds: string[];
+    /** Node ids backing the report row(s), in render order — the roster's DOWN leg
+     *  (the live subagents). Excludes the trailing ⚑ self-asks line. */
+    reportIds: string[];
 }
 /** Build the BASE panel line stacks for `nodeId`. `asks` is the per-node
- *  pending-ask map the caller polls; pass `{}` to omit the ⚑ badges. `palette`
+ *  pending human-ticket count map the caller polls (deck/review/notify); pass
+ *  `{}` to omit the ⚑ badges. `palette`
  *  drives the headers + dim cells; omit it and the panels render uncolored. */
-export declare function buildCanvasPanelLines(nodeId: string, asks: Record<string, number>, palette?: AttachPalette, source?: CanvasSource): Promise<CanvasPanelLines>;
+export declare function buildCanvasPanelLines(nodeId: string, asks: Record<string, number>, palette?: AttachPalette, source?: CanvasSource, selectedId?: string): Promise<CanvasPanelLines>;

package/dist/clients/attach/canvas-panels.js

@@ -1,17 +1,24 @@
 // canvas-panels.ts — the subscribed-node panel for `crtr surface attach` (Unit Q).
 //
 // Reads through the CanvasSource seam so the viewer chrome and graph overlay
-// share the same canvas read authority. Produces the two line stacks the viewer paints
+// share the same canvas read authority. Produces the line stacks the viewer paints
 // into Containers around the editor:
-//   managers  → ABOVE the editor: this node's manager (its first subscriber).
-//   reports   → BELOW the editor: this node's live reports (active|idle
-//               subscriptions), plus a trailing ⚑ line for self's own asks.
+//   managers  → always empty: nothing is shown ABOVE the editor. The manager is
+//               folded into the one list below (see reports), so the roster is a
+//               single stable list, not a split above/below layout.
+//   reports   → BELOW the editor: the ONE stable family roster — the subagent
+//               set's root (self's non-human manager, or self when it is the
+//               root) followed by that root's live (active|idle) children — plus
+//               a trailing ⚑ line for self's own pending human tickets (asks,
+//               reviews, notifications). The SAME list shows for every family
+//               member; the one this viewer is attached to is the highlighted
+//               row. Backs the attach viewer's inline scroll+swap.
 //
-// Pure: given a node id + the per-node ask map it returns ANSI strings; the
+// Pure: given a node id + the per-node ticket-count map it returns ANSI strings; the
 // caller owns the Containers and the refresh trigger. beginFrame() clears the
 // nav-model telemetry cache for this one build pass so token/activity cells are
 // read fresh for every chrome frame.
-import { beginFrame, navLabel, nodeGlyph, truncate, tokensCell, cycleBadge, askBadge, activityCell, YELLOW, RESET, DIM, GREEN, } from '../../core/canvas/nav-model.js';
+import { beginFrame, navLabel, nodeGlyph, truncate, tokensCell, cycleBadge, askBadge, activityCell, fillBar, fillWidth, YELLOW, RESET, DIM, GREEN, REVERSE, BG_ATTACHED, } from '../../core/canvas/nav-model.js';
 import { localCanvasSource } from '../../core/canvas/source.js';
 import { RemoteCanvasSource } from '../../core/canvas/remote-canvas-source.js';
 /** Column widths for the aligned panel rows (visible columns). name is sized to
@@ -30,9 +37,10 @@ function padStartVisible(s, w) {
     return s.length >= w ? s.slice(0, w) : ' '.repeat(w - s.length) + s;
 }
 /** Build the BASE panel line stacks for `nodeId`. `asks` is the per-node
- *  pending-ask map the caller polls; pass `{}` to omit the ⚑ badges. `palette`
+ *  pending human-ticket count map the caller polls (deck/review/notify); pass
+ *  `{}` to omit the ⚑ badges. `palette`
  *  drives the headers + dim cells; omit it and the panels render uncolored. */
-export async function buildCanvasPanelLines(nodeId, asks, palette, source = localCanvasSource) {
+export async function buildCanvasPanelLines(nodeId, asks, palette, source = localCanvasSource, selectedId) {
     // A remote source provides only graph structure + node metadata; tokens/
     // activity/status-glyph adornments are local disk reads (telemetry.json,
     // fault state, pid liveness) and are suppressed to safe defaults below —
@@ -126,9 +134,20 @@ export async function buildCanvasPanelLines(nodeId, asks, palette, source = loca
     const muted = palette?.muted ?? ((s) => s);
     const faint = palette?.faint ?? ((s) => s);
     await computeActivity(await climbRoot(nodeId));
-    const mgr = await managerOf(nodeId);
-    const live = await liveReports(nodeId);
-    const gridIds = [...(mgr !== undefined ? [mgr] : []), ...live];
+    // ONE stable family roster, shown BELOW the editor and NOTHING above it
+    // (Claude-Code style): the root of this subagent set — self's (non-human)
+    // manager, or self when it is the root — followed by that root's live children.
+    // The SAME list appears no matter which family member you're viewing; the one
+    // you're in is the highlighted row. The manager is folded in as the top entry
+    // (root-first), so "up to main" is just scrolling up the same list — no
+    // separate parent panel above the box. A solo node with no family shows nothing.
+    const mgrRaw = await managerOf(nodeId);
+    const mgr = mgrRaw !== undefined && (await node(mgrRaw))?.kind !== 'human' ? mgrRaw : undefined;
+    const rosterRoot = mgr ?? nodeId;
+    const kids = await liveReports(rosterRoot);
+    const family = [rosterRoot, ...kids.filter((id) => id !== rosterRoot)];
+    const live = family.length > 1 ? family : [];
+    const gridIds = live;
     const gridNodes = await Promise.all(gridIds.map((id) => node(id)));
     const nameW = gridIds.length > 0
         ? Math.min(NAME_CAP, Math.max(...gridIds.map((id, i) => navLabel(gridNodes[i] ?? null, id).length)))
@@ -139,16 +158,23 @@ export async function buildCanvasPanelLines(nodeId, asks, palette, source = loca
         const kind = faint(nameCell(n?.kind ?? '', KIND_W));
         const tokens = muted(padStartVisible(tokensCell(id, remote), TOK_W));
         const badges = `${cycleBadge(n)}${await childBadgeFor(n)}${liveBelowBadgeFor(n)}${askBadge(id, asks)}${activityCell(id, n, remote)}`;
-        return truncate(` ${nodeGlyph(n, remote)} ${name}  ${kind} ${tokens}${badges}`);
+        const line = ` ${nodeGlyph(n, remote)} ${name}  ${kind} ${tokens}${badges}`;
+        // Two roster highlights: the roving nav cursor (strong REVERSE, mirroring the
+        // graph overlay's cursor) wins; otherwise the node this viewer is CURRENTLY
+        // attached to — self, when it sits among its siblings — gets the subtler
+        // you-are-here bar so you always see which subagent you're in.
+        if (id === selectedId)
+            return fillBar(line, fillWidth(), REVERSE);
+        if (id === nodeId)
+            return fillBar(line, fillWidth(), BG_ATTACHED);
+        return truncate(line);
     };
-    const managers = [];
-    if (mgr !== undefined)
-        managers.push(await row(mgr));
     const reports = [];
     for (const id of live)
         reports.push(await row(id));
     const selfAsks = asks[nodeId] ?? 0;
     if (selfAsks > 0)
         reports.push(` ${YELLOW}⚑ ${selfAsks} pending${RESET}`);
-    return { managers, reports };
+    // Nothing above the editor: the whole family lives in the one list below.
+    return { managers: [], reports, managerIds: [], reportIds: [...live] };
 }

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

@@ -59,6 +59,17 @@ export declare class ChatView {
     private bashComponent;
     /** The single active activity loader (working/compaction/retry), if any. */
     private activityLoader;
+    /** True while applySnapshot is mid-build; live broker frames defer instead of
+     *  mutating the partially-rebuilt view. */
+    private applyingSnapshot;
+    /** Bumped on every applySnapshot. A build suspended at a yield compares this
+     *  after resuming and abandons itself when a newer welcome has bumped it, so
+     *  the newest welcome wins and stale state never overwrites the live view. */
+    private snapshotGeneration;
+    /** Live frames captured during an in-flight build (bound closures that re-run
+     *  the original entry point), replayed in order when the build completes and
+     *  dropped when a newer welcome supersedes the build. */
+    private readonly deferredFrames;
     /** Text of the most recent assistant message, kept current from the welcome
      *  snapshot AND the live event stream so `/copy` (getLastAssistantText) works
      *  whether the message arrived before or after attach. */
@@ -69,7 +80,15 @@ export declare class ChatView {
      *  tool-execution components matched to their toolResult messages; everything
      *  else routes through `addMessageToChat`. The TUI's differential renderer +
      *  reflow-on-resize is automatic — no scrollback reconstruction needed. */
-    applySnapshot(snapshot: BrokerSnapshot): void;
+    applySnapshot(snapshot: BrokerSnapshot): Promise<void>;
+    /** Defer a live broker frame when a snapshot build is in flight. Returns true
+     *  (and enqueues the replay closure) while building so the caller returns
+     *  without mutating the half-rebuilt view; false when the caller may proceed.
+     *  This is the single-writer gate every live-frame entry point passes through. */
+    private deferIfBuilding;
+    /** Replay deferred live frames in wire order. The gate is already open, so each
+     *  closure re-enters its entry point and dispatches immediately. */
+    private replayDeferredFrames;
     /** Stop any spinning activity loader. A one-shot `crtr surface attach` process lets its
      *  timers die with the process, but if T7 reuses a ChatView across reconnects in
      *  one process it should call this on detach to avoid a leaked interval. */

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

@@ -40,6 +40,10 @@ const CONTEXT_INTRO_CUSTOM_TYPE = 'crtr-context';
  *  themselves still use `getMarkdownTheme()` for full-fidelity rendering. */
 const defaultSpinnerStyle = (s) => `\x1b[2m${s}\x1b[22m`;
 const defaultDimStyle = (s) => `\x1b[2m${s}\x1b[22m`;
+/** How many catch-up messages `applySnapshot` builds between event-loop yields.
+ *  Keeps large non-streaming snapshots from monopolizing the main thread so
+ *  queued keystrokes are serviced during construction. */
+const SNAPSHOT_YIELD_EVERY = 50;
 /** A component supports the Ctrl+O global tool-output toggle. Mirrors pi's
  *  `isExpandable` duck-type (interactive-mode.js): any rendered child carrying a
  *  `setExpanded(boolean)` method — tool executions, custom/compaction/branch/skill
@@ -125,6 +129,25 @@ export class ChatView {
     bashComponent;
     /** The single active activity loader (working/compaction/retry), if any. */
     activityLoader;
+    // -- Single-writer snapshot ordering -------------------------------------
+    // A non-streaming catch-up yields to the event loop mid-build (so queued stdin
+    // drains), which opens a window where later broker frames could otherwise
+    // mutate a half-rebuilt transcript. These three fields make the ChatView a
+    // single ordered writer: applySnapshot is the only thing that mutates the
+    // view while a build is in flight, live frames are deferred and replayed in
+    // wire order once it finishes, and a newer welcome always supersedes an older
+    // build. See applySnapshot / deferIfBuilding.
+    /** True while applySnapshot is mid-build; live broker frames defer instead of
+     *  mutating the partially-rebuilt view. */
+    applyingSnapshot = false;
+    /** Bumped on every applySnapshot. A build suspended at a yield compares this
+     *  after resuming and abandons itself when a newer welcome has bumped it, so
+     *  the newest welcome wins and stale state never overwrites the live view. */
+    snapshotGeneration = 0;
+    /** Live frames captured during an in-flight build (bound closures that re-run
+     *  the original entry point), replayed in order when the build completes and
+     *  dropped when a newer welcome supersedes the build. */
+    deferredFrames = [];
     /** Text of the most recent assistant message, kept current from the welcome
      *  snapshot AND the live event stream so `/copy` (getLastAssistantText) works
      *  whether the message arrived before or after attach. */
@@ -163,12 +186,34 @@ export class ChatView {
      *  tool-execution components matched to their toolResult messages; everything
      *  else routes through `addMessageToChat`. The TUI's differential renderer +
      *  reflow-on-resize is automatic — no scrollback reconstruction needed. */
-    applySnapshot(snapshot) {
+    async applySnapshot(snapshot) {
+        // Open a new build generation. Any older build still suspended at a yield
+        // abandons itself when it resumes (generation check below), and live frames
+        // that were deferred against the transcript we are about to discard are
+        // dropped — a newer welcome always wins.
+        const generation = ++this.snapshotGeneration;
+        this.applyingSnapshot = true;
+        this.deferredFrames.length = 0;
         this.resetChat();
         const renderedPendingTools = new Map();
         const messages = snapshot.messages;
         const lastIndex = messages.length - 1;
         for (let i = 0; i < messages.length; i++) {
+            // Yield to the event loop every SNAPSHOT_YIELD_EVERY messages so queued
+            // stdin drains (keystrokes are handled instead of bursting after a long
+            // catch-up) while a big transcript constructs. Skipped for a STREAMING
+            // snapshot: its in-flight tail + pending tools must be bound before any
+            // relayed message_update/message_end lands, so it builds synchronously
+            // (no await → no broker frame can interleave and freeze the live bubble).
+            if (!snapshot.state.isStreaming &&
+                i > 0 &&
+                i % SNAPSHOT_YIELD_EVERY === 0) {
+                await new Promise((resolve) => setImmediate(resolve));
+                // A newer welcome arrived while we were suspended — abandon this stale
+                // build without touching the view (or the gate) it no longer owns.
+                if (generation !== this.snapshotGeneration)
+                    return;
+            }
             const message = messages[i];
             if (message.role === 'assistant') {
                 // Keep the `/copy` source current from the catch-up transcript too, not
@@ -231,6 +276,28 @@ export class ChatView {
         if (snapshot.state.isStreaming)
             this.setActivity(this.makeLoader('Working...'));
         this.tui.requestRender();
+        // Build complete and still current (a mismatch would have returned above):
+        // open the gate and replay, in wire order, any live frames that arrived
+        // during construction so they land on the finished transcript.
+        this.applyingSnapshot = false;
+        this.replayDeferredFrames();
+    }
+    /** Defer a live broker frame when a snapshot build is in flight. Returns true
+     *  (and enqueues the replay closure) while building so the caller returns
+     *  without mutating the half-rebuilt view; false when the caller may proceed.
+     *  This is the single-writer gate every live-frame entry point passes through. */
+    deferIfBuilding(replay) {
+        if (!this.applyingSnapshot)
+            return false;
+        this.deferredFrames.push(replay);
+        return true;
+    }
+    /** Replay deferred live frames in wire order. The gate is already open, so each
+     *  closure re-enters its entry point and dispatches immediately. */
+    replayDeferredFrames() {
+        const frames = this.deferredFrames.splice(0);
+        for (const replay of frames)
+            replay();
     }
     /** Stop any spinning activity loader. A one-shot `crtr surface attach` process lets its
      *  timers die with the process, but if T7 reuses a ChatView across reconnects in
@@ -274,6 +341,10 @@ export class ChatView {
     // exactly as interactive pi falls through default for those two).
     // -------------------------------------------------------------------------
     handleEvent(event) {
+        // Order behind an in-flight catch-up: a live turn that starts while a large
+        // welcome is still building is replayed after it, never interleaved into it.
+        if (this.deferIfBuilding(() => this.handleEvent(event)))
+            return;
         switch (event.type) {
             case 'agent_start': {
                 this.pendingTools.clear();
@@ -444,7 +515,13 @@ export class ChatView {
             default:
                 break;
         }
-        this.historyContainer.markDirty();
+        // No unconditional markDirty here: history-mutating branches already
+        // invalidate the cache the moment they touch the container — appends/removes
+        // go through RenderCacheContainer.addChild/removeChild (which markDirty), and
+        // every in-place child mutation (message_update/message_end, tool_execution_*)
+        // runs while the container is volatile (agent_start set it), where the cache
+        // is bypassed entirely. Footer-only, ignored (turn_start/turn_end), and
+        // activity-only events thus no longer nuke the settled-history render cache.
         this.tui.requestRender();
     }
     // -------------------------------------------------------------------------
@@ -454,6 +531,8 @@ export class ChatView {
     // also rides the next snapshot, so this only drives the LIVE view.
     // -------------------------------------------------------------------------
     bashStart(command, excludeFromContext) {
+        if (this.deferIfBuilding(() => this.bashStart(command, excludeFromContext)))
+            return;
         const component = new BashExecutionComponent(command, this.tui, excludeFromContext);
         this.bashComponent = component;
         this.historyContainer.setVolatile(true);
@@ -461,11 +540,15 @@ export class ChatView {
         this.tui.requestRender();
     }
     bashOutput(chunk) {
+        if (this.deferIfBuilding(() => this.bashOutput(chunk)))
+            return;
         this.bashComponent?.appendOutput(chunk);
         this.historyContainer.markDirty();
         this.tui.requestRender();
     }
     bashEnd(result) {
+        if (this.deferIfBuilding(() => this.bashEnd(result)))
+            return;
         this.bashComponent?.setComplete(result.exitCode, result.cancelled, result.truncated ? { truncated: true } : undefined, result.fullOutputPath);
         this.bashComponent = undefined;
         this.historyContainer.setVolatile(false);

package/dist/commands/__tests__/human.test.js

@@ -220,12 +220,15 @@ describe('human cancel: behavior', () => {
         assert.equal(r['canceled'], false);
         assert.equal(r['reason'], 'already_resolved');
     });
-    test('live node with no pane → retires the node (status done)', async () => {
+    test('live node with no request descriptor → already_resolved (nothing to cancel)', async () => {
+        // A live bridge whose interaction dir holds no deck.json/review.json has no
+        // humanloop ticket to race a cancellation against, so the !hasDescriptor
+        // guard short-circuits to already_resolved and never transitions the node.
         createNode(humanNode('live-1', { status: 'active' }));
         const r = await humanCancel.run({ job_id: 'live-1' });
-        assert.equal(r['canceled'], true);
-        assert.equal(r['job_id'], 'live-1');
-        assert.equal(getNode('live-1')?.status, 'done');
+        assert.equal(r['canceled'], false);
+        assert.equal(r['reason'], 'already_resolved');
+        assert.equal(getNode('live-1')?.status, 'active');
     });
 });
 // ---------------------------------------------------------------------------
@@ -253,21 +256,3 @@ describe('human list: params', () => {
         assert.equal(result['cursor'], 'tok_abc123');
     });
 });
-// ---------------------------------------------------------------------------
-// human _run — no params (reads CRTR_HUMAN_DIR from env)
-// ---------------------------------------------------------------------------
-describe('human _run: no params', () => {
-    const params = [];
-    test('empty argv yields empty result (no params declared)', async () => {
-        const result = await parseArgv(params, []);
-        assert.deepEqual(result, {});
-    });
-    test('positional token throws bad_invocation (no positionals declared)', async () => {
-        await assert.rejects(() => parseArgv(params, ['some-value']), (err) => { assert.match(err.message, /takes no positional/); return true; });
-    });
-    test('CRTR_HUMAN_DIR env var contract: _run reads it from env, not argv', () => {
-        // Structural check: the params array is empty, confirming no argv surface.
-        // The actual env-var read is in the run handler and verified by inspection.
-        assert.equal(params.length, 0);
-    });
-});

package/dist/commands/attention.js

@@ -1,51 +1,52 @@
-// `crtr canvas attention` — aggregate pending human asks across the canvas.
+// `crtr canvas attention` — aggregate pending human tickets across the canvas.
 //
-// Pending asks are stored per-cwd by humanloop. This subtree surfaces two
-// public views:
+// A pending "ticket" is any humanloop interaction awaiting a human: a deck
+// (ask), a notify deck, or an anchored review. They are stored per-cwd by
+// humanloop. This subtree surfaces two public views:
 //   count  — a single integer (stdout.count is machine-parseable)
-//   list   — itemised entries with cwd, node id, and per-cwd ask count
+//   list   — itemised entries with cwd, node id, and per-cwd ticket count
 // `map` (hidden) is the batched per-node form the attach viewer's nav chrome
 // polls; it is not an agent-facing decision.
 //
 // All three scope modes share the same underlying helpers in attention.ts:
-//   --node <id>   → countAsks(id)             (one cwd)
-//   --view <id>   → pendingAsksForView(id)     (sub-DAG from root)
-//   (neither)     → asksAcrossCanvas()         (whole canvas)
+//   --node <id>   → countTickets(id)            (one cwd)
+//   --view <id>   → pendingTicketsForView(id)    (sub-DAG from root)
+//   (neither)     → ticketsAcrossCanvas()        (whole canvas)
 //
 // Exported as a branch; `crtr canvas` (canvas.ts) mounts it.
 import { defineBranch, defineLeaf } from '../core/command.js';
 import { InputError } from '../core/io.js';
 import { getNode, view } from '../core/canvas/index.js';
-import { countAsks, pendingAsksForView, asksAcrossCanvas, asksForNodes, } from '../core/canvas/attention.js';
+import { countTickets, pendingTicketsForView, ticketsAcrossCanvas, ticketCountsForNodes, } from '../core/canvas/attention.js';
 // ---------------------------------------------------------------------------
 // attention count
 // ---------------------------------------------------------------------------
 const attentionCount = defineLeaf({
     name: 'count',
-    description: 'total pending ask count (machine-parseable stdout.count)',
+    description: 'total pending human-ticket count (machine-parseable stdout.count)',
     whenToUse: 'a lightweight summary when you just need the number, not which cwds are blocked — scope it to a node or a sub-DAG, or default to canvas-wide. Use `list` when you need to act on where to go answer.',
     help: {
         name: 'canvas attention count',
         // stdout.count is parsed directly by the nav chrome — keep the contract.
-        summary: 'return the number of pending human asks; stdout.count is machine-parseable',
+        summary: 'return the number of pending human tickets (asks, reviews, notifications); stdout.count is machine-parseable',
         params: [
             {
                 kind: 'flag',
                 name: 'node',
                 type: 'string',
                 required: false,
-                constraint: 'Count asks only for this node\'s cwd. Mutually exclusive with --view.',
+                constraint: 'Count tickets only for this node\'s cwd. Mutually exclusive with --view.',
             },
             {
                 kind: 'flag',
                 name: 'view',
                 type: 'string',
                 required: false,
-                constraint: 'Sum asks for all nodes in the sub-DAG rooted at this id. Mutually exclusive with --node.',
+                constraint: 'Sum tickets for all nodes in the sub-DAG rooted at this id. Mutually exclusive with --node.',
             },
         ],
         output: [
-            { name: 'count', type: 'integer', required: true, constraint: 'Total pending asks in the requested scope.' },
+            { name: 'count', type: 'integer', required: true, constraint: 'Total pending human tickets in the requested scope.' },
         ],
         outputKind: 'object',
         effects: ['Read-only: scans humanloop interaction dirs.'],
@@ -69,7 +70,7 @@ const attentionCount = defineLeaf({
                     next: 'List nodes with `crtr node inspect list`.',
                 });
             }
-            return { count: countAsks(nodeId) };
+            return { count: countTickets(nodeId) };
         }
         if (viewId !== undefined) {
             if (getNode(viewId) === null) {
@@ -79,12 +80,12 @@ const attentionCount = defineLeaf({
                     next: 'List nodes with `crtr node inspect list`.',
                 });
             }
-            const items = pendingAsksForView(viewId);
+            const items = pendingTicketsForView(viewId);
             const total = items.reduce((s, e) => s + e.count, 0);
             return { count: total };
         }
         // Canvas-wide.
-        const items = asksAcrossCanvas();
+        const items = ticketsAcrossCanvas();
         const total = items.reduce((s, e) => s + e.count, 0);
         return { count: total };
     },
@@ -94,11 +95,11 @@ 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 it to a sub-DAG or list canvas-wide. Use `canvas attention count` instead when you just need the number.',
+    description: 'itemised list of cwds with pending human tickets',
+    whenToUse: 'finding which agents are blocked waiting on a human — an itemised list of the cwds with pending tickets (asks, reviews, notifications), 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 you just need the number.',
     help: {
         name: 'canvas attention list',
-        summary: 'list nodes with pending human asks, grouped by cwd, oldest first',
+        summary: 'list nodes with pending human tickets, grouped by cwd, oldest first',
         params: [
             {
                 kind: 'flag',
@@ -131,10 +132,10 @@ const attentionList = defineLeaf({
                     next: 'List nodes with `crtr node inspect list`.',
                 });
             }
-            items = pendingAsksForView(viewId);
+            items = pendingTicketsForView(viewId);
         }
         else {
-            items = asksAcrossCanvas();
+            items = ticketsAcrossCanvas();
         }
         const total = items.reduce((s, e) => s + e.count, 0);
         return { items, total };
@@ -145,12 +146,12 @@ const attentionList = defineLeaf({
 // ---------------------------------------------------------------------------
 const attentionMap = defineLeaf({
     name: 'map',
-    description: 'per-node ask counts for a visible set, batched in one pass',
-    whenToUse: 'labelling every node in a UI with its pending-ask count in one batched pass — the form nav chrome polls (one process, one JSON blob) instead of N count shell-outs',
+    description: 'per-node ticket counts for a visible set, batched in one pass',
+    whenToUse: 'labelling every node in a UI with its pending-ticket count in one batched pass — the form nav chrome polls (one process, one JSON blob) instead of N count shell-outs',
     tier: 'hidden',
     help: {
         name: 'canvas attention map',
-        summary: 'per-node pending-ask counts for a visible set of nodes in ONE pass — the batched form the nav chrome polls (one process, one JSON blob) instead of N count shell-outs',
+        summary: 'per-node pending human-ticket counts for a visible set of nodes in ONE pass — the batched form the nav chrome polls (one process, one JSON blob) instead of N count shell-outs',
         params: [
             {
                 kind: 'flag',
@@ -172,7 +173,7 @@ const attentionMap = defineLeaf({
                 name: 'counts',
                 type: 'object',
                 required: true,
-                constraint: 'Map of node_id → pending ask count. Every requested id is present (0 when none).',
+                constraint: 'Map of node_id → pending human-ticket count. Every requested id is present (0 when none).',
             },
         ],
         outputKind: 'object',
@@ -205,7 +206,7 @@ const attentionMap = defineLeaf({
             for (const id of nodesRaw.split(',').map((s) => s.trim()).filter((s) => s !== ''))
                 ids.add(id);
         }
-        return { counts: asksForNodes([...ids]) };
+        return { counts: ticketCountsForNodes([...ids]) };
     },
 });
 // ---------------------------------------------------------------------------
@@ -213,12 +214,12 @@ 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 or list the cwds that have them. 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',
+    description: 'count/list pending human tickets across the graph',
+    whenToUse: 'checking whether any agent on the canvas is blocked waiting on a human, and where: count the pending tickets (asks, reviews, notifications) or list the cwds that have them. 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',
-        model: '`count` returns a single integer (stdout.count is machine-parseable); `list` returns itemised entries — the cwds with pending asks, oldest first. Scope with --node (one node) or --view (sub-DAG) — default is canvas-wide.',
+        summary: 'aggregate pending human tickets across the canvas',
+        model: '`count` returns a single integer (stdout.count is machine-parseable); `list` returns itemised entries — the cwds with pending tickets, oldest first. Scope with --node (one node) or --view (sub-DAG) — default is canvas-wide. A ticket is any humanloop interaction awaiting a human: an ask, a review, or a notification.',
     },
     children: [attentionCount, attentionList, attentionMap],
 });