@welluable/orch 1.2.0 → 1.3.0

package/README.md

@@ -51,7 +51,10 @@ npm install -g @welluable/orch
 
 Make sure an agent CLI is on your `PATH` — orch defaults to `--agent cursor`
 (the Cursor Agent CLI, command `agent`); `claude` and `agn` are also
-supported. See [Requirements](#requirements) for details.
+supported. Pin a default with `orch config --agent <name>` so you don't need
+`--agent` on every run (local `.orch/config` overrides global
+`~/.orch/config`; CLI `--agent` still wins). See [Requirements](#requirements)
+for details.
 
 ```bash
 orch "fix the typo in the README"
@@ -210,9 +213,18 @@ Usage: orch [options] [command] <task...>
   at once; omit to let the coordinator choose (typically the current layer's
   size); only meaningful with `--fan-out`.
 - `--agent <cursor|claude|agn>` — selects the backend for the whole pipeline;
-  defaults to `cursor`.
+  when omitted, uses local `.orch/config`, then global `~/.orch/config`, else
+  `cursor`.
 - `-h, --help` — displays help for the command.
 
+Config:
+
+- `orch config` — prints the effective agent and which file(s) contributed
+  (local / global / default). Does not prompt.
+- `orch config --agent <cursor|claude|agn> [--global|--local]` — writes the
+  default agent. Bare `--agent` (and `--global`) write `~/.orch/config`;
+  `--local` writes `<cwd>/.orch/config`. There is no `orch init`.
+
 Job-control subcommands (see [Headless runs](#headless-runs)):
 
 - `orch list` — lists all runs tracked under `.orch/` in the current directory.
@@ -220,7 +232,11 @@ Job-control subcommands (see [Headless runs](#headless-runs)):
   recently started run.
 - `orch pause <slug>` — requests a pause at the run's next stage-boundary
   checkpoint.
-- `orch resume <slug>` — resumes a paused (or pausing) run.
+- `orch resume <slug>` — unpauses a paused (or pausing) run.
+- `orch continue <slug> "new task"` — starts a new complex pipeline on a
+  finished run's existing worktree/branch (same slug). Carries prior
+  stage/failure outcome into research/plan. For fan-out workers, continue the
+  worker slug, then `orch --integrate <parent>`. Not the same as `resume`.
 - `orch stop <slug>` — sends `SIGTERM` to a running job (or reconciles a dead
   one to `crashed`).
 - `orch logs <slug> [-f]` — prints a run's `orch.log`; `-f` follows it until
@@ -237,6 +253,9 @@ orch "implement the local spec" --agent agn -v
 orch --ask "where is the CLI entrypoint?" --agent claude
 orch --quick "fix the typo in the README" --agent claude
 orch "noop" --dry-run --agent cursor
+orch config
+orch config --agent claude
+orch config --agent agn --local
 ```
 
 ## Headless runs
@@ -260,7 +279,8 @@ directory's `.orch/`:
 orch list                     # SLUG  ROLE  STATE  PHASE  AGENT  STARTED  DURATION  PID
 orch status swift-lagoon-49ea # full record: state, phase, branch, worktree, exit code, ...
 orch pause swift-lagoon-49ea  # request a pause at the next stage-boundary checkpoint
-orch resume swift-lagoon-49ea # resume a paused/pausing run
+orch resume swift-lagoon-49ea # unpause a paused/pausing run
+orch continue swift-lagoon-49ea "follow-up polish"  # new work on the same worktree
 orch logs swift-lagoon-49ea -f # follow orch.log until the run finishes
 orch stop swift-lagoon-49ea   # SIGTERM the run
 orch jobs clean                # delete every tracked run under .orch/ (asks to confirm)
@@ -432,7 +452,7 @@ pkill -f 'agn '        # --agent agn
 
 | Backend | `--agent` value | Status | Notes |
 | --- | --- | --- | --- |
-| Cursor Agent CLI | `cursor` | Supported (default) | Command `agent` on `PATH`. |
+| Cursor Agent CLI | `cursor` | Supported (builtin default) | Command `agent` on `PATH`. Override via `orch config` or `--agent`. |
 | Claude Code CLI | `claude` | Supported | Command `claude` on `PATH`. |
 | agn | `agn` | Supported | Requires `npm install -g @welluable/agn-cli` (`>= 0.0.12`) and `agn init`. |
 

package/lib/agent.js

@@ -2,7 +2,7 @@ import { spawn } from 'child_process';
 import path from 'path';
 import ora from 'ora';
 import { formatActiveTools } from './tool-status.js';
-import { patchJob } from './jobs.js';
+import { patchJob, buildLastOutcome } from './jobs.js';
 
 /**
  * Every child process spawned by an agent, tracked so we can reap them all
@@ -67,11 +67,24 @@ export function shutdown(signal, { exit = (code) => process.exit(code), jobCwd =
     const jobSlug = process.env.ORCH_JOB_SLUG ?? activeJobSlug;
     if (jobSlug) {
         try {
-            patchJob(jobCwd, jobSlug, {
+            const exitCode = exitCodeForSignal(signal);
+            const finishedAt = new Date().toISOString();
+            patchJob(jobCwd, jobSlug, (current) => ({
                 state: 'stopped',
-                exitCode: exitCodeForSignal(signal),
-                finishedAt: new Date().toISOString(),
-            });
+                exitCode,
+                finishedAt,
+                lastOutcome: buildLastOutcome({
+                    state: 'stopped',
+                    phase: current.phase,
+                    stage: current.stage,
+                    round: current.round,
+                    exitCode,
+                    finishedAt,
+                    task: current.task,
+                    summary: '',
+                    error: null,
+                }),
+            }));
         } catch {
             // Best-effort: don't let a job-state write failure block shutdown.
         }

package/lib/config.js

@@ -0,0 +1,115 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const VALID_AGENTS = new Set(['cursor', 'claude', 'agn']);
+
+/** Absolute path to the global orch config file. */
+export function globalConfigPath({ homedir = os.homedir() } = {}) {
+    return path.join(homedir, '.orch', 'config');
+}
+
+/** Absolute path to the project-local orch config file under `cwd`. */
+export function localConfigPath(cwd) {
+    return path.join(cwd, '.orch', 'config');
+}
+
+/**
+ * Read a config file. Missing file → `{}`. Bad JSON, unreadable file, or
+ * invalid `agent` → throws with a message suitable for `Error: …` on stderr.
+ * Unknown keys are ignored; `agent` is case-sensitive.
+ */
+export function loadConfig(configPath, displayPath = configPath) {
+    if (!fs.existsSync(configPath)) return {};
+
+    let raw;
+    try {
+        raw = fs.readFileSync(configPath, 'utf8');
+    } catch (err) {
+        throw new Error(`could not parse ${displayPath}: ${err.message}`);
+    }
+
+    let data;
+    try {
+        data = JSON.parse(raw);
+    } catch (err) {
+        throw new Error(`could not parse ${displayPath}: ${err.message}`);
+    }
+
+    if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+        throw new Error(`could not parse ${displayPath}: expected a JSON object`);
+    }
+
+    if (!Object.prototype.hasOwnProperty.call(data, 'agent') || data.agent === undefined) {
+        return {};
+    }
+
+    if (!VALID_AGENTS.has(data.agent)) {
+        throw new Error(
+            `invalid agent in ${displayPath}: ${JSON.stringify(data.agent)} (expected "cursor", "claude", or "agn")`,
+        );
+    }
+
+    return { agent: data.agent };
+}
+
+/**
+ * Effective agent for a run: `--agent` > local > global > `cursor`.
+ * Reads local then global when `cliAgent` is omitted; throws on bad files.
+ */
+export function resolveAgent({ cliAgent, cwd, homedir = os.homedir() } = {}) {
+    if (cliAgent) return cliAgent;
+
+    const local = loadConfig(localConfigPath(cwd), '.orch/config');
+    if (local.agent) return local.agent;
+
+    const global = loadConfig(globalConfigPath({ homedir }), '~/.orch/config');
+    if (global.agent) return global.agent;
+
+    return 'cursor';
+}
+
+/**
+ * Create parent dirs if needed, overwrite `config` with pretty-printed JSON,
+ * return the path written.
+ */
+export function writeConfig(configPath, { agent }) {
+    if (!VALID_AGENTS.has(agent)) {
+        throw new Error(
+            `invalid agent: ${JSON.stringify(agent)} (expected "cursor", "claude", or "agn")`,
+        );
+    }
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, `${JSON.stringify({ agent }, null, 2)}\n`);
+    return configPath;
+}
+
+/**
+ * Print effective agent and which file(s) contributed (stdout). Throws on
+ * invalid existing files — same fail-fast contract as a run.
+ */
+export function printConfig({
+    cwd,
+    homedir = os.homedir(),
+    log = console.log,
+} = {}) {
+    const localPath = localConfigPath(cwd);
+    const globalPath = globalConfigPath({ homedir });
+    const local = loadConfig(localPath, '.orch/config');
+    const global = loadConfig(globalPath, '~/.orch/config');
+
+    let agent = 'cursor';
+    let source = 'default (builtin)';
+    if (local.agent) {
+        agent = local.agent;
+        source = `local (${localPath})`;
+    } else if (global.agent) {
+        agent = global.agent;
+        source = `global (${globalPath})`;
+    }
+
+    log(`agent=${agent}`);
+    log(`source=${source}`);
+    log(`global=${global.agent ?? 'unset'} (${globalPath})`);
+    log(`local=${local.agent ?? 'unset'} (${localPath})`);
+}

package/lib/continue.js

@@ -0,0 +1,132 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJob, reconcileJob, jobPaths } from './jobs.js';
+
+const CONTINUE_ELIGIBLE = new Set(['done', 'failed', 'stopped', 'crashed']);
+
+/** Plain Error whose `toString()` is just the message (no `Error:` prefix), so
+ * `assert.throws(fn, /^exact message$/)` contracts match Node's RegExp check. */
+function fail(message) {
+    const err = new Error(message);
+    err.name = '';
+    return err;
+}
+
+/**
+ * Pure eligibility gate for `orch continue`. Reconciles first; never mutates
+ * beyond reconcile's dead-pid → crashed rewrite. Throws plain Error messages
+ * (CLI wraps with `Error: ${err.message}`).
+ */
+export function validateContinue(cwd, slug, { task, ask, quick } = {}) {
+    const existing = readJob(cwd, slug);
+    if (!existing) throw fail(`unknown run ${slug}`);
+
+    if (ask) throw fail('orch continue does not support --ask; use the default orch command');
+    if (quick) throw fail('orch continue does not support --quick; use the default orch command');
+
+    if (typeof task !== 'string' || !task.trim()) {
+        throw fail('task cannot be empty');
+    }
+
+    const record = reconcileJob(cwd, slug, existing);
+
+    if (!CONTINUE_ELIGIBLE.has(record.state)) {
+        throw fail(
+            `cannot continue ${slug} while state is ${record.state}; use orch resume / orch stop`,
+        );
+    }
+
+    if (record.role === 'coordinator') {
+        throw fail(
+            `cannot continue coordinator ${slug}; continue each failed worker slug, then orch --integrate ${slug}`,
+        );
+    }
+
+    if (record.role === 'integration') {
+        const parent = record.parent ?? '<parent-slug>';
+        throw fail(
+            `cannot continue integration ${slug}; use orch --integrate ${parent}`,
+        );
+    }
+
+    if (!record.worktree || !record.branch) {
+        throw fail(`${slug} has no worktree; continue only applies to complex runs`);
+    }
+
+    if (!fs.existsSync(record.worktree)) {
+        throw fail(`worktree missing at ${record.worktree}; cannot continue ${slug}`);
+    }
+
+    return record;
+}
+
+/**
+ * Snapshot prior outcome for continue reopen. Prefer `record.lastOutcome`;
+ * otherwise synthesize from terminal fields (+ best-effort status.md scrape).
+ * Never throws.
+ */
+export function snapshotPriorOutcome(cwd, slug, record) {
+    if (record?.lastOutcome) return record.lastOutcome;
+
+    let summary = '';
+    try {
+        const statusPath = path.join(jobPaths(cwd, slug).dir, 'status.md');
+        if (fs.existsSync(statusPath)) {
+            const content = fs.readFileSync(statusPath, 'utf8');
+            const matches = [...content.matchAll(/^- Summary:\s*(.*)$/gm)];
+            if (matches.length > 0) {
+                summary = (matches[matches.length - 1][1] || '').trim();
+            }
+        }
+    } catch {
+        summary = '';
+    }
+
+    return {
+        state: record.state,
+        phase: record.phase ?? null,
+        stage: record.stage ?? null,
+        round: record.round ?? null,
+        exitCode: record.exitCode ?? null,
+        finishedAt: record.finishedAt ?? null,
+        task: record.task ?? null,
+        summary,
+        error: null,
+    };
+}
+
+function displayOrNone(value) {
+    if (value == null || value === '') return '(none recorded)';
+    return String(value);
+}
+
+/**
+ * Build the `[Prior run outcome]…[/Prior run outcome]` block injected into
+ * research/planner prompts on continue.
+ */
+export function buildPriorOutcomeText(prior, {
+    slug,
+    continuation,
+    worktreePath,
+    branch,
+    parentSlug,
+    workerId,
+} = {}) {
+    const p = prior ?? {};
+    const lines = [
+        '[Prior run outcome]',
+        `- Continuation: this is continue ${continuation} on slug ${slug}`,
+        `- Prior state: ${displayOrNone(p.state)}`,
+        `- Prior phase: ${displayOrNone(p.phase)}`,
+        `- Prior stage: ${displayOrNone(p.stage)}`,
+        `- Prior round: ${p.round == null ? 'null' : p.round}`,
+        `- Prior task: ${displayOrNone(p.task)}`,
+        `- Summary: ${displayOrNone(p.summary)}`,
+        `- Error: ${displayOrNone(p.error)}`,
+        `- Worktree: ${worktreePath} (branch ${branch} tip is the starting point; do not assume a clean tree)`,
+    ];
+    if (parentSlug) lines.push(`- Fan-out parent: ${parentSlug}`);
+    if (workerId) lines.push(`- Worker id: ${workerId}`);
+    lines.push('[/Prior run outcome]');
+    return lines.join('\n');
+}

package/lib/jobs.js

@@ -5,6 +5,34 @@ import crypto from 'node:crypto';
 const ACTIVE_LIVE_STATES = ['running', 'pausing', 'paused'];
 const TERMINAL_STATES = ['done', 'failed', 'stopped', 'crashed'];
 
+/**
+ * Compact outcome written onto `run.json` with every terminal state transition.
+ * Shared so all call sites (pipelines, shutdown, reconcile) keep one shape.
+ */
+export function buildLastOutcome({
+    state,
+    phase = null,
+    stage = null,
+    round = null,
+    exitCode = null,
+    finishedAt,
+    task = null,
+    summary = '',
+    error = null,
+}) {
+    return {
+        state,
+        phase: phase ?? null,
+        stage: stage ?? null,
+        round: round ?? null,
+        exitCode: exitCode ?? null,
+        finishedAt,
+        task: task ?? null,
+        summary: summary ?? '',
+        error: error ?? null,
+    };
+}
+
 /** Absolute paths for a job's on-disk artifacts under `<cwd>/.orch/<slug>/`. */
 export function jobPaths(cwd, slug) {
     const dir = path.join(path.resolve(cwd), '.orch', slug);
@@ -136,10 +164,59 @@ export function patchJob(cwd, slug, patchFnOrObject) {
 export function reconcileJob(cwd, slug, record) {
     if (!ACTIVE_LIVE_STATES.includes(record.state)) return record;
     if (isPidAlive(record.pid)) return record;
+    return patchJob(cwd, slug, (current) => {
+        const finishedAt = new Date().toISOString();
+        return {
+            state: 'crashed',
+            finishedAt,
+            exitCode: null,
+            lastOutcome: buildLastOutcome({
+                state: 'crashed',
+                phase: current.phase,
+                stage: current.stage,
+                round: current.round,
+                exitCode: null,
+                finishedAt,
+                task: current.task,
+                summary: '',
+                error: null,
+            }),
+        };
+    });
+}
+
+/**
+ * Reopen an existing terminal job for `orch continue`. Patches in place —
+ * never allocates a new slug/directory. Bumps `continuation`, appends
+ * `continuations[]`, clears live `lastOutcome`, resets to running/research.
+ */
+export function reopenJob(cwd, slug, { task, agent, maxRounds, pid, prior, startedAt } = {}) {
+    const existing = readJob(cwd, slug);
+    if (!existing) throw new Error(`reopenJob: unknown job ${slug}`);
+
+    const started = startedAt ?? new Date().toISOString();
+    const continuation = (existing.continuation ?? 1) + 1;
+    const continuations = Array.isArray(existing.continuations)
+        ? [...existing.continuations]
+        : [];
+    continuations.push({ n: continuation, task, startedAt: started, prior: prior ?? null });
+
     return patchJob(cwd, slug, {
-        state: 'crashed',
-        finishedAt: new Date().toISOString(),
+        task,
+        agent,
+        maxRounds,
+        pid,
+        startedAt: started,
+        state: 'running',
+        phase: 'research',
+        stage: null,
+        round: null,
+        finishedAt: null,
         exitCode: null,
+        pauseRequested: false,
+        lastOutcome: null,
+        continuation,
+        continuations,
     });
 }
 

package/main.js

@@ -33,7 +33,14 @@ import {
     stopJob,
     cleanJobs,
     isPidAlive,
+    reopenJob,
+    buildLastOutcome,
 } from './lib/jobs.js';
+import {
+    validateContinue,
+    snapshotPriorOutcome,
+    buildPriorOutcomeText,
+} from './lib/continue.js';
 import { askAgentArgs } from './agents/ask.js';
 import { triageAgentArgs } from './agents/triage.js';
 import { quickFixAgentArgs } from './agents/quick-fix.js';
@@ -67,6 +74,13 @@ import {
     conflictedFiles,
     hasConflictMarkers,
 } from './lib/integrate.js';
+import {
+    resolveAgent,
+    writeConfig,
+    printConfig,
+    globalConfigPath,
+    localConfigPath,
+} from './lib/config.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -211,6 +225,18 @@ export function formatStatus(cwd, record) {
         lines.splice(1, 0, `parent:   ${record.parent}`);
     }
 
+    if (record.continuation > 1) {
+        const stateIdx = lines.findIndex((line) => line.startsWith('state:'));
+        lines.splice(stateIdx + 1, 0, `continuation: ${record.continuation}`);
+    }
+
+    if (record.lastOutcome) {
+        const o = record.lastOutcome;
+        lines.push(`outcome:  ${o.phase ?? '-'} / ${o.stage ?? '-'} (round ${o.round ?? '-'})`);
+        if (o.summary) lines.push(`summary:  ${o.summary}`);
+        if (o.error) lines.push(`error:    ${o.error}`);
+    }
+
     const statusPath = path.join(jobPaths(cwd, record.slug).dir, 'status.md');
     if (fs.existsSync(statusPath)) {
         const last = lastNonEmptyLine(fs.readFileSync(statusPath, 'utf8'));
@@ -275,6 +301,28 @@ function defaultExecFile(command, args, options = {}) {
     return execFileSync(command, args, { encoding: 'utf8', ...options });
 }
 
+/** Patch a job to a terminal state and write a matching `lastOutcome` in the same write. */
+function patchTerminalJob(patchJobFn, jobCwd, jobSlug, { state, exitCode, summary = '', error = null, task }) {
+    if (!jobSlug) return;
+    const finishedAt = new Date().toISOString();
+    patchJobFn(jobCwd, jobSlug, (current) => ({
+        state,
+        exitCode,
+        finishedAt,
+        lastOutcome: buildLastOutcome({
+            state,
+            phase: current.phase,
+            stage: current.stage,
+            round: current.round,
+            exitCode,
+            finishedAt,
+            task: task ?? current.task,
+            summary,
+            error,
+        }),
+    }));
+}
+
 /** The test-writer ⇄ test-critic loop shared by `runPipeline` and `runWorkerPipeline`. */
 async function runTestLoop({
     prompt,
@@ -729,7 +777,7 @@ export async function runPipeline(prompt, options) {
             .filter(Boolean)
             .join('\n');
 
-        await runCodeLoop({
+        const codeAccepted = await runCodeLoop({
             prompt,
             worktreePath: worktree.worktreePath,
             branch: worktree.branch,
@@ -762,6 +810,7 @@ export async function runPipeline(prompt, options) {
             );
             console.log(`commit: ${commitResult.sha.slice(0, 7)} on ${commitResult.branch}`);
             console.log(`merge:  git merge ${commitResult.branch}`);
+            console.log(`next:   orch continue ${runContext.slug} "…"`);
         } else {
             fs.appendFileSync(
                 runContext.statusPath,
@@ -770,20 +819,29 @@ export async function runPipeline(prompt, options) {
             console.log(`commit: no changes on ${commitResult.branch}`);
         }
 
-        jobPatch({ state: 'done', exitCode: 0, finishedAt: new Date().toISOString() });
+        patchTerminalJob(patchJobFn, jobCwd, jobSlug, {
+            state: 'done',
+            exitCode: 0,
+            summary: codeAccepted?.verdict?.summary ?? '',
+            error: null,
+            task: prompt,
+        });
     } catch (err) {
         console.error(`Error: ${err.message}`);
         if (jobSlug) {
             try {
-                patchJobFn(jobCwd, jobSlug, {
+                patchTerminalJob(patchJobFn, jobCwd, jobSlug, {
                     state: 'failed',
                     exitCode: 1,
-                    finishedAt: new Date().toISOString(),
+                    summary: '',
+                    error: err.message,
+                    task: prompt,
                 });
             } catch {
                 // Best-effort: don't let a job-state write failure mask the real error.
             }
         }
+        console.error(`next:   orch continue ${jobSlug ?? '<slug>'} "fix the failure and finish"`);
         process.exit(1);
     }
 }
@@ -846,6 +904,311 @@ export async function runDetached(prompt, options = {}) {
     exit(0);
 }
 
+/**
+ * Continue pipeline: full complex stages on an existing worktree/branch.
+ * Skips triage and `createWorktree`. Injects prior-outcome text into
+ * research/planner only. See `.spec/continue.md`.
+ */
+export async function runContinuePipeline(prompt, options = {}) {
+    const verbose = Boolean(options.verbose);
+    const maxRounds = options.maxRounds ?? 5;
+    const backend = AGENT_BACKENDS[options.agent];
+    if (!backend) {
+        throw new Error(`Unknown agent backend: ${options.agent}`);
+    }
+    const AgentClass = options.AgentClass ?? backend.AgentClass;
+    const cwd = options.cwd ?? process.cwd();
+    const {
+        slug,
+        worktreePath,
+        branch,
+        role,
+        parentSlug,
+        workerId,
+        priorOutcome,
+        continuation,
+    } = options;
+
+    const createRunContextFn = options.createRunContext ?? createRunContext;
+    const commitWorktreeFn = options.commitWorktree ?? commitWorktree;
+    const collectWorktreeChangesFn = options.collectWorktreeChanges ?? collectWorktreeChanges;
+    const patchWorkerFn = options.patchWorker ?? patchWorker;
+    const recordChangedFilesFn = options.recordChangedFiles ?? recordChangedFiles;
+    const execFileFn = options.execFile;
+
+    const jobSlug = options.jobSlug ?? slug ?? process.env.ORCH_JOB_SLUG;
+    const jobCwd = options.jobCwd ?? cwd;
+    const patchJobFn = options.patchJob ?? patchJob;
+    const checkpointPauseFn = options.checkpointPause ?? checkpointPause;
+    const pausePollIntervalMs = options.pausePollIntervalMs ?? 500;
+
+    const jobPatch = (fields) => {
+        if (!jobSlug) return;
+        patchJobFn(jobCwd, jobSlug, fields);
+    };
+    const jobCheckpoint = async () => {
+        if (!jobSlug) return;
+        await checkpointPauseFn(jobCwd, jobSlug, { pollIntervalMs: pausePollIntervalMs });
+    };
+
+    if (!options.AgentClass) {
+        ensureBinaryOnPath(backend.binary, options.agent);
+    }
+
+    const priorBlock = buildPriorOutcomeText(priorOutcome, {
+        slug,
+        continuation,
+        worktreePath,
+        branch,
+        parentSlug,
+        workerId,
+    });
+    const researchPlannerPrompt = `${priorBlock}\n\nUser follow-up:\n${prompt}`;
+
+    try {
+        const runContext = createRunContextFn({ cwd, slug });
+
+        fs.mkdirSync(path.dirname(runContext.statusPath), { recursive: true });
+        const prior = priorOutcome ?? {};
+        const startedIso = new Date().toISOString();
+        let continueSection = `\n## Continue ${continuation}\n\n`;
+        continueSection += `- Task: ${prompt.split('\n')[0]}\n`;
+        continueSection += `- Started: ${startedIso}\n`;
+        continueSection += `- Branch: \`${branch}\`\n`;
+        continueSection += `- Worktree: \`${worktreePath}\`\n`;
+        if (parentSlug) continueSection += `- Fan-out parent: \`${parentSlug}\`\n`;
+        if (workerId) continueSection += `- Worker id: \`${workerId}\`\n`;
+        continueSection += `\n### Prior outcome\n\n`;
+        continueSection += `- State: ${prior.state ?? '(none recorded)'}\n`;
+        continueSection += `- Phase: ${prior.phase ?? '(none recorded)'}\n`;
+        continueSection += `- Stage: ${prior.stage ?? '(none recorded)'}\n`;
+        continueSection += `- Round: ${prior.round ?? 'null'}\n`;
+        continueSection += `- Summary: ${prior.summary || '(none recorded)'}\n`;
+        if (prior.error) continueSection += `- Error: ${prior.error}\n`;
+        fs.appendFileSync(runContext.statusPath, continueSection);
+
+        jobPatch({ phase: 'research', stage: 'research', round: null });
+        const research = researchAgentArgs({
+            prompt: researchPlannerPrompt,
+            cwd: worktreePath,
+            researchPath: runContext.researchPath,
+        });
+        const researchAgent = new AgentClass(
+            research.name,
+            research.instructions,
+            research.prompt,
+            research.options,
+        );
+        const researchResult = await researchAgent.run({ verbose });
+        await jobCheckpoint();
+        const { content: researchContent, summary: researchSummary } = splitStageSummary(researchResult.result);
+        printStageSummary('research', researchSummary);
+
+        jobPatch({ phase: 'plan', stage: 'planner', round: null });
+        const planner = plannerAgentArgs({
+            prompt: researchPlannerPrompt,
+            cwd: worktreePath,
+            researchPath: runContext.researchPath,
+            taskPath: runContext.taskPath,
+            researchOutput: researchContent,
+        });
+        const plannerAgent = new AgentClass(
+            planner.name,
+            planner.instructions,
+            planner.prompt,
+            planner.options,
+        );
+        const plannerResult = await plannerAgent.run({ verbose });
+        await jobCheckpoint();
+        const { summary: plannerSummary } = splitStageSummary(plannerResult.result);
+        printStageSummary('planner', plannerSummary);
+
+        const testAccepted = await runTestLoop({
+            prompt,
+            worktreePath,
+            branch,
+            taskPath: runContext.taskPath,
+            statusPath: runContext.statusPath,
+            maxRounds,
+            AgentClass,
+            verbose,
+            jobPatch,
+            jobCheckpoint,
+        });
+
+        const acceptedVerification = [testAccepted.verdict.summary, testAccepted.writerContent]
+            .filter(Boolean)
+            .join('\n');
+
+        const codeAccepted = await runCodeLoop({
+            prompt,
+            worktreePath,
+            branch,
+            taskPath: runContext.taskPath,
+            statusPath: runContext.statusPath,
+            maxRounds,
+            AgentClass,
+            verbose,
+            jobPatch,
+            jobCheckpoint,
+            acceptedVerification,
+        });
+
+        jobPatch({ phase: 'commit', stage: 'commit', round: null });
+        const message = `orch: ${slug} (continue ${continuation}): ${prompt.split('\n')[0]}`;
+        const worktreeChanges = collectWorktreeChangesFn({ worktreePath });
+        printFilesChanged(worktreeChanges);
+        const commitResult = commitWorktreeFn({
+            worktreePath,
+            branch,
+            message,
+        });
+
+        if (commitResult.committed) {
+            fs.appendFileSync(
+                runContext.statusPath,
+                `\n## Commit\n\n- SHA: \`${commitResult.sha}\`\n- Branch: \`${commitResult.branch}\`\n`,
+            );
+            console.log(`commit: ${commitResult.sha.slice(0, 7)} on ${commitResult.branch}`);
+            console.log(`merge:  git merge ${commitResult.branch}`);
+        } else {
+            fs.appendFileSync(
+                runContext.statusPath,
+                `\n## Commit\n\n- No changes to commit on \`${commitResult.branch}\`.\n`,
+            );
+            console.log(`commit: no changes on ${commitResult.branch}`);
+        }
+
+        if (role === 'worker' && parentSlug && workerId) {
+            let changedFiles = [];
+            try {
+                changedFiles = recordChangedFilesFn({
+                    repoRoot: cwd,
+                    base: undefined,
+                    branch,
+                    execFile: execFileFn,
+                });
+            } catch {
+                // Best-effort.
+            }
+            if (commitResult.committed) {
+                patchWorkerFn(cwd, parentSlug, workerId, {
+                    state: 'done',
+                    sha: commitResult.sha,
+                    changedFiles,
+                });
+                console.log(`next:   orch --integrate ${parentSlug}`);
+            }
+        }
+
+        patchTerminalJob(patchJobFn, jobCwd, jobSlug, {
+            state: 'done',
+            exitCode: 0,
+            summary: codeAccepted?.verdict?.summary ?? '',
+            error: null,
+            task: prompt,
+        });
+    } catch (err) {
+        console.error(`Error: ${err.message}`);
+        if (role === 'worker' && parentSlug && workerId) {
+            try {
+                patchWorkerFn(cwd, parentSlug, workerId, { state: 'failed' });
+            } catch {
+                // Best-effort.
+            }
+        }
+        if (jobSlug) {
+            try {
+                patchTerminalJob(patchJobFn, jobCwd, jobSlug, {
+                    state: 'failed',
+                    exitCode: 1,
+                    summary: '',
+                    error: err.message,
+                    task: prompt,
+                });
+            } catch {
+                // Best-effort.
+            }
+        }
+        process.exit(1);
+    }
+}
+
+/**
+ * Detach-parent path for `orch continue`: validate, PATH-check, spawn a
+ * `--detach`-stripped re-invocation, reopen the existing slug with the child
+ * pid, print `started`, exit. Never runs pipeline stages itself.
+ */
+export async function runContinueDetached(slug, prompt, options = {}) {
+    const {
+        agent,
+        maxRounds = 5,
+        verbose,
+        cwd = process.cwd(),
+        spawn: spawnFn = spawn,
+        exit = (code) => process.exit(code),
+        validateContinue: validateContinueFn = validateContinue,
+        reopenJob: reopenJobFn = reopenJob,
+        snapshotPriorOutcome: snapshotPriorOutcomeFn = snapshotPriorOutcome,
+    } = options;
+
+    const backend = AGENT_BACKENDS[agent];
+    if (!backend) {
+        throw new Error(`Unknown agent backend: ${agent}`);
+    }
+
+    let record;
+    try {
+        record = validateContinueFn(cwd, slug, { task: prompt });
+    } catch (err) {
+        console.error(`Error: ${err.message}`);
+        exit(1);
+        return;
+    }
+
+    if (!isBinaryOnPath(backend.binary)) {
+        console.error(binaryMissingHint(agent));
+        exit(1);
+        return;
+    }
+
+    const prior = snapshotPriorOutcomeFn(cwd, slug, record);
+    const { logPath } = jobPaths(cwd, slug);
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    const logFd = fs.openSync(logPath, 'a');
+
+    const childArgs = [
+        __filename,
+        'continue',
+        slug,
+        prompt,
+        '--agent',
+        agent,
+        '--max-rounds',
+        String(maxRounds),
+    ];
+    if (verbose) childArgs.push('--verbose');
+
+    const child = spawnFn(process.execPath, childArgs, {
+        cwd,
+        env: { ...process.env, ORCH_JOB_SLUG: slug, ORCH_DETACHED: '1' },
+        detached: true,
+        stdio: ['ignore', logFd, logFd],
+    });
+    child.unref();
+
+    const updated = reopenJobFn(cwd, slug, {
+        task: prompt,
+        agent,
+        maxRounds,
+        pid: child.pid,
+        prior,
+    });
+
+    console.log(`started ${slug} (pid ${child.pid}, continuation ${updated.continuation})`);
+    exit(0);
+}
+
 /**
  * The `--worker <parent>:<workerId>` driver: skips triage and runs research → planner →
  * worktree (from the fan-out's recorded `base`) → test loop → code loop (writer-first) →
@@ -954,7 +1317,7 @@ export async function runWorkerPipeline(prompt, options = {}) {
             .filter(Boolean)
             .join('\n');
 
-        await runCodeLoop({
+        const codeAccepted = await runCodeLoop({
             prompt,
             worktreePath: worktree.worktreePath,
             branch: worktree.branch,
@@ -1009,7 +1372,13 @@ export async function runWorkerPipeline(prompt, options = {}) {
             sha: commitResult.sha,
             changedFiles,
         });
-        jobPatch({ state: 'done', exitCode: 0, finishedAt: new Date().toISOString() });
+        patchTerminalJob(patchJobFn, jobCwd, jobSlug, {
+            state: 'done',
+            exitCode: 0,
+            summary: codeAccepted?.verdict?.summary ?? '',
+            error: null,
+            task: prompt,
+        });
     } catch (err) {
         console.error(`Error: ${err.message}`);
         try {
@@ -1019,15 +1388,19 @@ export async function runWorkerPipeline(prompt, options = {}) {
         }
         if (jobSlug) {
             try {
-                patchJobFn(jobCwd, jobSlug, {
+                patchTerminalJob(patchJobFn, jobCwd, jobSlug, {
                     state: 'failed',
                     exitCode: 1,
-                    finishedAt: new Date().toISOString(),
+                    summary: '',
+                    error: err.message,
+                    task: prompt,
                 });
             } catch {
                 // Best-effort: don't let a job-state write failure mask the real error.
             }
         }
+        console.error(`next:   orch continue ${jobSlug ?? '<slug>'} "fix the failure and finish"`);
+        if (parentSlug) console.error(`        orch --integrate ${parentSlug}`);
         process.exit(1);
     }
 }
@@ -1217,7 +1590,7 @@ export async function runIntegratePipeline(options = {}) {
         }
 
         // --- runner-first verify loop: test-runner first, code-writer only on failure ---
-        await runCodeLoop({
+        const codeAccepted = await runCodeLoop({
             prompt: fanout.task,
             worktreePath: worktree.worktreePath,
             branch: worktree.branch,
@@ -1253,7 +1626,13 @@ export async function runIntegratePipeline(options = {}) {
             merged,
             skipped,
         });
-        jobPatch({ state: 'done', exitCode: 0, finishedAt: new Date().toISOString() });
+        patchTerminalJob(patchJobFn, jobCwd, jobSlug, {
+            state: 'done',
+            exitCode: 0,
+            summary: codeAccepted?.verdict?.summary ?? '',
+            error: null,
+            task: fanout.task,
+        });
     } catch (err) {
         console.error(`Error: ${err.message}`);
         try {
@@ -1268,10 +1647,12 @@ export async function runIntegratePipeline(options = {}) {
         }
         if (jobSlug) {
             try {
-                patchJobFn(jobCwd, jobSlug, {
+                patchTerminalJob(patchJobFn, jobCwd, jobSlug, {
                     state: 'failed',
                     exitCode: 1,
-                    finishedAt: new Date().toISOString(),
+                    summary: '',
+                    error: err.message,
+                    task: fanout?.task,
                 });
             } catch {
                 // Best-effort: don't let a job-state write failure mask the real error.
@@ -1392,11 +1773,24 @@ export async function runFanoutPipeline(prompt, options = {}) {
         }
         if (jobSlug) {
             try {
-                patchJobFn(jobCwd, jobSlug, {
+                const exitCode = exitCodeForSignal(signal);
+                const finishedAt = new Date().toISOString();
+                patchJobFn(jobCwd, jobSlug, (current) => ({
                     state: 'stopped',
-                    exitCode: exitCodeForSignal(signal),
-                    finishedAt: new Date().toISOString(),
-                });
+                    exitCode,
+                    finishedAt,
+                    lastOutcome: buildLastOutcome({
+                        state: 'stopped',
+                        phase: current.phase,
+                        stage: current.stage,
+                        round: current.round,
+                        exitCode,
+                        finishedAt,
+                        task: prompt,
+                        summary: '',
+                        error: null,
+                    }),
+                }));
             } catch {
                 // Best-effort: don't let a job-state write failure block shutdown.
             }
@@ -1942,17 +2336,31 @@ export async function runFanoutPipeline(prompt, options = {}) {
             console.log(`retry integration after fixing it: orch --integrate ${jobSlug}`);
         }
 
-        jobPatch({ state: success ? 'done' : 'failed', exitCode: success ? 0 : 1, finishedAt: new Date().toISOString() });
+        const finishedAt = new Date().toISOString();
+        const summary = success
+            ? `fan-out complete: ${doneWorkers.length} worker${doneWorkers.length === 1 ? '' : 's'} integrated`
+            : (failedWorkers.length > 0
+                ? `${failedWorkers.length} worker(s) failed`
+                : 'fan-out failed');
+        patchTerminalJob(patchJobFn, jobCwd, jobSlug, {
+            state: success ? 'done' : 'failed',
+            exitCode: success ? 0 : 1,
+            summary,
+            error: success ? null : summary,
+            task: prompt,
+        });
         exitFn(success ? 0 : 1);
     } catch (err) {
         if (err instanceof FanoutInterrupted) return;
         console.error(`Error: ${err.message}`);
         if (jobSlug) {
             try {
-                patchJobFn(jobCwd, jobSlug, {
+                patchTerminalJob(patchJobFn, jobCwd, jobSlug, {
                     state: 'failed',
                     exitCode: 1,
-                    finishedAt: new Date().toISOString(),
+                    summary: '',
+                    error: err.message,
+                    task: prompt,
                 });
             } catch {
                 // Best-effort: don't let a job-state write failure mask the real error.
@@ -2093,6 +2501,17 @@ function positiveIntParser(flagName) {
     };
 }
 
+/** Resolve the effective agent (CLI > local > global > cursor) or exit 1. */
+function resolveAgentOrExit(cliAgent, cwd = process.cwd()) {
+    try {
+        return resolveAgent({ cliAgent, cwd });
+    } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+        return undefined;
+    }
+}
+
 const program = new Command();
 
 program
@@ -2110,9 +2529,8 @@ program
     .option('--max-workers <n>', 'Max number of parallel fan-out workers (only meaningful with --fan-out)', positiveIntParser('--max-workers'), 4)
     .option('--max-concurrency <n>', 'Optional hard ceiling on in-flight fan-out workers at once (only meaningful with --fan-out; default: coordinator chooses)', positiveIntParser('--max-concurrency'))
     .addOption(
-        new Option('--agent <agent>', 'Agent backend to run the pipeline with: "cursor" (Cursor Agent CLI), "claude" (Claude Code CLI), or "agn" (agn CLI)')
-            .choices(['cursor', 'claude', 'agn'])
-            .default('cursor'),
+        new Option('--agent <agent>', 'Agent backend to run the pipeline with: "cursor" (Cursor Agent CLI), "claude" (Claude Code CLI), or "agn" (agn CLI). Omitting uses local then global config, else cursor')
+            .choices(['cursor', 'claude', 'agn']),
     )
     .addOption(new Option('--worker <value>', 'internal: run a single fan-out worker "<parent-slug>:<worker-id>"').hideHelp())
     .addOption(new Option('--integrate <value>', 'internal: (re)run fan-out integration for "<parent-slug>"').hideHelp())
@@ -2126,13 +2544,18 @@ Examples:
   $ orch --ask "where is the CLI entrypoint?" --agent claude
   $ orch --quick "fix the typo in the README" --agent claude
   $ orch "noop" --dry-run --agent cursor
+  $ orch config                                          # print effective agent
+  $ orch config --agent claude                           # pin global default
+  $ orch config --agent agn --local                      # pin project default
 
 Headless runs:
   $ orch "long-running task" --detach --agent claude   # start in the background, prints the run slug
   $ orch list                                          # show all tracked runs
   $ orch status [slug]                                 # show full status (defaults to most recent)
   $ orch pause <slug>                                  # request a pause at the next stage boundary
-  $ orch resume <slug>                                 # resume a paused/pausing run
+  $ orch resume <slug>                                 # unpause a paused/pausing run
+  $ orch continue <slug> "new task"                    # new work on a finished run's worktree
+                                                       # (workers: same command; then re-integrate the parent)
   $ orch stop <slug>                                   # send SIGTERM to a running job
   $ orch logs <slug> [-f]                              # print (or follow) a run's log file
 
@@ -2149,6 +2572,8 @@ Fan-out:
             return;
         }
 
+        options.agent = resolveAgentOrExit(options.agent);
+
         if (options.fanOut) {
             const conflicts = ['ask', 'quick', 'dryRun']
                 .filter((key) => options[key])
@@ -2235,6 +2660,178 @@ Fan-out:
         await runPipeline(prompt, options);
     });
 
+program
+    .command('continue')
+    .description(
+        'Start new complex work on a finished run\'s existing worktree (not the same as resume, which only unpauses). Workers: continue the worker slug, then re-integrate the parent',
+    )
+    .argument('<slug>', 'Existing run slug under .orch/')
+    .argument('<task...>', 'New task prompt for this continue iteration')
+    .option('-v, --verbose', 'Stream agent thinking/output deltas to stderr as the pipeline runs')
+    .option('--dry-run', 'Validate eligibility and agent PATH; do not reopen the job or run agents')
+    .option('--ask', 'Rejected: continue does not support --ask')
+    .option('--quick', 'Rejected: continue does not support --quick')
+    .option('--detach', 'Run the continue in the background under the same slug')
+    .option('--max-rounds <n>', 'Max writer⇄critic and writer⇄runner iterations per implementer loop', positiveIntParser('--max-rounds'), 5)
+    .addOption(
+        new Option('--agent <agent>', 'Agent backend: "cursor", "claude", or "agn". Omitting uses local then global config, else cursor')
+            .choices(['cursor', 'claude', 'agn']),
+    )
+    .action(async (slug, taskParts, options, command) => {
+        // Parent program also defines --ask/--quick/--dry-run/--agent/--detach/
+        // --max-rounds; when those flags appear after the continue arguments,
+        // Commander attaches them to the parent. Merge via optsWithGlobals.
+        const opts = typeof command.optsWithGlobals === 'function'
+            ? command.optsWithGlobals()
+            : { ...program.opts(), ...options };
+        const prompt = taskParts.join(' ').trim();
+        const cwd = process.cwd();
+
+        opts.agent = resolveAgentOrExit(opts.agent, cwd);
+
+        let record;
+        try {
+            record = validateContinue(cwd, slug, {
+                task: prompt,
+                ask: opts.ask,
+                quick: opts.quick,
+            });
+        } catch (err) {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+            return;
+        }
+
+        if (opts.detach) {
+            await runContinueDetached(slug, prompt, {
+                agent: opts.agent,
+                maxRounds: opts.maxRounds,
+                verbose: opts.verbose,
+                cwd,
+            });
+            return;
+        }
+
+        if (opts.dryRun) {
+            const backend = AGENT_BACKENDS[opts.agent];
+            if (!isBinaryOnPath(backend.binary)) {
+                console.error(binaryMissingHint(opts.agent));
+                process.exit(1);
+                return;
+            }
+            console.log(`dry-run: continue ${slug} ok`);
+            return;
+        }
+
+        const alreadyReopened = Boolean(process.env.ORCH_JOB_SLUG);
+        let priorOutcome;
+        let continuation;
+        let worktreePath = record.worktree;
+        let branch = record.branch;
+        let role = record.role;
+        let parentSlug = record.parent;
+        let workerId = record.workerId;
+
+        if (!alreadyReopened) {
+            priorOutcome = snapshotPriorOutcome(cwd, slug, record);
+            const updated = reopenJob(cwd, slug, {
+                task: prompt,
+                agent: opts.agent,
+                maxRounds: opts.maxRounds,
+                pid: process.pid,
+                prior: priorOutcome,
+            });
+            continuation = updated.continuation;
+            setJobSlug(slug);
+        } else {
+            const live = readJob(cwd, slug) ?? record;
+            continuation = live.continuation ?? 2;
+            const entries = Array.isArray(live.continuations) ? live.continuations : [];
+            const last = entries[entries.length - 1];
+            priorOutcome = last?.prior ?? snapshotPriorOutcome(cwd, slug, live);
+            worktreePath = live.worktree ?? worktreePath;
+            branch = live.branch ?? branch;
+            role = live.role ?? role;
+            parentSlug = live.parent ?? parentSlug;
+            workerId = live.workerId ?? workerId;
+            setJobSlug(slug);
+        }
+
+        // PATH check after reopen (foreground) so empty-PATH tests can observe the bump.
+        const backend = AGENT_BACKENDS[opts.agent];
+        ensureBinaryOnPath(backend.binary, opts.agent);
+
+        await runContinuePipeline(prompt, {
+            agent: opts.agent,
+            maxRounds: opts.maxRounds,
+            verbose: opts.verbose,
+            cwd,
+            slug,
+            worktreePath,
+            branch,
+            role,
+            parentSlug,
+            workerId,
+            priorOutcome,
+            continuation,
+            jobSlug: slug,
+            jobCwd: cwd,
+        });
+    });
+
+program
+    .command('config')
+    .description('Print or set the default agent (global ~/.orch/config or local .orch/config)')
+    .addOption(
+        new Option('--agent <agent>', 'Set the default agent backend')
+            .choices(['cursor', 'claude', 'agn']),
+    )
+    .option('--global', 'Write the global config (~/.orch/config); default when --agent is set')
+    .option('--local', 'Write the project-local config (.orch/config)')
+    .action((options, command) => {
+        // Parent also defines --agent; flags after `config` may land on the
+        // parent. Merge so either placement works.
+        const opts = typeof command.optsWithGlobals === 'function'
+            ? command.optsWithGlobals()
+            : { ...program.opts(), ...options };
+        const cwd = process.cwd();
+
+        if (opts.global && opts.local) {
+            console.error('Error: --global and --local are mutually exclusive');
+            process.exit(1);
+            return;
+        }
+
+        if ((opts.global || opts.local) && !opts.agent) {
+            console.error('Error: --global/--local require --agent (omit flags to print config)');
+            process.exit(1);
+            return;
+        }
+
+        if (opts.agent) {
+            const targetPath = opts.local
+                ? localConfigPath(cwd)
+                : globalConfigPath();
+            try {
+                writeConfig(targetPath, { agent: opts.agent });
+            } catch (err) {
+                console.error(`Error: ${err.message}`);
+                process.exit(1);
+                return;
+            }
+            console.log(`wrote ${targetPath}`);
+            process.stdout.write(`${JSON.stringify({ agent: opts.agent }, null, 2)}\n`);
+            return;
+        }
+
+        try {
+            printConfig({ cwd });
+        } catch (err) {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
+    });
+
 program
     .command('list')
     .description('List all runs (active and finished) tracked under .orch/ in this directory')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@welluable/orch",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "CLI orchestrator: triage → research → plan → implement",
   "type": "module",
   "main": "main.js",