@crouton-kit/crouter 0.3.8 → 0.3.11

package/dist/commands/debug.d.ts

@@ -1,3 +1,3 @@
-export declare const FLOW_DEBUG_GUIDE = "## Debug workflow \u2014 reproduce first\n\nAudience: the agent that ran `crtr agent debug`. A reproduction agent is\nalready spawned in a sibling pane. It writes ONE failing integration test and\nnever fixes anything. You do everything after: gate on the repro, root-cause,\nfix, verify against that same test.\n\n### Phase 0: Await the repro agent\n\nRun `crtr job read result <job_id> --wait` (10-min budget).\nOn status:\"timeout\": re-issue the wait, or run `crtr job read logs <job_id> --follow`\nuntil the job is terminal.\n\n### Phase 1: Gate on reproduction\n\n`reproduces:true`: read `test_path`, run `test_command` YOURSELF, confirm\nit fails for the stated reason. Do not trust the agent's claim \u2014 if it passes\nor fails differently, treat repro as NOT achieved. This test is the regression\ngate; it stays in the suite after the fix.\n`status:\"failed\"` / `reproduces:false` / your run disproves it: no repro\nharness. Continue, but record \"no reproduction \u2014 fix unverified; do not claim\nverified-fixed.\"\n\n### Phase 2: Reconnaissance\n\nRead the key files yourself \u2014 entry point, failure point, the data flow\nbetween. `git log` / `git blame` near the failure: recent changes are\nhigh-signal.\n\n### Phase 3: Assess difficulty, scale investigators\n\nSimple \u2192 solo (Explore subagents for tracing if the area is large).\nMedium \u2192 2\u20133 parallel `devcore:senior-advisor`: data-flow tracer, assumption\nauditor, change investigator.\nHard (intermittent, races, \"been stuck\", many modules) \u2192 3\u20135 parallel:\nend-to-end tracer, assumption breaker, git archaeologist, boundary inspector.\nGive investigators file paths, observed behavior, and concrete tasks \u2014 never\nyour hypotheses. Challenge theories against each other; the one that survives\ndisconfirmation wins.\n\n### Phase 4: Fix\n\nMinimal root-cause fix. No scope expansion, no drive-by refactor.\n\n### Phase 5: Verify\n\nRe-run `test_command`: it MUST now pass. Run the broader suite for\nregressions. If there was no repro test, state the fix is unverified by\nreproduction and recommend explicit manual verification.\n\n### Phase 6: Report\n\nRoot cause (exact line + why), evidence, the now-passing repro test path,\nconfidence (High/Medium/Low; if not High, name what is uncertain).\n\n### Constraints\n\nThe repro test is the regression guard \u2014 it stays; a fix-agent must never\nweaken it. Investigators run in forked contexts; they return summaries, not\nraw output. No code changes during Phases 2\u20133 except the repro test.";
+export declare const FLOW_DEBUG_GUIDE = "## Debug workflow \u2014 reproduce first\n\nAudience: the agent that ran `crtr mode debug`. A reproduction agent is\nalready spawned in a sibling pane. It writes ONE failing integration test and\nnever fixes anything. You do everything after: gate on the repro, root-cause,\nfix, verify against that same test.\n\n### Phase 0: Await the repro agent\n\nRun `crtr job read result <job_id> --wait` (10-min budget).\nOn status:\"timeout\": re-issue the wait, or run `crtr job read logs <job_id> --follow`\nuntil the job is terminal.\n\n### Phase 1: Gate on reproduction\n\n`reproduces:true`: read `test_path`, run `test_command` YOURSELF, confirm\nit fails for the stated reason. Do not trust the agent's claim \u2014 if it passes\nor fails differently, treat repro as NOT achieved. This test is the regression\ngate; it stays in the suite after the fix.\n`status:\"failed\"` / `reproduces:false` / your run disproves it: no repro\nharness. Continue, but record \"no reproduction \u2014 fix unverified; do not claim\nverified-fixed.\"\n\n### Phase 2: Reconnaissance\n\nRead the key files yourself \u2014 entry point, failure point, the data flow\nbetween. `git log` / `git blame` near the failure: recent changes are\nhigh-signal.\n\n### Phase 3: Assess difficulty, scale investigators\n\nSimple \u2192 solo (Explore subagents for tracing if the area is large).\nMedium \u2192 2\u20133 parallel `devcore:senior-advisor`: data-flow tracer, assumption\nauditor, change investigator.\nHard (intermittent, races, \"been stuck\", many modules) \u2192 3\u20135 parallel:\nend-to-end tracer, assumption breaker, git archaeologist, boundary inspector.\nGive investigators file paths, observed behavior, and concrete tasks \u2014 never\nyour hypotheses. Challenge theories against each other; the one that survives\ndisconfirmation wins.\n\n### Phase 4: Fix\n\nMinimal root-cause fix. No scope expansion, no drive-by refactor.\n\n### Phase 5: Verify\n\nRe-run `test_command`: it MUST now pass. Run the broader suite for\nregressions. If there was no repro test, state the fix is unverified by\nreproduction and recommend explicit manual verification.\n\n### Phase 6: Report\n\nRoot cause (exact line + why), evidence, the now-passing repro test path,\nconfidence (High/Medium/Low; if not High, name what is uncertain).\n\n### Constraints\n\nThe repro test is the regression guard \u2014 it stays; a fix-agent must never\nweaken it. Investigators run in forked contexts; they return summaries, not\nraw output. No code changes during Phases 2\u20133 except the repro test.";
 import type { LeafDef } from '../core/command.js';
 export declare function registerDebug(): LeafDef;

package/dist/commands/debug.js

@@ -1,14 +1,14 @@
-// `crtr agent 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 agent new 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 agent 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 agent 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 agent 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: 'agent 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 agent 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;

package/dist/commands/job.js

@@ -6,20 +6,44 @@
 // cancel.
 //
 // Terminal-write contract:
-//   Worker calls `crtr job submit` → jobs.writeResult(jobId, result, 'done').
-//   If claude exits without submitting, the wrapper shell calls `crtr job _fail`
-//   → jobs.writeResult(jobId, {}, 'failed') IF result.json does not yet exist.
-//   `job read result` watches result.json appearance as the sole completion signal.
+//   Worker MAY call `crtr job submit` → writes result.md (done|failed).
+//   If claude exits without submitting, the wrapper shell's `crtr job _fail`
+//   marks it failed IF no result file exists yet.
+//   If the worker's tmux pane is closed, SIGHUP skips `_fail`; the jobs layer
+//   then reaps the job by detecting that its recorded pane has vanished.
+//   `job read result` watches result file appearance and polls for pane death.
 //
 // `job read logs` is the only JSONL leaf.
 import { defineBranch, defineLeaf } from '../core/command.js';
 import { emitLine } from '../core/io.js';
 import { InputError } from '../core/io.js';
-import { writeMarkdownResult, readResult as jobsReadResult, jobStatus, listJobs, readLog, cancelJob, } from '../core/jobs.js';
+import { writeMarkdownResult, readResult as jobsReadResult, jobStatus, listJobs, readLog, cancelJob, appendEvent, } from '../core/jobs.js';
 import { scheduleKillCurrentPane } from '../core/spawn.js';
 import { paginate } from '../core/pagination.js';
+import { stateBlock } from '../core/help.js';
 const WAIT_BUDGET_MS = 10 * 60 * 1000;
 const FOLLOW_POLL_MS = 1000;
+/** 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 function liveJobCount() {
+    try {
+        return listJobs().filter((j) => j.state === 'live').length;
+    }
+    catch {
+        return 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 function buildJobRootBlock() {
+    const n = liveJobCount();
+    if (n === null || n === 0)
+        return null;
+    return stateBlock('workers', { count: n }, '`crtr job read list` to see them; `crtr job read result ID` to collect');
+}
 const DEFAULT_KILL_SECS = 2;
 // ---------------------------------------------------------------------------
 // read sub-branch
@@ -68,7 +92,7 @@ const readStatus = defineLeaf({
         ],
         output: [
             { name: 'job_id', type: 'string', required: true, constraint: 'Echo of input.' },
-            { name: 'state', type: 'string', required: true, constraint: 'One of: live, done, failed, canceled.' },
+            { name: 'state', type: 'string', required: true, constraint: 'One of: live, done, failed, canceled, closed (worker pane closed with no submitted result).' },
             { name: 'age_s', type: 'number', required: true, constraint: 'Seconds since job creation.' },
             { name: 'last_event', type: 'object | null', required: true, constraint: 'Most recent log event {event, ts}, or null if no events yet.' },
         ],
@@ -133,7 +157,7 @@ const readLogs = defineLeaf({
                 lastTs = e['ts'];
             }
         }
-        const terminalStates = new Set(['done', 'failed', 'canceled']);
+        const terminalStates = new Set(['done', 'failed', 'canceled', 'closed']);
         await new Promise((resolve) => {
             const poll = () => {
                 const status = jobStatus(jobId);
@@ -166,10 +190,10 @@ const readResult = defineLeaf({
         ],
         output: [
             { name: 'job_id', type: 'string', required: true, constraint: 'Echo of input.' },
-            { name: 'status', type: 'string', required: true, constraint: 'One of: done, failed, canceled, timeout.' },
+            { name: 'status', type: 'string', required: true, constraint: 'One of: done, failed, canceled, closed, timeout. closed = the worker pane went away before submitting a result.' },
             { name: 'result_md', type: 'string', required: false, constraint: 'Markdown body submitted by an agent via `crtr job submit`. Present when the job used the agent submit path.' },
             { name: 'result', type: 'object', required: false, constraint: 'Structured object submitted by a programmatic caller (human/sys). Present when the job used the programmatic submit path.' },
-            { name: 'reason', type: 'string', required: false, constraint: 'Failure reason from frontmatter when status is failed and the agent submit path was used.' },
+            { name: 'reason', type: 'string', required: false, constraint: 'Short explanation from frontmatter. Present when status is failed (agent-reported error) or closed (worker pane closed before submitting).' },
         ],
         outputKind: 'object',
         effects: ['None. Read-only.'],
@@ -255,6 +279,11 @@ const jobSubmit = defineLeaf({
             });
         }
         writeMarkdownResult(jobId, body, status, status === 'failed' ? reason : undefined);
+        appendEvent(jobId, {
+            level: status === 'failed' ? 'error' : 'info',
+            event: 'worker_finished',
+            message: status === 'failed' ? `worker failed: ${reason}` : 'worker submitted result',
+        });
         const paneKillScheduled = killPane ? scheduleKillCurrentPane(DEFAULT_KILL_SECS) : false;
         return { submitted: true, pane_kill_scheduled: paneKillScheduled };
     },
@@ -292,6 +321,11 @@ const jobFail = defineLeaf({
         }
         try {
             writeMarkdownResult(jobId, '', 'failed', 'worker exited without submitting');
+            appendEvent(jobId, {
+                level: 'error',
+                event: 'worker_finished',
+                message: 'worker exited without submitting',
+            });
             return { recorded: true };
         }
         catch {
@@ -328,10 +362,16 @@ const jobCancel = defineLeaf({
 export function registerJob() {
     return defineBranch({
         name: 'job',
+        rootEntry: {
+            concept: 'producer-agnostic record of any ongoing task — its logs and result',
+            desc: 'monitor and collect from any ongoing task',
+            useWhen: 'reading status, logs, or result of a job started by any producer',
+            dynamicState: buildJobRootBlock,
+        },
         help: {
             name: 'job',
             summary: 'monitor and collect results from any ongoing task',
-            model: 'A job is a producer-agnostic record of an ongoing task: state, logs, terminal result. Producers (`crtr agent new *`, future task systems) create jobs; this subtree is the shared read/cancel/submit surface. States: live | done | failed | canceled.',
+            model: 'A job is a producer-agnostic record of an ongoing task: state, logs, terminal result. Producers (`crtr agent new *`, future task systems) create jobs; this subtree is the shared read/cancel/submit surface. States: live | done | failed | canceled | closed (worker pane closed before submitting a result).',
             children: [
                 { name: 'read', desc: 'read status, logs, or results', useWhen: 'monitoring or collecting from a running or completed job' },
                 { name: 'submit', desc: 'deliver result from inside a worker pane or any producer', useWhen: 'a worker is ready to return its output' },

package/dist/commands/mode.d.ts

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