@crouton-kit/crouter 0.3.2 → 0.3.8

package/dist/commands/human.js

@@ -21,7 +21,7 @@ import { readConfig } from '../core/config.js';
 import { mkdirSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
-import { ask, launchReview, display, inbox, scanInbox, validateDeck, parseDeck, deckPath, atomicWriteJson, readJson, } from '@crouton-kit/humanloop';
+import { ask, launchReview, display, inbox, scanInbox, validateDeck, approveDeck, notifyDeck, parseDeck, deckPath, atomicWriteJson, readJson, } from '@crouton-kit/humanloop';
 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,' +
@@ -146,20 +146,10 @@ const humanApprove = defineLeaf({
         const title = input['title'];
         const subtitle = input['subtitle'];
         const body = input['body'];
-        const interaction = {
-            id: 'approve',
-            title,
-            kind: 'validation',
-            options: [
-                { id: 'yes', label: 'Yes' },
-                { id: 'no', label: 'No' },
-            ],
-        };
-        if (subtitle !== undefined)
-            interaction['subtitle'] = subtitle;
-        if (body !== undefined)
-            interaction['body'] = body;
-        const deck = validateDeck({ interactions: [interaction] });
+        const deck = approveDeck(title, {
+            ...(subtitle !== undefined ? { subtitle } : {}),
+            ...(body !== undefined ? { body } : {}),
+        });
         const cwd = process.cwd();
         const { jobId } = createJob('human', { cwd });
         const idir = interactionDir(jobId, cwd);
@@ -250,15 +240,7 @@ const humanNotify = defineLeaf({
     run: async (input) => {
         const title = input['title'];
         const body = input['body'];
-        const interaction = {
-            id: 'notify',
-            title,
-            kind: 'notify',
-            options: [{ id: 'ack', label: 'OK' }],
-        };
-        if (body !== undefined)
-            interaction['body'] = body;
-        const deck = validateDeck({ interactions: [interaction] });
+        const deck = notifyDeck(title, body !== undefined ? { body } : {});
         const cwd = process.cwd();
         const id = `nfy-${randomBytes(4).toString('hex')}`;
         const idir = interactionDir(id, cwd);

package/dist/commands/job.js

@@ -1,7 +1,9 @@
-// `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').
@@ -13,356 +15,12 @@
 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, } from '../core/jobs.js';
+import { scheduleKillCurrentPane } from '../core/spawn.js';
 import { paginate } from '../core/pagination.js';
-import { existsSync } from 'node:fs';
 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.',
-        });
-    }
-}
-// ---------------------------------------------------------------------------
-// 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],
-});
 // ---------------------------------------------------------------------------
 // read sub-branch
 // ---------------------------------------------------------------------------
@@ -406,7 +64,7 @@ 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.' },
@@ -434,7 +92,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.' },
@@ -478,9 +136,7 @@ const readLogs = defineLeaf({
         const terminalStates = new Set(['done', 'failed', 'canceled']);
         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 +161,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: '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.' },
         ],
         outputKind: 'object',
         effects: ['None. Read-only.'],
@@ -524,6 +182,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 +206,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 +227,34 @@ 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);
         const paneKillScheduled = killPane ? scheduleKillCurrentPane(DEFAULT_KILL_SECS) : false;
         return { submitted: true, pane_kill_scheduled: paneKillScheduled };
     },
@@ -591,20 +268,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 +291,7 @@ 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');
             return { recorded: true };
         }
         catch {
@@ -632,7 +308,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.' },
@@ -654,16 +330,15 @@ export function registerJob() {
         name: 'job',
         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.',
             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/plan.d.ts

@@ -1,4 +1,4 @@
-export declare const PLAN_NEW_GUIDE = "## Planning workflow\n\nBuild and save an implementation plan: a map another agent can execute without\nre-discovering context. Work through these phases before saving.\n\n### Phase 1: Understand\n\nBuild a full picture of the request and the code. Search for reusable\nfunctions, patterns, and existing implementations before proposing new ones.\n\nLaunch up to 3 Explore subagents IN PARALLEL (single message, multiple tool\ncalls). Use 1 agent for isolated, small-scope tasks; use more when scope is\nuncertain or multiple subsystems are involved. Give each a distinct focus so\nthey don't duplicate work.\n\n### Phase 2: Design\n\nDesign the implementation from Phase 1 findings. Default to launching at least\n1 Plan agent to validate your understanding and surface alternatives. Skip only\nfor trivially small tasks (typo fixes, single-line renames). Use up to 3 agents\nfor large refactors or architectural changes.\n\nIn the Plan agent prompt: include file paths, code-path traces, requirements,\nand constraints from Phase 1. Request a detailed implementation plan.\n\n### Phase 3: Review findings\n\nRead the critical files identified by agents. Confirm the plan aligns with the\nuser's request. Use AskUserQuestion ONLY to clarify requirements or choose\nbetween approaches \u2014 never to ask \"is this okay?\" or \"should I proceed?\".\n\n### Phase 4: Compose the plan body\n\nQuality bar \u2014 every item below is cheap to satisfy and saves the implementer\nfrom re-deciding:\n\n- Every decision pinned. No \"if X then Y\" branches, no \"investigate whether\u2026\",\n  no deferred choices. If you don't know, find out or ask now.\n- No timelines, no fallbacks, no magic values, no \"for now\" shortcuts.\n- Where the plan creates a new interface, schema, or contract, write the actual\n  shape, not \"design a Foo type.\"\n\nRequired sections:\n\n  # Plan: <one-line title>\n\n  ## Context\n  <why this change is being made \u2014 the problem, what prompted it, intended outcome>\n\n  ## Recommended approach\n  <your chosen approach only. Concise enough to scan, detailed enough to execute.>\n\n  ## Files to modify / create\n  - `path/to/file.ts` \u2014 <what changes>\n\n  ## Existing utilities to reuse\n  - `functionName` from `path/to/file.ts:LL` \u2014 <why it fits>\n\n  ## Verification\n  <how to test end-to-end \u2014 run the code, run tests, etc.>\n\nFor plans touching 4+ files across distinct concerns, structure parallel tasks:\n\n  ## Tasks\n  - **Task 1**: <name>\n    - Files: `a.ts`, `b.ts` (disjoint from other tasks)\n    - Depends on: (none) | Task N\n    - Integration: <shared types/APIs with exact shape>\n    - Changes: <bullets>\n\nSkip the Tasks structure for small plans; it's noise when there's no\nparallelism to unlock.\n\n### Phase 5: Save\n\nRun `crtr flow plan new`:\n\n  echo '<plan markdown>' | crtr flow plan new <kebab-case-name> [--spec <spec-name>]\n\n- NAME: short kebab-case slug. Nested names become subdirectories\n  (e.g. `auth/jwt-refresh`).\n- Pipe the full plan markdown composed in Phase 4 on stdin.\n- `--spec` (optional): name of the spec this plan implements. Enables alignment\n  check by the reviewer.\n\nOutput: `{path, follow_up}`. The `follow_up` field names the exact next call\n\u2014 run it.\n\n### Phase 6: Oversize check\n\nIf `follow_up` contains an oversize advisory (plan exceeds 200 lines), split\ninto a short index plan plus nested part plans, each under the threshold.\nRe-save. The implementer executes parts one at a time; long monolithic plans\nare under-decomposed.\n\n### Phase 7: Done\n\nAfter the reviewer approves the plan, your turn ends. Do not summarize in chat.\nFor a human gate, optionally put the plan in front of a person with `crtr\nhuman review` (anchored comments) and gate the handoff with `crtr human\napprove`. This complements \u2014 it does not replace \u2014 `crtr job start reviewer`.\nIf the user is ready to build, ask once whether to hand off; if yes, run:\n`crtr job start implementer` with the plan path.";
+export declare const PLAN_NEW_GUIDE = "## Planning workflow\n\nBuild and save an implementation plan: a map another agent can execute without\nre-discovering context. Work through these phases before saving.\n\n### Phase 1: Understand\n\nBuild a full picture of the request and the code. Search for reusable\nfunctions, patterns, and existing implementations before proposing new ones.\n\nLaunch up to 3 Explore subagents IN PARALLEL (single message, multiple tool\ncalls). Use 1 agent for isolated, small-scope tasks; use more when scope is\nuncertain or multiple subsystems are involved. Give each a distinct focus so\nthey don't duplicate work.\n\n### Phase 2: Design\n\nDesign the implementation from Phase 1 findings. Default to launching at least\n1 Plan agent to validate your understanding and surface alternatives. Skip only\nfor trivially small tasks (typo fixes, single-line renames). Use up to 3 agents\nfor large refactors or architectural changes.\n\nIn the Plan agent prompt: include file paths, code-path traces, requirements,\nand constraints from Phase 1. Request a detailed implementation plan.\n\n### Phase 3: Review findings\n\nRead the critical files identified by agents. Confirm the plan aligns with the\nuser's request. Use AskUserQuestion ONLY to clarify requirements or choose\nbetween approaches \u2014 never to ask \"is this okay?\" or \"should I proceed?\".\n\n### Phase 4: Compose the plan body\n\nQuality bar \u2014 every item below is cheap to satisfy and saves the implementer\nfrom re-deciding:\n\n- Every decision pinned. No \"if X then Y\" branches, no \"investigate whether\u2026\",\n  no deferred choices. If you don't know, find out or ask now.\n- No timelines, no fallbacks, no magic values, no \"for now\" shortcuts.\n- Where the plan creates a new interface, schema, or contract, write the actual\n  shape, not \"design a Foo type.\"\n\nRequired sections:\n\n  # Plan: <one-line title>\n\n  ## Context\n  <why this change is being made \u2014 the problem, what prompted it, intended outcome>\n\n  ## Recommended approach\n  <your chosen approach only. Concise enough to scan, detailed enough to execute.>\n\n  ## Files to modify / create\n  - `path/to/file.ts` \u2014 <what changes>\n\n  ## Existing utilities to reuse\n  - `functionName` from `path/to/file.ts:LL` \u2014 <why it fits>\n\n  ## Verification\n  <how to test end-to-end \u2014 run the code, run tests, etc.>\n\nFor plans touching 4+ files across distinct concerns, structure parallel tasks:\n\n  ## Tasks\n  - **Task 1**: <name>\n    - Files: `a.ts`, `b.ts` (disjoint from other tasks)\n    - Depends on: (none) | Task N\n    - Integration: <shared types/APIs with exact shape>\n    - Changes: <bullets>\n\nSkip the Tasks structure for small plans; it's noise when there's no\nparallelism to unlock.\n\n### Phase 5: Save\n\nRun `crtr agent plan new`:\n\n  echo '<plan markdown>' | crtr agent plan new <kebab-case-name> [--spec <spec-name>]\n\n- NAME: short kebab-case slug. Nested names become subdirectories\n  (e.g. `auth/jwt-refresh`).\n- Pipe the full plan markdown composed in Phase 4 on stdin.\n- `--spec` (optional): name of the spec this plan implements. Enables alignment\n  check by the reviewer.\n\nOutput: `{path, follow_up}`. The `follow_up` field names the exact next call\n\u2014 run it.\n\n### Phase 6: Oversize check\n\nIf `follow_up` contains an oversize advisory (plan exceeds 200 lines), split\ninto a short index plan plus nested part plans, each under the threshold.\nRe-save. The implementer executes parts one at a time; long monolithic plans\nare under-decomposed.\n\n### Phase 7: Done\n\nAfter the reviewer approves the plan, your turn ends. Do not summarize in chat.\nFor a human gate, optionally put the plan in front of a person with `crtr\nhuman review` (anchored comments) and gate the handoff with `crtr human\napprove`. This complements \u2014 it does not replace \u2014 `crtr agent new reviewer`.\nIf the user is ready to build, ask once whether to hand off; if yes, run:\n`crtr agent new implementer` with the plan path.";
 export declare const PLAN_SHOW_GUIDE = "";
 import type { BranchDef } from '../core/command.js';
 export declare function registerPlan(): BranchDef;