@crouton-kit/crouter 0.3.3 → 0.3.11

package/dist/commands/job.js

@@ -1,368 +1,50 @@
-// `crtr job` subtree — spawn/worker model backed by jobs.ts persistence.
+// `crtr job` subtree — universal monitoring registry for any ongoing task.
 //
-// Sub-branches: start {prompt,fork,planner,implementer,reviewer},
-//               read {list,status,logs,result}, submit, _fail, cancel.
+// Producers (agent spawns, future task systems) register jobs and write
+// results; this subtree is the read/cancel/submit surface shared across all
+// producers. Sub-branches: read {list, status, logs, result}, submit, _fail,
+// 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 { createJob, writeResult, readResult as jobsReadResult, jobStatus, listJobs, readLog, cancelJob, appendEvent, } from '../core/jobs.js';
-import { spawnAgent, spawnAndDetach, scheduleKillCurrentPane, isInTmux } from '../core/spawn.js';
-import { readConfig } from '../core/config.js';
-import { planHandoffPrompt, implementHandoffPrompt, reviewerHandoffPrompt } from '../prompts/agent.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 { existsSync } from 'node:fs';
+import { stateBlock } from '../core/help.js';
 const WAIT_BUDGET_MS = 10 * 60 * 1000;
 const FOLLOW_POLL_MS = 1000;
-const DEFAULT_KILL_SECS = 2;
-function followUpResult(jobId) {
-    return `crtr job read result ${jobId} --wait`;
-}
-function resolveMaxPanes() {
-    const cfg = readConfig('user');
-    return cfg.max_panes_per_window;
-}
-function assertTmux() {
-    if (!isInTmux()) {
-        throw new InputError({
-            error: 'not_in_tmux',
-            message: 'crtr job start requires tmux (TMUX env var not set).',
-            next: 'Run inside a tmux session.',
-        });
+/** 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;
     }
 }
-// ---------------------------------------------------------------------------
-// start sub-branch
-// ---------------------------------------------------------------------------
-const startPrompt = defineLeaf({
-    name: 'prompt',
-    help: {
-        name: 'job start prompt',
-        summary: 'spawn a fresh Claude agent with a prompt; returns a job handle immediately',
-        params: [
-            { kind: 'stdin', name: 'prompt', required: true, constraint: 'Prompt text sent to the spawned agent.' },
-            { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Working directory for the spawned agent. Defaults to process.cwd().' },
-        ],
-        output: [
-            { name: 'job_id', type: 'string', required: true, constraint: 'Use with `job read status`, `job read logs`, `job read result`, `job cancel`.' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'Recommended next call.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Spawns a Claude agent in a sibling tmux pane.',
-            'Creates a job entry at $XDG_STATE_HOME/crtr/jobs/<job_id>/.',
-            'On completion, result writes atomically to result.json.',
-        ],
-    },
-    run: async (input) => {
-        assertTmux();
-        const prompt = input['prompt'];
-        const cwd = typeof input['cwd'] === 'string' ? input['cwd'] : process.cwd();
-        const { jobId } = createJob('prompt', { cwd });
-        const promptWithSubmit = `${prompt}
-
----
-When your task is complete, submit your result:
-\`\`\`bash
-crtr job submit ${jobId} --context-file /tmp/result.json
-\`\`\`
-If you cannot complete the task, still submit with status "failed" and a reason.`;
-        const result = spawnAgent({
-            prompt: promptWithSubmit,
-            cwd,
-            jobId,
-            maxPanesPerWindow: resolveMaxPanes(),
-        });
-        if (result.status === 'not-in-tmux') {
-            throw new InputError({
-                error: 'not_in_tmux',
-                message: result.message,
-                next: 'Run inside a tmux session.',
-            });
-        }
-        if (result.status === 'spawn-failed') {
-            throw new InputError({
-                error: 'spawn_failed',
-                message: result.message,
-                next: 'Check tmux is running and try again.',
-            });
-        }
-        const paneLabel = result.paneId !== undefined ? result.paneId : 'unknown';
-        appendEvent(jobId, { level: 'info', event: 'worker_started', message: `pane ${paneLabel} spawned` });
-        return { job_id: jobId, follow_up: followUpResult(jobId) };
-    },
-});
-const startFork = defineLeaf({
-    name: 'fork',
-    help: {
-        name: 'job start fork',
-        summary: 'fork the current Claude session into a sibling pane; returns a job handle immediately',
-        params: [
-            { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Working directory. Defaults to process.cwd().' },
-        ],
-        output: [
-            { name: 'job_id', type: 'string', required: true, constraint: 'Use with `job read *` and `job cancel`.' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'Recommended next call.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Requires $CLAUDE_CODE_SESSION_ID — must run inside Claude Code.',
-            'Spawns a forked Claude session in a sibling tmux pane.',
-            'Creates a job entry and result sidecar as with `job start prompt`.',
-        ],
-    },
-    run: async (input) => {
-        assertTmux();
-        const parentSessionId = process.env['CLAUDE_CODE_SESSION_ID'];
-        if (parentSessionId === undefined || parentSessionId === '') {
-            throw new InputError({
-                error: 'missing_session_id',
-                message: 'crtr job start fork requires $CLAUDE_CODE_SESSION_ID — must run inside Claude Code.',
-                next: 'Run this command from within a Claude Code session.',
-            });
-        }
-        const cwd = typeof input['cwd'] === 'string' ? input['cwd'] : process.cwd();
-        const { jobId } = createJob('fork', { cwd });
-        const promptWithSubmit = `Fork of session ${parentSessionId}
-
----
-When your task is complete, submit your result:
-\`\`\`bash
-crtr job submit ${jobId} --context-file /tmp/result.json
-\`\`\`
-If you cannot complete the task, still submit with status "failed" and a reason.`;
-        const result = spawnAgent({
-            prompt: promptWithSubmit,
-            cwd,
-            jobId,
-            fork: { sessionId: parentSessionId },
-            maxPanesPerWindow: resolveMaxPanes(),
-        });
-        if (result.status === 'not-in-tmux') {
-            throw new InputError({
-                error: 'not_in_tmux',
-                message: result.message,
-                next: 'Run inside a tmux session.',
-            });
-        }
-        if (result.status === 'spawn-failed') {
-            throw new InputError({
-                error: 'spawn_failed',
-                message: result.message,
-                next: 'Check tmux is running and try again.',
-            });
-        }
-        const forkPaneLabel = result.paneId !== undefined ? result.paneId : 'unknown';
-        appendEvent(jobId, { level: 'info', event: 'worker_started', message: `forked pane ${forkPaneLabel} spawned` });
-        return { job_id: jobId, follow_up: followUpResult(jobId) };
-    },
-});
-const startPlanner = defineLeaf({
-    name: 'planner',
-    help: {
-        name: 'job start planner',
-        summary: 'launch a planning agent for an approved spec; closes the originating pane after handoff',
-        params: [
-            { kind: 'positional', name: 'spec_path', type: 'path', required: true, constraint: 'Absolute path to the spec file.' },
-            { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Working directory. Defaults to process.cwd().' },
-        ],
-        output: [
-            { name: 'job_id', type: 'string', required: true, constraint: 'Use with `job read *` and `job cancel`.' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'Recommended next call.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Spawns a planner agent in a sibling tmux pane.',
-            'Closes the originating pane after a short delay.',
-            'Creates a job entry and result sidecar.',
-        ],
-    },
-    run: async (input) => {
-        assertTmux();
-        const specPath = input['spec_path'];
-        const cwd = typeof input['cwd'] === 'string' ? input['cwd'] : process.cwd();
-        if (!existsSync(specPath)) {
-            throw new InputError({
-                error: 'not_found',
-                message: `spec not found: ${specPath}`,
-                field: 'spec_path',
-                next: 'Provide an absolute path to an existing spec file.',
-            });
-        }
-        const { jobId } = createJob('planner', { cwd });
-        const result = spawnAndDetach({
-            prompt: planHandoffPrompt(specPath, jobId),
-            cwd,
-            jobId,
-            placement: 'split-h',
-            killAfterSeconds: DEFAULT_KILL_SECS,
-        });
-        if (result.status === 'not-in-tmux') {
-            throw new InputError({
-                error: 'not_in_tmux',
-                message: result.message,
-                next: 'Run inside a tmux session.',
-            });
-        }
-        if (result.status === 'spawn-failed') {
-            throw new InputError({
-                error: 'spawn_failed',
-                message: result.message,
-                next: 'Check tmux is running and try again.',
-            });
-        }
-        const plannerPaneLabel = result.paneId !== undefined ? result.paneId : 'unknown';
-        appendEvent(jobId, { level: 'info', event: 'worker_started', message: `planner pane ${plannerPaneLabel} spawned` });
-        return { job_id: jobId, follow_up: followUpResult(jobId) };
-    },
-});
-const startImplementer = defineLeaf({
-    name: 'implementer',
-    help: {
-        name: 'job start implementer',
-        summary: 'launch an implementation agent for an approved plan; closes the originating pane after handoff',
-        params: [
-            { kind: 'positional', name: 'plan_path', type: 'path', required: true, constraint: 'Absolute path to the plan file.' },
-            { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Working directory. Defaults to process.cwd().' },
-        ],
-        output: [
-            { name: 'job_id', type: 'string', required: true, constraint: 'Use with `job read *` and `job cancel`.' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'Recommended next call.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Spawns an implementer agent in a sibling tmux pane.',
-            'Closes the originating pane after a short delay.',
-            'Creates a job entry and result sidecar.',
-        ],
-    },
-    run: async (input) => {
-        assertTmux();
-        const planPath = input['plan_path'];
-        const cwd = typeof input['cwd'] === 'string' ? input['cwd'] : process.cwd();
-        if (!existsSync(planPath)) {
-            throw new InputError({
-                error: 'not_found',
-                message: `plan not found: ${planPath}`,
-                field: 'plan_path',
-                next: 'Provide an absolute path to an existing plan file.',
-            });
-        }
-        const { jobId } = createJob('implementer', { cwd });
-        const result = spawnAndDetach({
-            prompt: implementHandoffPrompt(planPath, jobId),
-            cwd,
-            jobId,
-            placement: 'split-h',
-            killAfterSeconds: DEFAULT_KILL_SECS,
-        });
-        if (result.status === 'not-in-tmux') {
-            throw new InputError({
-                error: 'not_in_tmux',
-                message: result.message,
-                next: 'Check tmux is running and try again.',
-            });
-        }
-        if (result.status === 'spawn-failed') {
-            throw new InputError({
-                error: 'spawn_failed',
-                message: result.message,
-                next: 'Check tmux is running and try again.',
-            });
-        }
-        const implPaneLabel = result.paneId !== undefined ? result.paneId : 'unknown';
-        appendEvent(jobId, { level: 'info', event: 'worker_started', message: `implementer pane ${implPaneLabel} spawned` });
-        return { job_id: jobId, follow_up: followUpResult(jobId) };
-    },
-});
-const startReviewer = defineLeaf({
-    name: 'reviewer',
-    help: {
-        name: 'job start reviewer',
-        summary: 'launch a reviewer agent for a plan or spec artifact; the originating pane stays alive to collect the verdict',
-        params: [
-            { kind: 'positional', name: 'artifact_path', type: 'path', required: true, constraint: 'Absolute path to the artifact to review.' },
-            { kind: 'flag', name: 'kind', type: 'enum', choices: ['plan', 'spec'], required: true, constraint: 'Artifact kind to review.' },
-            { kind: 'flag', name: 'spec-path', type: 'path', required: false, constraint: 'Absolute path to the spec, for plan reviews. Omit for spec reviews.' },
-            { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Working directory. Defaults to process.cwd().' },
-        ],
-        output: [
-            { name: 'job_id', type: 'string', required: true, constraint: 'Use with `job read *` and `job cancel`.' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'Recommended next call.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Spawns a reviewer agent in a sibling tmux pane.',
-            'The originating pane stays alive — wait on the result and act on the verdict.',
-            'Creates a job entry and result sidecar.',
-        ],
-    },
-    run: async (input) => {
-        assertTmux();
-        const artifactPath = input['artifact_path'];
-        const artifactKind = input['kind'];
-        const specPath = typeof input['specPath'] === 'string' ? input['specPath'] : undefined;
-        const cwd = typeof input['cwd'] === 'string' ? input['cwd'] : process.cwd();
-        if (!existsSync(artifactPath)) {
-            throw new InputError({
-                error: 'not_found',
-                message: `artifact not found: ${artifactPath}`,
-                field: 'artifact_path',
-                next: 'Provide an absolute path to an existing artifact file.',
-            });
-        }
-        const { jobId } = createJob('reviewer', { cwd });
-        // The reviewer is a subordinate the caller waits on (verdict → revise or
-        // hand off), NOT a handoff successor. Use spawnAgent so the originating
-        // pane (planner/orchestrator) stays alive to collect the result; do not
-        // self-kill the caller the way planner/implementer handoffs do.
-        const result = spawnAgent({
-            prompt: reviewerHandoffPrompt(artifactPath, artifactKind, specPath !== undefined ? specPath : null, jobId),
-            cwd,
-            jobId,
-            maxPanesPerWindow: resolveMaxPanes(),
-        });
-        if (result.status === 'not-in-tmux') {
-            throw new InputError({
-                error: 'not_in_tmux',
-                message: result.message,
-                next: 'Run inside a tmux session.',
-            });
-        }
-        if (result.status === 'spawn-failed') {
-            throw new InputError({
-                error: 'spawn_failed',
-                message: result.message,
-                next: 'Check tmux is running and try again.',
-            });
-        }
-        const reviewerPaneLabel = result.paneId !== undefined ? result.paneId : 'unknown';
-        appendEvent(jobId, { level: 'info', event: 'worker_started', message: `reviewer pane ${reviewerPaneLabel} spawned` });
-        return { job_id: jobId, follow_up: followUpResult(jobId) };
-    },
-});
-const startBranch = defineBranch({
-    name: 'start',
-    help: {
-        name: 'job start',
-        summary: 'spawn agent workers; all return a job handle immediately',
-        children: [
-            { name: 'prompt', desc: 'fresh agent with a prompt', useWhen: 'spawning a general-purpose agent' },
-            { name: 'fork', desc: 'fork current session into a sibling pane', useWhen: 'branching the current session\'s context into a new agent' },
-            { name: 'planner', desc: 'planning agent for a spec', useWhen: 'handing off spec → plan decomposition' },
-            { name: 'implementer', desc: 'implementation agent for a plan', useWhen: 'handing off plan → code implementation' },
-            { name: 'reviewer', desc: 'review agent for a plan or spec', useWhen: 'launching a review of a plan or spec artifact' },
-        ],
-    },
-    children: [startPrompt, startFork, startPlanner, startImplementer, startReviewer],
-});
+/** 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
 // ---------------------------------------------------------------------------
@@ -406,11 +88,11 @@ const readStatus = defineLeaf({
         name: 'job read status',
         summary: 'read the current status of a job',
         params: [
-            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id from a `job start *` call.' },
+            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id from a producer (e.g. `crtr agent new *`).' },
         ],
         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.' },
         ],
@@ -434,7 +116,7 @@ const readLogs = defineLeaf({
         name: 'job read logs',
         summary: 'read log events from a job; emits JSONL — one event object per line',
         params: [
-            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id from a `job start *` call.' },
+            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id from a producer (e.g. `crtr agent new *`).' },
             { kind: 'flag', name: 'since', type: 'string', required: false, constraint: 'ISO 8601 timestamp. Only emit events at or after this time.' },
             { kind: 'flag', name: 'until', type: 'string', required: false, constraint: 'ISO 8601 timestamp. Only emit events before this time.' },
             { kind: 'flag', name: 'level', type: 'enum', choices: ['debug', 'info', 'warn', 'error'], required: false, default: 'info', constraint: 'Minimum severity. Default: info.' },
@@ -475,12 +157,10 @@ 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 = () => {
-                // Check terminal state first.
                 const status = jobStatus(jobId);
-                // Emit any new events since lastTs.
                 const newEvents = readLog(jobId, { sinceTs: lastTs !== new Date(0).toISOString() ? lastTs : undefined, minLevel });
                 for (const ev of newEvents) {
                     const e = ev;
@@ -505,13 +185,15 @@ const readResult = defineLeaf({
         name: 'job read result',
         summary: 'read the final result of a completed job',
         params: [
-            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id from a `job start *` call.' },
-            { kind: 'flag', name: 'wait', type: 'bool', required: false, constraint: 'When present, blocks until result.json appears (up to 10 min).' },
+            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id from a producer (e.g. `crtr agent new *`).' },
+            { kind: 'flag', name: 'wait', type: 'bool', required: false, constraint: 'When present, blocks until a result file appears (up to 10 min).' },
         ],
         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: 'result', type: 'object', required: false, constraint: 'The result object submitted by the worker. Present when status is done or failed.' },
+            { 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: '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.'],
@@ -524,6 +206,12 @@ const readResult = defineLeaf({
         if (r.result !== undefined) {
             out['result'] = r.result;
         }
+        if (r.result_md !== undefined) {
+            out['result_md'] = r.result_md;
+        }
+        if (r.reason !== undefined) {
+            out['reason'] = r.reason;
+        }
         return out;
     },
 });
@@ -542,16 +230,19 @@ const readBranch = defineBranch({
     children: [readList, readStatus, readLogs, readResult],
 });
 // ---------------------------------------------------------------------------
-// submit — called by the worker inside its pane
+// submit — called by the worker inside its pane (or by any producer that
+// writes a result programmatically)
 // ---------------------------------------------------------------------------
 const jobSubmit = defineLeaf({
     name: 'submit',
     help: {
         name: 'job submit',
-        summary: 'inside a crtr-spawned pane, deliver the result back to the job record',
+        summary: 'deliver a markdown result back to a job record (called by workers, or any producer writing the terminal value)',
         params: [
             { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id injected as $CRTR_JOB_ID in the spawned pane.' },
-            { kind: 'context-file', name: 'result', required: true, constraint: `Result payload JSON file. Must be a JSON object. Becomes the result.json content.` },
+            { kind: 'stdin', name: 'body', required: false, constraint: 'Markdown body of the result, piped on stdin. Required when --status is done (the default). When --status failed, stdin is optional; --reason carries the explanation.' },
+            { kind: 'flag', name: 'status', type: 'enum', choices: ['done', 'failed'], required: false, default: 'done', constraint: 'Terminal status to record. Default: done.' },
+            { kind: 'flag', name: 'reason', type: 'string', required: false, constraint: 'Short failure reason. Required when --status failed; ignored otherwise.' },
             { kind: 'flag', name: 'kill-pane', type: 'bool', required: false, constraint: `When present, schedule the current tmux pane to close ${DEFAULT_KILL_SECS}s after submission so the spawned worker does not linger. Reviewer agents should pass this; planner/implementer handoffs already self-kill on spawn.` },
         ],
         output: [
@@ -560,24 +251,39 @@ const jobSubmit = defineLeaf({
         ],
         outputKind: 'object',
         effects: [
-            'Writes result.json atomically for the job, marking it done.',
-            'Updates meta.json status to done.',
+            'Writes <jobdir>/result.md atomically (YAML frontmatter + body), marking the job done or failed.',
+            'Updates meta.json status to match.',
             `When --kill-pane is set, schedules \`tmux kill-pane\` on $TMUX_PANE after ${DEFAULT_KILL_SECS}s (detached; submit still returns cleanly).`,
         ],
     },
     run: async (input) => {
         const jobId = input['job_id'];
-        const result = input['result'];
-        if (result === undefined || result === null || typeof result !== 'object' || Array.isArray(result)) {
+        const status = (typeof input['status'] === 'string' ? input['status'] : 'done');
+        const body = typeof input['body'] === 'string' ? input['body'] : '';
+        const reason = typeof input['reason'] === 'string' ? input['reason'] : '';
+        const killPane = input['killPane'] === true;
+        if (status === 'done' && body.trim() === '') {
             throw new InputError({
                 error: 'invalid_field',
-                message: 'result file must contain a JSON object.',
-                field: 'result',
-                next: 'Pass a path to a file containing a JSON object via --context-file.',
+                message: '--status done requires a markdown body on stdin.',
+                field: 'body',
+                next: `Pipe the markdown result on stdin, e.g. \`crtr job submit ${jobId} <<'MD' ... MD\`. For failures, use \`--status failed --reason "<why>"\`.`,
             });
         }
-        const killPane = input['killPane'] === true;
-        writeResult(jobId, result, 'done');
+        if (status === 'failed' && reason.trim() === '') {
+            throw new InputError({
+                error: 'invalid_field',
+                message: '--status failed requires --reason "<text>".',
+                field: 'reason',
+                next: 'Pass --reason explaining why the task could not complete.',
+            });
+        }
+        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 };
     },
@@ -591,20 +297,19 @@ const jobFail = defineLeaf({
         name: 'job _fail',
         summary: 'internal: mark a job failed if it has not already been submitted (called by wrapper shell)',
         params: [
-            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id. If result.json already exists, this is a no-op.' },
+            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id. If a result file already exists, this is a no-op.' },
         ],
         output: [
-            { name: 'recorded', type: 'boolean', required: true, constraint: 'True if failure was recorded; false if result.json already existed (no-op).' },
+            { name: 'recorded', type: 'boolean', required: true, constraint: 'True if failure was recorded; false if a result file already existed (no-op).' },
         ],
         outputKind: 'object',
         effects: [
-            'Writes result.json with status "failed" if not already present.',
+            'Writes result.md with status "failed" and a reason if no result file is present.',
             'Updates meta.json status to failed.',
         ],
     },
     run: async (input) => {
         const jobId = input['job_id'];
-        // No-op if result.json already exists (worker submitted successfully).
         try {
             const existing = await jobsReadResult(jobId, { waitMs: 0 });
             if (existing.status !== 'timeout') {
@@ -615,7 +320,12 @@ const jobFail = defineLeaf({
             // job dir not found — still try to write to surface the failure
         }
         try {
-            writeResult(jobId, { reason: 'worker exited without submitting' }, 'failed');
+            writeMarkdownResult(jobId, '', 'failed', 'worker exited without submitting');
+            appendEvent(jobId, {
+                level: 'error',
+                event: 'worker_finished',
+                message: 'worker exited without submitting',
+            });
             return { recorded: true };
         }
         catch {
@@ -632,7 +342,7 @@ const jobCancel = defineLeaf({
         name: 'job cancel',
         summary: 'send a best-effort cancellation signal to a running job',
         params: [
-            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id from a `job start *` call.' },
+            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id from a producer (e.g. `crtr agent new *`).' },
         ],
         output: [
             { name: 'canceled', type: 'boolean', required: true, constraint: 'True if a signal was delivered or the job was already terminal; false if the job was not live.' },
@@ -652,18 +362,23 @@ 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: 'spawn, monitor, and collect results from running agent workers',
-            model: 'Jobs are running or completed agent workers. Status: live | done | failed | canceled.',
+            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 | closed (worker pane closed before submitting a result).',
             children: [
-                { name: 'start', desc: 'spawn agent workers', useWhen: 'launching a new agent job' },
                 { 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 spawned pane', useWhen: 'worker is ready to return its output' },
+                { name: 'submit', desc: 'deliver result from inside a worker pane or any producer', useWhen: 'a worker is ready to return its output' },
                 { name: '_fail', desc: 'internal: mark job failed on unsubmitted exit', useWhen: 'called by the wrapper shell, not manually' },
                 { name: 'cancel', desc: 'best-effort cancel a live job', useWhen: 'stopping a job that is no longer needed' },
             ],
         },
-        children: [startBranch, readBranch, jobSubmit, jobFail, jobCancel],
+        children: [readBranch, jobSubmit, jobFail, jobCancel],
     });
 }

package/dist/commands/{flow.d.ts → mode.d.ts}

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