@crouton-kit/crouter 0.3.3 → 0.3.11

package/dist/commands/debug.js

@@ -1,14 +1,14 @@
-// `crtr flow debug` leaf — reproduce-first root-cause workflow.
+// `crtr mode debug` leaf — reproduce-first root-cause workflow.
 //
 // Running it spawns a reproduction-only agent in a sibling tmux pane (the same
-// spawn + job-handle shape as `crtr job start prompt`) and returns a job handle
+// spawn + job-handle shape as `crtr agent new`) and returns a job handle
 // plus a follow_up. The orchestrator-side methodology lives in FLOW_DEBUG_GUIDE
-// (the leaf's help.guide), loaded via `crtr flow debug -h` after the repro
+// (the leaf's help.guide), loaded via `crtr mode debug -h` after the repro
 // agent returns. Methodology stays in the CLI guide field, like PLAN_NEW_GUIDE;
 // no builtin skill.
 export const FLOW_DEBUG_GUIDE = `## Debug workflow — reproduce first
 
-Audience: the agent that ran \`crtr flow debug\`. A reproduction agent is
+Audience: the agent that ran \`crtr mode debug\`. A reproduction agent is
 already spawned in a sibling pane. It writes ONE failing integration test and
 never fixes anything. You do everything after: gate on the repro, root-cause,
 fix, verify against that same test.
@@ -82,7 +82,7 @@ function assertTmux() {
     if (!isInTmux()) {
         throw new InputError({
             error: 'not_in_tmux',
-            message: 'crtr flow debug requires tmux (TMUX env var not set).',
+            message: 'crtr mode debug requires tmux (TMUX env var not set).',
             next: 'Run inside a tmux session.',
         });
     }
@@ -91,7 +91,7 @@ export function registerDebug() {
     return defineLeaf({
         name: 'debug',
         help: {
-            name: 'flow debug',
+            name: 'mode debug',
             summary: 'reproduce-first root-cause workflow: spawns a reproduction agent, then you root-cause and fix',
             guide: FLOW_DEBUG_GUIDE,
             params: [
@@ -137,6 +137,19 @@ export function registerDebug() {
                 'On completion, result writes atomically to result.json.',
             ],
         },
+        slash: {
+            name: 'debug',
+            description: 'Debug mode — reproduce-first root-cause investigation.',
+            argumentHint: '<symptom or failing test>',
+            body: `You are entering **debug mode**: a reproduce-first, root-cause investigation.
+
+1. Run \`crtr mode debug -h\` to load the debugging workflow and output schema.
+2. Follow it — reproduce the failure first, then isolate the root cause before proposing a fix.
+
+The issue: $ARGUMENTS
+
+If no issue was given, ask the user for the symptom or failing test before starting.`,
+        },
         run: async (input) => {
             assertTmux();
             const stepsToReproduce = input['steps_to_reproduce'];
@@ -172,7 +185,7 @@ export function registerDebug() {
             });
             return {
                 job_id: jobId,
-                follow_up: `Await the reproduction agent: crtr job read result ${jobId} --wait. Then run \`crtr flow debug -h\` and follow the workflow from Phase 1.`,
+                follow_up: `Await the reproduction agent: crtr job read result ${jobId} --wait. Then run \`crtr mode debug -h\` and follow the workflow from Phase 1.`,
             };
         },
     });

package/dist/commands/human.js

@@ -13,7 +13,7 @@
 // run.json, never stdin.
 import { defineBranch, defineLeaf } from '../core/command.js';
 import { InputError } from '../core/io.js';
-import { createJob, writeResult, recordJobPane, appendEvent } from '../core/jobs.js';
+import { createJob, writeResult, recordJobPane, appendEvent, readResult as jobsReadResult } from '../core/jobs.js';
 import { spawnAndDetach, shellQuote, isInTmux, countPanesInCurrentWindow } from '../core/spawn.js';
 import { interactionsRoot, interactionDir } from '../core/artifact.js';
 import { paginate } from '../core/pagination.js';
@@ -45,9 +45,10 @@ function followUpDrain(jobId) {
 }
 /**
  * Spawn the detached `_run` pane for a job-backed kickoff, record the pane for
- * cancellation, log the start, and return the appropriate follow_up. Degrades
- * to the inbox-drain follow_up (job still created) when not in tmux / spawn
- * fails — kickoffs are intentionally non-fatal off-tmux.
+ * cancellation, log the start, and return whether the pane spawned plus the
+ * appropriate follow_up. Degrades to the inbox-drain follow_up (job still
+ * created) when not in tmux / spawn fails — kickoffs are intentionally
+ * non-fatal off-tmux.
  */
 function spawnHumanJob(jobId, idir, cwd) {
     const spawn = spawnAndDetach({
@@ -59,7 +60,7 @@ function spawnHumanJob(jobId, idir, cwd) {
         failGuard: true,
     });
     if (spawn.status !== 'spawned') {
-        return followUpDrain(jobId);
+        return { spawned: false, follow_up: followUpDrain(jobId) };
     }
     if (spawn.paneId !== undefined)
         recordJobPane(jobId, spawn.paneId);
@@ -69,7 +70,7 @@ function spawnHumanJob(jobId, idir, cwd) {
         event: 'worker_started',
         message: `human pane ${paneLabel} spawned`,
     });
-    return followUpResult(jobId);
+    return { spawned: true, follow_up: followUpResult(jobId) };
 }
 // ---------------------------------------------------------------------------
 // ask
@@ -78,7 +79,8 @@ const humanAsk = defineLeaf({
     name: 'ask',
     help: {
         name: 'human ask',
-        summary: 'put a humanloop decision deck in front of a person; returns a job handle immediately. Humans respond on human time (often >10 min) — never block on the result.',
+        summary: 'put a humanloop decision deck in front of a person; returns a job handle immediately. This is the default, expected channel for posing ANY question or decision to the user — reach for it instead of writing the question as prose in your reply.',
+        guide: 'Use this for quick, open-ended, and nuanced asks alike — not just "formal" multiple-choice. Set `allowFreetext: true` (with `freetextLabel`) when the answer is open-ended; offer a few `options` as starting points even for judgment calls. The kickoff is instant and NEVER blocks — "never block on the result" refers only to not busy-waiting on the job; the human answering on their own time is not a reason to avoid asking or to fall back to inline prose. The deck body is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one.',
         params: [
             { kind: 'context-file', name: 'deck', required: true, constraint: 'Contains a humanloop deck. Validated before any job is created.', shape: DECK_SCHEMA_HINT },
             { kind: 'flag', name: 'wait', type: 'bool', required: false, constraint: 'Accepted for symmetry with the job contract; the kickoff never blocks.' },
@@ -114,7 +116,7 @@ const humanAsk = defineLeaf({
         atomicWriteJson(deckPath(idir), deck);
         const rc = { mode: 'ask', job_id: jobId };
         atomicWriteJson(join(idir, 'run.json'), rc);
-        const follow_up = spawnHumanJob(jobId, idir, cwd);
+        const { follow_up } = spawnHumanJob(jobId, idir, cwd);
         return { job_id: jobId, dir: idir, follow_up };
     },
 });
@@ -125,7 +127,8 @@ const humanApprove = defineLeaf({
     name: 'approve',
     help: {
         name: 'human approve',
-        summary: 'a Yes/No approval gate; returns a job handle immediately. Humans respond on human time (often >10 min) — never block on the result.',
+        summary: 'a Yes/No approval gate; returns a job handle immediately. The standard way to gate a handoff on human sign-off. Kickoff never blocks — peek at the result later rather than busy-waiting; the human answering on their own time is not a reason to skip the gate.',
+        guide: 'The body is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one.',
         params: [
             { kind: 'positional', name: 'title', type: 'string', required: true, constraint: 'The question shown to the human.' },
             { kind: 'flag', name: 'subtitle', type: 'string', required: false, constraint: 'Optional one-line context.' },
@@ -157,7 +160,7 @@ const humanApprove = defineLeaf({
         atomicWriteJson(deckPath(idir), deck);
         const rc = { mode: 'approve', job_id: jobId, approve_iid: 'approve' };
         atomicWriteJson(join(idir, 'run.json'), rc);
-        const follow_up = spawnHumanJob(jobId, idir, cwd);
+        const { follow_up } = spawnHumanJob(jobId, idir, cwd);
         return { job_id: jobId, dir: idir, follow_up };
     },
 });
@@ -168,20 +171,25 @@ const humanReview = defineLeaf({
     name: 'review',
     help: {
         name: 'human review',
-        summary: 'open a .md in a read-only review editor for anchored comments; returns a job handle immediately. Humans respond on human time (often >10 min) — never block on the result.',
+        summary: 'open a .md in a read-only review editor for anchored comments; BLOCKS until the human submits the review. Humans respond on human time (often >10 min) — if you want to keep working, background this call (your harness will notify you when it finishes).',
+        guide: 'Unlike ask/approve, this call does not return a job handle and walk away — it blocks until the human finishes reviewing and submits (or closes the pane). Run it in the background when you have other work to do; the harness surfaces the result on completion. The returned `result` is the humanloop FeedbackResult (anchored comments). The .md you point at is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one.',
         params: [
             { kind: 'positional', name: 'file', type: 'path', required: true, constraint: 'Absolute path to an existing .md file.' },
             { kind: 'flag', name: 'output', type: 'path', required: false, constraint: 'Where the FeedbackResult JSON is written. Default: <dir>/feedback.json.' },
         ],
         output: [
-            { name: 'job_id', type: 'string', required: true, constraint: 'Poll with `crtr job read result`; result is the humanloop FeedbackResult.' },
+            { name: 'job_id', type: 'string', required: true, constraint: 'The kind:"human" job backing this review. Cancel with `crtr job cancel`.' },
             { name: 'output', type: 'string', required: true, constraint: 'Path the FeedbackResult JSON is autosaved to.' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'A non-blocking status peek. The human may take minutes to hours — never block waiting on this.' },
+            { name: 'status', type: 'string', required: true, constraint: 'Terminal state once the call unblocks: done (submitted), failed, canceled, or closed (pane went away before submit).' },
+            { name: 'result', type: 'object', required: false, constraint: 'The humanloop FeedbackResult (anchored comments). Present when status is done.' },
+            { name: 'reason', type: 'string', required: false, constraint: 'Short explanation when status is failed or closed.' },
+            { name: 'follow_up', type: 'string', required: false, constraint: 'Present only when off-tmux: a human must drain the review via `crtr human inbox`, then read the result.' },
         ],
         outputKind: 'object',
         effects: [
             'Creates a kind:"human" job and writes run.json to the interaction dir.',
             'Spawns a read-only nvim/vim review session in a detached tmux pane (when in tmux).',
+            'Blocks the calling process until the human submits, the pane closes, or the job is canceled.',
         ],
     },
     run: async (input) => {
@@ -211,8 +219,22 @@ const humanReview = defineLeaf({
         const output = outputArg !== undefined ? outputArg : join(idir, 'feedback.json');
         const rc = { mode: 'review', job_id: jobId, file: abs, output };
         atomicWriteJson(join(idir, 'run.json'), rc);
-        const follow_up = spawnHumanJob(jobId, idir, cwd);
-        return { job_id: jobId, output, follow_up };
+        const { spawned, follow_up } = spawnHumanJob(jobId, idir, cwd);
+        // Off-tmux: no pane to block on — fall back to the non-blocking handle the
+        // way ask/approve do, so the review can still be drained from the inbox.
+        if (!spawned) {
+            return { job_id: jobId, output, status: 'live', follow_up };
+        }
+        // In tmux: block until the human submits, the pane closes, or the job is
+        // canceled. Infinity = no timeout (the human owns the clock); the poll in
+        // readResult still reaps a dead pane, so this never hangs on a closed pane.
+        const r = await jobsReadResult(jobId, { waitMs: Infinity });
+        const out = { job_id: jobId, output, status: r.status };
+        if (r.result !== undefined)
+            out['result'] = r.result;
+        if (r.reason !== undefined)
+            out['reason'] = r.reason;
+        return out;
     },
 });
 // ---------------------------------------------------------------------------
@@ -223,6 +245,7 @@ const humanNotify = defineLeaf({
     help: {
         name: 'human notify',
         summary: 'show a fire-and-forget acknowledgement; creates no job',
+        guide: 'The body is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one.',
         params: [
             { kind: 'positional', name: 'title', type: 'string', required: true, constraint: 'The notification headline.' },
             { kind: 'flag', name: 'body', type: 'string', required: false, constraint: 'Optional markdown body.' },
@@ -270,9 +293,9 @@ const humanShow = defineLeaf({
     help: {
         name: 'human show',
         summary: 'put a file live on screen in a tmux pane via humanloop display',
+        guide: 'The pane always watches the file and live-updates on every save — a displayed doc is a live view by definition, so point it at a file something keeps rewriting (a status board, a running summary) and it stays current. The file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one.',
         params: [
             { kind: 'positional', name: 'path', type: 'path', required: true, constraint: 'Path to the file to render.' },
-            { kind: 'flag', name: 'watch', type: 'bool', required: false, constraint: 'When present, live-update the pane on edits. Default off.' },
             { kind: 'flag', name: 'window', type: 'enum', choices: ['auto', 'split', 'new'], required: false, default: 'auto', constraint: 'Placement. Default auto.' },
         ],
         output: [
@@ -284,14 +307,13 @@ const humanShow = defineLeaf({
     },
     run: async (input) => {
         const path = input['path'];
-        const watch = input['watch'] === true;
         const windowArg = input['window'];
         const window = windowArg !== undefined ? windowArg : 'auto';
         // `human show` must never fail the caller: any display error degrades to
         // {pane_id:null, reason} with exit 0 (matches humanloop display semantics).
         let paneId;
         try {
-            const r = display(path, { watch, window, maxPanes: resolveMaxPanes() });
+            const r = display(path, { window, maxPanes: resolveMaxPanes() });
             paneId = r.paneId;
         }
         catch {
@@ -415,8 +437,13 @@ const humanRun = defineLeaf({
                 // notify: no job — nothing to write
             }
             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,
                 });
                 writeResult(rc.job_id, res, 'done');
             }
@@ -434,10 +461,15 @@ const humanRun = defineLeaf({
 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',
+            desc: 'ask, approve, review, notify, show, 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',
+        },
         help: {
             name: 'human',
             summary: 'human-in-the-loop decisions, document review, and live display',
-            model: "Kickoff leaves create kind:'human' jobs. Humans respond on human time (often >10 min) — never block waiting on the result; peek with `crtr job read result|status` (no `wait`). Cancel with `crtr job cancel`. notify/show create no job.",
+            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 kind:'human' jobs and return instantly, never blocking — peek later with `crtr job read result|status` (no `wait`). 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. Cancel with `crtr job cancel`. notify/show create no job.",
             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' },

package/dist/commands/job.d.ts

@@ -1,2 +1,11 @@
 import type { BranchDef } from '../core/command.js';
+/** Count of jobs currently in the live state, or null when listing fails.
+ *  Backs the always-on "Workers running" signal on root -h so an agent never
+ *  forgets it has in-flight workers to collect. */
+export declare function liveJobCount(): number | null;
+/** The job subtree's root-level dynamic block. A bounded aggregate (running
+ *  count + how to collect), never an enumeration: live jobs are volatile and
+ *  unbounded, so listing them in root -h would balloon (cli-design rule 15).
+ *  Omitted when nothing is running. */
+export declare function buildJobRootBlock(): string | null;
 export declare function registerJob(): BranchDef;