@crouton-kit/crouter 0.3.14 → 0.3.16

package/dist/commands/human/shared.js

@@ -1,14 +1,12 @@
 import { readConfig } from '../../core/config.js';
 import { spawnSync } from 'node:child_process';
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { atomicWriteJson, readJson } from '@crouton-kit/humanloop';
 import { countPanesInCurrentWindow, spawnAndDetach, shellQuote } from '../../core/spawn.js';
-import { reportsDir } from '../../core/canvas/paths.js';
 export const DECK_SCHEMA_HINT = 'Deck must match the humanloop deck schema: {title?, ' +
     'source?:{sessionName?,askedBy?,blockedSince?}, ' +
     'interactions:[{id,title,subtitle?,(body?|bodyPath?),options:[{id,label,' +
-    'description?,shortcut?}],multiSelect?,allowFreetext?,freetextLabel?,' +
+    'description?}],multiSelect?,allowFreetext?,freetextLabel?,' +
     "kind?:'notify'|'validation'|'decision'|'context'|'error'}]}.";
 export function resolveMaxPanes() {
     return readConfig('user').max_panes_per_window;
@@ -26,17 +24,31 @@ export function followUpDrain(_jobId) {
     return ('Not in tmux: a human must drain it — run `crtr human inbox` (or re-run ' +
         'inside tmux). The answer then arrives in your inbox.');
 }
+/**
+ * Road sign for a spawned `human review`. It is a non-blocking kickoff, so the
+ * text steers the caller to stop rather than wait, verify, or re-present: the
+ * pane is already live and tracks the file, and the comments arrive via the
+ * inbox/wake when the human submits.
+ */
+export function followUpReview(_jobId) {
+    return ("The document is live on the human's screen for anchored, line-by-line " +
+        'review. The pane tracks the file — edit the .md in place and it re-renders ' +
+        'on save, so never cancel and re-present just to show a change. Do not poll, ' +
+        'verify it opened, or background this call; end your turn. The human reviews ' +
+        'on their own time, and their comments (with any line edits) arrive in your ' +
+        'inbox and wake you when they submit.');
+}
 /**
  * Spawn the detached `_run` pane that drives the humanloop TUI for this node.
- * Returns whether the pane spawned, the follow_up text, and (when spawned) the
- * tmux pane id so a blocking caller (review) can detect the pane dying before
- * the human submits. Degrades to the inbox-drain follow_up when not in tmux /
- * spawn fails — kickoffs are intentionally non-fatal off-tmux.
+ * Returns whether the pane spawned and the follow_up road sign. Degrades to the
+ * inbox-drain follow_up when not in tmux / spawn fails — kickoffs are
+ * intentionally non-fatal off-tmux.
  *
  * Completion routing needs no bookkeeping here: the human node was created
  * under the asking node as its parent (spawnNode auto-subscribes the parent),
- * so the `pushFinal` the `_run` worker emits fans the answer straight into the
- * asking node's inbox.
+ * so the `pushFinal` the `_run` worker emits — for ask, approve, AND review —
+ * fans the answer straight into the asking node's inbox. The pane id is recorded
+ * on run.json (not returned) so `human cancel` can later kill the TUI.
  */
 export function spawnHumanJob(jobId, idir, cwd) {
     const spawn = spawnAndDetach({
@@ -57,66 +69,32 @@ export function spawnHumanJob(jobId, idir, cwd) {
         if (rc !== null)
             atomicWriteJson(rcPath, { ...rc, pane_id: spawn.paneId });
     }
-    return {
-        spawned: true,
-        follow_up: followUpResult(jobId),
-        ...(spawn.paneId !== undefined ? { paneId: spawn.paneId } : {}),
-    };
-}
-/** Best-effort kill of a detached TUI pane. No-op (and never throws) when the
- *  pane is already gone or tmux is unavailable — `human cancel` is best-effort. */
-export function killPane(paneId) {
-    const r = spawnSync('tmux', ['kill-pane', '-t', paneId], { encoding: 'utf8' });
-    return r.status === 0;
-}
-/** True when a tmux pane is still alive. */
-function paneAlive(paneId) {
-    const r = spawnSync('tmux', ['display-message', '-p', '-t', paneId, '#{pane_id}'], {
-        encoding: 'utf8',
-    });
-    return r.status === 0 && r.stdout.trim() !== '';
+    return { spawned: true, follow_up: followUpResult(jobId) };
 }
 /**
- * Block until `nodeId` emits a `final` report (the human submitted) or — when a
- * pane id is given — that pane dies before submitting (the human closed it).
- * Polls once a second: this is a human-time operation, so a coarse poll is fine
- * and sidesteps fs.watch directory-existence races. The `_run` worker writes
- * the humanloop result as the report body (JSON), which we parse back out.
+ * Best-effort kill of a humanloop worker pane. SAFETY-CRITICAL: a malformed or
+ * empty `-t` target makes tmux fall back to the CALLER's current pane, so a bad
+ * paneId could kill the agent's own pi pane (and, if it is the last pane, the
+ * whole session). This refuses to kill anything that is not provably the worker:
+ *
+ *   1. paneId must be a real tmux pane id (`%<n>`) — never an empty/odd string.
+ *   2. The pane's start command must contain `verify` (the interaction dir, which
+ *      humanloop bakes into the worker's `CRTR_HUMAN_DIR=... crtr human _run`
+ *      launch). A shell (`zsh -l`) or the agent's pi never matches, so we can
+ *      only ever kill the exact worker we spawned for this job.
+ *
+ * Returns true only when a matching pane was found and killed. Never throws.
  */
-export function waitForFinalReport(nodeId, paneId) {
-    const dir = reportsDir(nodeId);
-    const findFinal = () => {
-        if (!existsSync(dir))
-            return null;
-        const files = readdirSync(dir).filter((f) => f.endsWith('-final.md')).sort();
-        return files.length > 0 ? join(dir, files[files.length - 1]) : null;
-    };
-    const parse = (path) => {
-        const body = readFileSync(path, 'utf8').replace(/^---[\s\S]*?---\n/, '').trim();
-        try {
-            return { status: 'done', result: JSON.parse(body) };
-        }
-        catch {
-            return { status: 'done' };
-        }
-    };
-    const immediate = findFinal();
-    if (immediate !== null)
-        return Promise.resolve(parse(immediate));
-    return new Promise((resolve) => {
-        const timer = setInterval(() => {
-            const p = findFinal();
-            if (p !== null) {
-                clearInterval(timer);
-                resolve(parse(p));
-                return;
-            }
-            if (paneId !== undefined && !paneAlive(paneId)) {
-                clearInterval(timer);
-                resolve({ status: 'closed', reason: 'review pane closed before submit' });
-            }
-        }, 1000);
-        if (typeof timer.unref === 'function')
-            timer.unref();
+export function killPane(paneId, verify) {
+    if (!/^%\d+$/.test(paneId))
+        return false;
+    const probe = spawnSync('tmux', ['display-message', '-p', '-t', paneId, '#{pane_start_command}'], {
+        encoding: 'utf8',
     });
+    // Pane is gone (status !== 0) → nothing to kill. Pane exists but its launch
+    // command doesn't carry our interaction dir → it is NOT our worker; refuse.
+    if (probe.status !== 0 || !probe.stdout.includes(verify))
+        return false;
+    const r = spawnSync('tmux', ['kill-pane', '-t', paneId], { encoding: 'utf8' });
+    return r.status === 0;
 }

package/dist/commands/human.js

@@ -18,24 +18,14 @@ export function registerHuman() {
     return defineBranch({
         name: 'human',
         rootEntry: {
-            concept: 'human-in-the-loop decisions, document review, and live display: ask puts a structured choice to a person, approve gates a handoff on a Yes/No sign-off, review collects anchored comments on a plan or spec, notify informs without blocking, show puts a file live on screen',
+            concept: 'human-in-the-loop decisions, document review, and live display',
             desc: 'ask, approve, review, notify, show, cancel, inbox, list',
-            useWhen: 'you have a question for the user or want their feedback — always reach for human instead of guessing or assuming when a person can decide',
+            useWhen: 'you have a question for the user, want their feedback, or are presenting them with options or a choice — always reach for human instead of guessing or assuming, or laying a choice out as prose, when a person can decide; and whenever the user wants to review a spec, plan, or requirements document, this is the command (use `human review` for anchored line-by-line comments)'
         },
         help: {
             name: 'human',
             summary: 'human-in-the-loop decisions, document review, and live display',
-            model: "Reach for human whenever you have a question for the user or want their feedback — never guess or assume when a person can decide. ask puts a structured choice in front of them; approve gates a handoff on a Yes/No sign-off; review collects anchored comments on a plan or spec; notify informs without blocking; show puts a file live on screen. Every body and displayed file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one. ask/approve/review are the DEFAULT channel for questions, sign-offs, and feedback — reach for them even for quick or open-ended asks (use `allowFreetext`), and don't substitute prose in your reply. ask and approve are kickoffs: they create a kind:'human' node under you and return instantly, never blocking — the answer is pushed to your inbox when the human responds, so just keep working and you'll be woken with it. review is different: it BLOCKS until the human submits, so background the call if you want to keep working (your harness notifies you when it finishes). 'Humans respond on human time' describes response latency only — it is never a reason to avoid asking. notify/show create no node.",
-            children: [
-                { name: 'ask', desc: 'put a decision deck to a person', useWhen: 'a structured choice needs a human' },
-                { name: 'approve', desc: 'a Yes/No approval gate', useWhen: 'gating a handoff on human sign-off' },
-                { name: 'review', desc: 'anchored-comment review of a .md', useWhen: 'a human should comment on a plan or spec' },
-                { name: 'notify', desc: 'fire-and-forget acknowledgement', useWhen: 'informing a person without blocking' },
-                { name: 'show', desc: 'put a file live on screen', useWhen: 'displaying a doc while a human comments' },
-                { name: 'cancel', desc: 'retract a pending ask/approve/review', useWhen: 'a question went stale before the human answered' },
-                { name: 'inbox', desc: 'interactively drain pending interactions', useWhen: 'a human clears the queue at their terminal' },
-                { name: 'list', desc: 'enumerate pending interactions', useWhen: 'discovering what is blocked on a human' },
-            ],
+            model: "Every body and displayed file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one. ask, approve, and review are kickoffs: they create a kind:'human' node under you and return instantly, never blocking — the human's response is pushed to your inbox when they answer, so keep working (or just end your turn) and you'll be woken with it. review puts a .md live on the human's screen for anchored comments and tracks the file, so edit in place rather than canceling and re-presenting. notify and show create no node.",
         },
         children: [
             humanAsk,
@@ -43,9 +33,9 @@ export function registerHuman() {
             humanReview,
             humanNotify,
             humanShow,
+            humanCancel,
             humanInbox,
             humanList,
-            humanCancel,
             humanRun,
         ],
     });

package/dist/commands/node.d.ts

@@ -1,2 +1,13 @@
 import { type BranchDef } from '../core/command.js';
+/** Decision road sign for a managed (non-root) child. Normally STD_CHILD_FOLLOW_UP,
+ *  but when the SPAWNER is an orchestrator whose context has already grown past
+ *  YIELD_NUDGE_THRESHOLD, steer it to yield now and let its fresh revive handle
+ *  the child's result. */
+export declare function childFollowUp(spawnerId: string | undefined): string;
+/** The live node occupying a tmux pane (pane → window → node), or undefined.
+ *  Defaults to $TMUX_PANE / the caller's current pane when `pane` is omitted —
+ *  shared by `node demote` and `node cycle`, both of which act on "the agent in
+ *  front of you". Exported for the `canvas chord` / `canvas tmux-spread` leaves,
+ *  which resolve the active pane's node the same way. */
+export declare function nodeInPane(pane?: string): string | undefined;
 export declare function registerNode(): BranchDef;