@welluable/orch 1.3.0 → 1.4.0

package/lib/agent-cursor.js

@@ -1,4 +1,4 @@
-import { Agent } from './agent.js';
+import { Agent, appendVerbose } from './agent.js';
 import { normalizeCursorToolEvent } from './tool-status.js';
 
 export class AgentCursor extends Agent {
@@ -26,8 +26,10 @@ export class AgentCursor extends Agent {
             case 'thinking': {
                 switch (event.subtype) {
                     case 'delta': {
+                        const text = event.text ?? '';
+                        appendVerbose(text);
                         if (verbose) {
-                            process.stderr.write(event.text ?? '');
+                            process.stderr.write(text);
                         } else if (this.activeTools.size === 0) {
                             this.setStatus('thinking…');
                         }

package/lib/agent-opencode.js

@@ -0,0 +1,177 @@
+import { Agent, modelPrintState, appendVerbose } from './agent.js';
+import { normalizeOpencodeToolEvent } from './tool-status.js';
+
+const OPENCODE_DENY_PERMISSION = '{"edit":"deny","bash":"deny"}';
+
+export class AgentOpencode extends Agent {
+    #textBuffer = '';
+    #sawStepStart = false;
+    #pendingStop = false;
+    #settled = false;
+
+    getSpawnConfig(promptToSend) {
+        if (this.readOnly) {
+            return {
+                command: 'opencode',
+                args: ['run', '--format', 'json', '--auto', '--thinking', '--agent', 'plan', promptToSend],
+                options: {
+                    cwd: this.cwd,
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                    env: { ...process.env, OPENCODE_PERMISSION: OPENCODE_DENY_PERMISSION },
+                },
+            };
+        }
+
+        return {
+            command: 'opencode',
+            args: ['run', '--format', 'json', '--auto', '--thinking', promptToSend],
+            options: {
+                cwd: this.cwd,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                env: process.env,
+            },
+        };
+    }
+
+    #printModelOnce(modelId) {
+        if (modelPrintState.printed || typeof modelId !== 'string' || !modelId) return;
+        modelPrintState.printed = true;
+        const wasSpinning = this.spinner?.isSpinning;
+        if (wasSpinning) this.spinner.stop?.();
+        console.log(`model: ${modelId}`);
+        if (wasSpinning) this.spinner.start?.();
+    }
+
+    #printUsageLine(part) {
+        const tokens = part?.tokens;
+        if (!tokens || typeof tokens !== 'object') return;
+        const input = tokens.input ?? tokens.in;
+        const output = tokens.output ?? tokens.out;
+        if (typeof input !== 'number' && typeof output !== 'number') return;
+
+        let line = `  tokens: in=${input ?? 0} out=${output ?? 0}`;
+        const cost = part.cost;
+        if (typeof cost === 'number' && cost > 0) {
+            line += ` · cost=$${cost}`;
+        }
+        process.stderr.write(`${line}\n`);
+    }
+
+    #settleOk(finish, { verbose = false, part = null } = {}) {
+        if (this.#settled) return;
+        this.#settled = true;
+        this.#pendingStop = false;
+        this.settleResult(
+            {
+                is_error: false,
+                result: this.#textBuffer,
+                duration_ms: undefined,
+            },
+            finish,
+        );
+        if (verbose && part) this.#printUsageLine(part);
+    }
+
+    #recordApplyPatchFiles(toolEvent) {
+        if (toolEvent.name !== 'apply_patch' || !this.fileTracker) return;
+        const entries = this.fileTracker.recordApplyPatch(toolEvent.args?.patchText);
+        for (const entry of entries) {
+            if (!entry.isNew) continue;
+            const wasSpinning = this.spinner?.isSpinning;
+            if (wasSpinning) this.spinner.stop();
+            console.log(`  ${entry.marker} ${entry.path}`);
+            if (wasSpinning) this.spinner.start();
+            this.onFileChange?.(entry);
+        }
+    }
+
+    handleStreamEvent(event, { verbose, finish }) {
+        switch (event.type) {
+            case 'message.updated': {
+                this.#printModelOnce(event.properties?.info?.modelID);
+                break;
+            }
+            case 'step_start': {
+                if (!this.#sawStepStart) {
+                    this.#sawStepStart = true;
+                    this.setStatus('connected');
+                } else if (this.activeTools.size === 0) {
+                    this.setStatus('thinking…');
+                }
+                break;
+            }
+            case 'tool_use': {
+                const toolEvent = normalizeOpencodeToolEvent(event);
+                if (!toolEvent) break;
+                this.onToolEvent({ ...toolEvent, phase: 'started' });
+                this.onToolEvent(toolEvent);
+                this.#recordApplyPatchFiles(toolEvent);
+                break;
+            }
+            case 'reasoning': {
+                const text = event.part?.text ?? '';
+                appendVerbose(text);
+                if (verbose) {
+                    process.stderr.write(text);
+                } else if (this.activeTools.size === 0) {
+                    this.setStatus('thinking…');
+                }
+                break;
+            }
+            case 'text': {
+                const text = event.part?.text ?? '';
+                this.#textBuffer += text;
+                appendVerbose(text);
+                if (verbose) {
+                    process.stderr.write(text);
+                } else if (this.activeTools.size === 0) {
+                    this.setStatus('composing response…');
+                }
+                if (this.#pendingStop && this.#textBuffer !== '') {
+                    this.#settleOk(finish, { verbose });
+                }
+                break;
+            }
+            case 'step_finish': {
+                const reason = event.part?.reason;
+                if (reason === 'tool-calls') break;
+                if (reason === 'stop' || reason == null) {
+                    if (this.#textBuffer !== '') {
+                        this.#settleOk(finish, { verbose, part: event.part });
+                    } else {
+                        this.#pendingStop = true;
+                    }
+                }
+                break;
+            }
+            case 'error': {
+                if (this.#settled) break;
+                this.#settled = true;
+                this.#pendingStop = false;
+                const message =
+                    event.error?.data?.message ||
+                    event.error?.name ||
+                    'OpenCode error';
+                this.settleResult(
+                    {
+                        is_error: true,
+                        result: message,
+                    },
+                    finish,
+                );
+                break;
+            }
+            default:
+                break;
+        }
+    }
+
+    handleProcessClose(code, finish) {
+        if (this.#settled) return;
+        if (code === 0 && this.#textBuffer !== '') {
+            this.#settleOk(finish);
+            return;
+        }
+        super.handleProcessClose(code, finish);
+    }
+}

package/lib/agent.js

@@ -1,8 +1,13 @@
 import { spawn } from 'child_process';
 import path from 'path';
 import ora from 'ora';
-import { formatActiveTools } from './tool-status.js';
-import { patchJob, buildLastOutcome } from './jobs.js';
+import { formatActiveTools, toolPath } from './tool-status.js';
+import { patchJob, buildLastOutcome, jobPaths, readJob } from './jobs.js';
+import {
+    appendFailureLog,
+    failureLogPointer,
+    formatFailureSection,
+} from './failure-log.js';
 
 /**
  * Every child process spawned by an agent, tracked so we can reap them all
@@ -43,6 +48,116 @@ export function setJobSlug(slug) {
     activeJobSlug = slug;
 }
 
+/** Active job slug: env (detached child) wins over in-process foreground slug. */
+export function getActiveJobSlug() {
+    return process.env.ORCH_JOB_SLUG ?? activeJobSlug;
+}
+
+/** Current stage capture + prior-stage ring for failure.log (independent of -v). */
+let currentCapture = null;
+/** @type {{ phase: *, stage: *, round: *, verbose: string }[]} */
+let priorCaptures = [];
+const PRIOR_RING_MAX = 8;
+
+/** Clear failure-log buffers (also invoked from `resetShutdownState`). */
+export function resetFailureLogState() {
+    currentCapture = null;
+    priorCaptures = [];
+}
+
+/**
+ * Start capturing verbose for a stage. Rotates a non-empty current buffer into
+ * the prior-stage ring so recover can see more than the final frame.
+ */
+export function beginStageCapture({ phase = null, stage = null, round = null } = {}) {
+    if (currentCapture && currentCapture.verbose) {
+        priorCaptures.push({
+            phase: currentCapture.phase,
+            stage: currentCapture.stage,
+            round: currentCapture.round,
+            verbose: currentCapture.verbose,
+        });
+        if (priorCaptures.length > PRIOR_RING_MAX) {
+            priorCaptures.splice(0, priorCaptures.length - PRIOR_RING_MAX);
+        }
+    }
+    currentCapture = { phase, stage, round, verbose: '' };
+}
+
+/**
+ * Append a verbose chunk when a job slug is active. Never gated on `-v`
+ * (stderr streaming stays verbose-gated in the backends).
+ */
+export function appendVerbose(chunk) {
+    if (!getActiveJobSlug()) return;
+    if (chunk == null || chunk === '') return;
+    if (!currentCapture) {
+        currentCapture = { phase: null, stage: null, round: null, verbose: '' };
+    }
+    currentCapture.verbose += String(chunk);
+}
+
+/**
+ * Append one `=== orch failure ===` section to `.orch/<slug>/failure.log`,
+ * patch `run.json.failureLogPath`, and return a pointer string. No-op when
+ * `slug` is falsy.
+ */
+export function flushFailureLog({
+    cwd,
+    slug,
+    state,
+    exitCode = null,
+    finishedAt,
+    task = null,
+    error = null,
+} = {}) {
+    if (!slug) return null;
+
+    const resolvedCwd = cwd ?? process.cwd();
+    let phase = currentCapture?.phase ?? null;
+    let stage = currentCapture?.stage ?? null;
+    let round = currentCapture?.round ?? null;
+    let resolvedTask = task;
+
+    if (phase == null || stage == null || round == null || resolvedTask == null) {
+        try {
+            const record = readJob(resolvedCwd, slug);
+            if (record) {
+                if (phase == null) phase = record.phase ?? null;
+                if (stage == null) stage = record.stage ?? null;
+                if (round == null) round = record.round ?? null;
+                if (resolvedTask == null) resolvedTask = record.task ?? null;
+            }
+        } catch {
+            // Best-effort cursor fill from run.json.
+        }
+    }
+
+    const { failureLogPath } = jobPaths(resolvedCwd, slug);
+    const section = formatFailureSection({
+        slug,
+        state,
+        phase,
+        stage,
+        round,
+        exitCode,
+        finishedAt,
+        task: resolvedTask,
+        error,
+        stageVerbose: currentCapture?.verbose ?? '',
+        priorStages: priorCaptures,
+    });
+    appendFailureLog(failureLogPath, section);
+
+    try {
+        patchJob(resolvedCwd, slug, { failureLogPath });
+    } catch {
+        // Best-effort: file is already on disk even if the patch fails.
+    }
+
+    return failureLogPointer(slug);
+}
+
 /** Conventional shell status: 128 + signal number. */
 export function exitCodeForSignal(signal) {
     if (signal === 'SIGINT') return 130;
@@ -69,6 +184,14 @@ export function shutdown(signal, { exit = (code) => process.exit(code), jobCwd =
         try {
             const exitCode = exitCodeForSignal(signal);
             const finishedAt = new Date().toISOString();
+            const pointer = flushFailureLog({
+                cwd: jobCwd,
+                slug: jobSlug,
+                state: 'stopped',
+                exitCode,
+                finishedAt,
+                error: signal,
+            });
             patchJob(jobCwd, jobSlug, (current) => ({
                 state: 'stopped',
                 exitCode,
@@ -82,7 +205,7 @@ export function shutdown(signal, { exit = (code) => process.exit(code), jobCwd =
                     finishedAt,
                     task: current.task,
                     summary: '',
-                    error: null,
+                    error: pointer,
                 }),
             }));
         } catch {
@@ -125,6 +248,7 @@ export function resetShutdownState() {
     shuttingDown = false;
     liveChildren.clear();
     activeJobSlug = null;
+    resetFailureLogState();
 }
 
 /**
@@ -209,10 +333,14 @@ export class Agent {
         this.refreshSpinnerText();
     }
 
-    /** @param {{ name: string, args: Record<string, unknown>, phase: 'started'|'completed', callId: string }} toolEvent */
-    onToolEvent({ name, args, phase, callId }) {
+    /** @param {{ name: string, args: Record<string, unknown>, phase: 'started'|'completed', callId: string, title?: string }} toolEvent */
+    onToolEvent({ name, args, phase, callId, title }) {
         if (phase === 'started') {
-            this.activeTools.set(callId, { name, args });
+            this.activeTools.set(callId, {
+                name,
+                args,
+                ...(typeof title === 'string' && title ? { title } : {}),
+            });
             this.fileTracker?.record({ name, args, phase, callId });
         } else if (phase === 'completed') {
             // Recall before delete — Claude/agn completions often have empty args.
@@ -220,7 +348,7 @@ export class Agent {
             this.activeTools.delete(callId);
 
             if (this.fileTracker) {
-                const hasPath = Boolean(args?.path || args?.file_path);
+                const hasPath = Boolean(toolPath(args));
                 const entry = this.fileTracker.record({
                     name: name || prior?.name || '',
                     args: hasPath ? args : (prior?.args ?? args ?? {}),
@@ -279,6 +407,20 @@ export class Agent {
         throw new Error('handleStreamEvent must be implemented by subclass');
     }
 
+    /**
+     * Called when the child exits before a settling stream event.
+     * Subclasses may override (e.g. defensive success on exit 0 + buffered text).
+     * @param {number|null} code
+     * @param {(err: Error|null, value?: object) => void} finish
+     */
+    handleProcessClose(code, finish) {
+        this.stopElapsedTimer();
+        if (this.spinner?.isSpinning) {
+            this.spinner.fail(`[${this.name}] exited ${code}`);
+        }
+        finish(new Error(`[${this.name}] exited ${code} before result`));
+    }
+
     settleResult(event, finish) {
         this.stopElapsedTimer();
         this.activeTools.clear();
@@ -376,11 +518,7 @@ export class Agent {
                 liveChildren.delete(child);
                 this.process = null;
                 if (!settled) {
-                    this.stopElapsedTimer();
-                    if (this.spinner?.isSpinning) {
-                        this.spinner.fail(`[${this.name}] exited ${code}`);
-                    }
-                    finish(new Error(`[${this.name}] exited ${code} before result`));
+                    this.handleProcessClose(code, finish);
                 }
             });
         });

package/lib/config.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
-const VALID_AGENTS = new Set(['cursor', 'claude', 'agn']);
+const VALID_AGENTS = new Set(['cursor', 'claude', 'agn', 'opencode']);
 
 /** Absolute path to the global orch config file. */
 export function globalConfigPath({ homedir = os.homedir() } = {}) {
@@ -16,8 +16,8 @@ export function localConfigPath(cwd) {
 
 /**
  * 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.
+ * invalid `agent` / `notify` → 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 {};
@@ -40,17 +40,27 @@ export function loadConfig(configPath, displayPath = configPath) {
         throw new Error(`could not parse ${displayPath}: expected a JSON object`);
     }
 
-    if (!Object.prototype.hasOwnProperty.call(data, 'agent') || data.agent === undefined) {
-        return {};
+    const out = {};
+
+    if (Object.prototype.hasOwnProperty.call(data, 'agent') && data.agent !== undefined) {
+        if (!VALID_AGENTS.has(data.agent)) {
+            throw new Error(
+                `invalid agent in ${displayPath}: ${JSON.stringify(data.agent)} (expected "cursor", "claude", "agn", or "opencode")`,
+            );
+        }
+        out.agent = data.agent;
     }
 
-    if (!VALID_AGENTS.has(data.agent)) {
-        throw new Error(
-            `invalid agent in ${displayPath}: ${JSON.stringify(data.agent)} (expected "cursor", "claude", or "agn")`,
-        );
+    if (Object.prototype.hasOwnProperty.call(data, 'notify') && data.notify !== undefined) {
+        if (typeof data.notify !== 'boolean') {
+            throw new Error(
+                `invalid notify in ${displayPath}: ${JSON.stringify(data.notify)} (expected true or false)`,
+            );
+        }
+        out.notify = data.notify;
     }
 
-    return { agent: data.agent };
+    return out;
 }
 
 /**
@@ -70,23 +80,74 @@ export function resolveAgent({ cliAgent, cwd, homedir = os.homedir() } = {}) {
 }
 
 /**
- * Create parent dirs if needed, overwrite `config` with pretty-printed JSON,
+ * Effective notify for a run: CLI > local > global > `true`.
+ * `cliNotify` is `true` | `false` | `undefined` (flag omitted).
+ */
+export function resolveNotify({ cliNotify, cwd, homedir = os.homedir() } = {}) {
+    if (cliNotify === true || cliNotify === false) return cliNotify;
+
+    const local = loadConfig(localConfigPath(cwd), '.orch/config');
+    if (typeof local.notify === 'boolean') return local.notify;
+
+    const global = loadConfig(globalConfigPath({ homedir }), '~/.orch/config');
+    if (typeof global.notify === 'boolean') return global.notify;
+
+    return true;
+}
+
+/**
+ * Create parent dirs if needed, merge `agent` / `notify` into the existing
+ * config object (preserve the other key), overwrite with pretty-printed JSON,
  * return the path written.
  */
-export function writeConfig(configPath, { agent }) {
-    if (!VALID_AGENTS.has(agent)) {
+export function writeConfig(configPath, { agent, notify } = {}) {
+    if (agent !== undefined && !VALID_AGENTS.has(agent)) {
+        throw new Error(
+            `invalid agent: ${JSON.stringify(agent)} (expected "cursor", "claude", "agn", or "opencode")`,
+        );
+    }
+    if (notify !== undefined && typeof notify !== 'boolean') {
         throw new Error(
-            `invalid agent: ${JSON.stringify(agent)} (expected "cursor", "claude", or "agn")`,
+            `invalid notify: ${JSON.stringify(notify)} (expected true or false)`,
         );
     }
+
+    let existing = {};
+    if (fs.existsSync(configPath)) {
+        try {
+            const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+            if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+                existing = raw;
+            }
+        } catch {
+            // Corrupt file: start fresh; caller already validated inputs.
+            existing = {};
+        }
+    }
+
+    const next = { ...existing };
+    if (agent !== undefined) next.agent = agent;
+    if (notify !== undefined) next.notify = notify;
+
+    // Persist only known keys (drop unknown junk from a prior merge? Spec says
+    // unknown keys are ignored on load but does not require stripping on write.
+    // Keep agent/notify; preserve other keys already present.)
+    const out = {};
+    if (next.agent !== undefined) out.agent = next.agent;
+    if (next.notify !== undefined) out.notify = next.notify;
+    for (const [k, v] of Object.entries(next)) {
+        if (k === 'agent' || k === 'notify') continue;
+        out[k] = v;
+    }
+
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
-    fs.writeFileSync(configPath, `${JSON.stringify({ agent }, null, 2)}\n`);
+    fs.writeFileSync(configPath, `${JSON.stringify(out, 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.
+ * Print effective agent/notify and which file(s) contributed (stdout). Throws
+ * on invalid existing files — same fail-fast contract as a run.
  */
 export function printConfig({
     cwd,
@@ -108,8 +169,22 @@ export function printConfig({
         source = `global (${globalPath})`;
     }
 
+    let notify = true;
+    let notifySource = 'default (builtin)';
+    if (typeof local.notify === 'boolean') {
+        notify = local.notify;
+        notifySource = `local (${localPath})`;
+    } else if (typeof global.notify === 'boolean') {
+        notify = global.notify;
+        notifySource = `global (${globalPath})`;
+    }
+
     log(`agent=${agent}`);
     log(`source=${source}`);
     log(`global=${global.agent ?? 'unset'} (${globalPath})`);
     log(`local=${local.agent ?? 'unset'} (${localPath})`);
+    log(`notify=${notify}`);
+    log(`notifySource=${notifySource}`);
+    log(`notifyGlobal=${typeof global.notify === 'boolean' ? global.notify : 'unset'} (${globalPath})`);
+    log(`notifyLocal=${typeof local.notify === 'boolean' ? local.notify : 'unset'} (${localPath})`);
 }

package/lib/continue.js

@@ -1,8 +1,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { readJob, reconcileJob, jobPaths } from './jobs.js';
+import { readSeq } from './seq.js';
 
-const CONTINUE_ELIGIBLE = new Set(['done', 'failed', 'stopped', 'crashed']);
+const CONTINUE_ELIGIBLE = new Set(['done']);
+const FAILURE_TERMINALS = new Set(['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. */
@@ -16,6 +18,9 @@ function fail(message) {
  * 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}`).
+ *
+ * Continue is follow-up work on primarily `done` jobs. Terminal failures
+ * refuse by default and point at `orch resume` (see `.spec/resume.md`).
  */
 export function validateContinue(cwd, slug, { task, ask, quick } = {}) {
     const existing = readJob(cwd, slug);
@@ -30,13 +35,12 @@ export function validateContinue(cwd, slug, { task, ask, quick } = {}) {
 
     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') {
+        if (readSeq(cwd, slug)) {
+            throw fail(
+                `cannot continue coordinator ${slug}; continue each failed unit slug, then orch --seq-continue ${slug} or orch resume ${slug}`,
+            );
+        }
         throw fail(
             `cannot continue coordinator ${slug}; continue each failed worker slug, then orch --integrate ${slug}`,
         );
@@ -49,6 +53,20 @@ export function validateContinue(cwd, slug, { task, ask, quick } = {}) {
         );
     }
 
+    if (FAILURE_TERMINALS.has(record.state)) {
+        const phase = record.phase ?? record.lastOutcome?.phase ?? '?';
+        const stage = record.stage ?? record.lastOutcome?.stage ?? '?';
+        throw fail(
+            `${slug} is ${record.state} at ${phase}/${stage};\nuse: orch resume ${slug}`,
+        );
+    }
+
+    if (!CONTINUE_ELIGIBLE.has(record.state)) {
+        throw fail(
+            `cannot continue ${slug} while state is ${record.state}; use orch resume / orch stop`,
+        );
+    }
+
     if (!record.worktree || !record.branch) {
         throw fail(`${slug} has no worktree; continue only applies to complex runs`);
     }