@welluable/orch 1.0.0 → 1.2.0

package/lib/jobs.js

@@ -0,0 +1,284 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+const ACTIVE_LIVE_STATES = ['running', 'pausing', 'paused'];
+const TERMINAL_STATES = ['done', 'failed', 'stopped', 'crashed'];
+
+/** 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);
+    return {
+        dir,
+        runJsonPath: path.join(dir, 'run.json'),
+        lockPath: path.join(dir, '.run.lock'),
+        logPath: path.join(dir, 'orch.log'),
+    };
+}
+
+function atomicWriteJson(dir, filePath, data) {
+    fs.mkdirSync(dir, { recursive: true });
+    const tmpPath = path.join(
+        dir,
+        `.${path.basename(filePath)}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`,
+    );
+    fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2));
+    fs.renameSync(tmpPath, filePath);
+}
+
+/** Atomically (write-temp + rename) writes a job record to `run.json`. */
+export function writeJob(cwd, slug, record) {
+    const { dir, runJsonPath } = jobPaths(cwd, slug);
+    atomicWriteJson(dir, runJsonPath, record);
+}
+
+/** Reads and parses `run.json`; `null` if missing; throws on invalid JSON. */
+export function readJob(cwd, slug) {
+    const { runJsonPath } = jobPaths(cwd, slug);
+    let content;
+    try {
+        content = fs.readFileSync(runJsonPath, 'utf8');
+    } catch (err) {
+        if (err.code === 'ENOENT') return null;
+        throw err;
+    }
+    return JSON.parse(content);
+}
+
+/** `process.kill(pid, 0)` wrapped in try/catch; never throws. */
+export function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function sleepSync(ms) {
+    const view = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(view, 0, 0, ms);
+}
+
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Acquires `.run.lock` via exclusive create, busy-waiting on contention.
+ * A lock whose owner pid is no longer alive is treated as stale and removed.
+ */
+function acquireLock(lockPath, { timeoutMs = 5000, retryMs = 5 } = {}) {
+    const start = Date.now();
+    for (;;) {
+        try {
+            const fd = fs.openSync(lockPath, 'wx');
+            fs.writeSync(fd, JSON.stringify({ pid: process.pid }));
+            fs.closeSync(fd);
+            return;
+        } catch (err) {
+            if (err.code !== 'EEXIST') throw err;
+
+            let ownerPid = null;
+            try {
+                ownerPid = JSON.parse(fs.readFileSync(lockPath, 'utf8')).pid;
+            } catch {
+                // Lock file mid-write or briefly unreadable; treat as contention.
+            }
+
+            if (ownerPid != null && !isPidAlive(ownerPid)) {
+                try {
+                    fs.unlinkSync(lockPath);
+                } catch {
+                    // Another process may have removed it first; retry.
+                }
+                continue;
+            }
+
+            if (Date.now() - start > timeoutMs) {
+                throw new Error(`patchJob: timed out waiting for lock ${lockPath}`);
+            }
+            sleepSync(retryMs);
+        }
+    }
+}
+
+/**
+ * Locks, re-reads, shallow-merges `patchFnOrObject` (an object, or a
+ * `(current) => partialPatch` function) over the latest record, atomically
+ * writes, unlocks, and returns the updated record.
+ */
+export function patchJob(cwd, slug, patchFnOrObject) {
+    const { dir, runJsonPath, lockPath } = jobPaths(cwd, slug);
+    fs.mkdirSync(dir, { recursive: true });
+    acquireLock(lockPath);
+    try {
+        const current = readJob(cwd, slug) ?? {};
+        const patch = typeof patchFnOrObject === 'function' ? patchFnOrObject(current) : patchFnOrObject;
+        const updated = { ...current, ...patch };
+        atomicWriteJson(dir, runJsonPath, updated);
+        return updated;
+    } finally {
+        try {
+            fs.unlinkSync(lockPath);
+        } catch {
+            // Already gone; nothing to clean up.
+        }
+    }
+}
+
+/**
+ * If `record` is in an active live state (running/pausing/paused) and its
+ * pid is dead, atomically rewrites it to `crashed` and returns the updated
+ * record. Otherwise returns `record` unchanged.
+ */
+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, {
+        state: 'crashed',
+        finishedAt: new Date().toISOString(),
+        exitCode: null,
+    });
+}
+
+/** Every `run.json` under `<cwd>/.orch/*`, reconciled, most-recent-first by `startedAt`. */
+export function listJobs(cwd) {
+    const orchDir = path.join(path.resolve(cwd), '.orch');
+    if (!fs.existsSync(orchDir)) return [];
+
+    const slugs = fs.readdirSync(orchDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name);
+
+    const jobs = [];
+    for (const slug of slugs) {
+        const record = readJob(cwd, slug);
+        if (!record) continue;
+        jobs.push(reconcileJob(cwd, slug, record));
+    }
+
+    jobs.sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
+    return jobs;
+}
+
+/**
+ * Cooperative pause point: no-op if `pauseRequested` is falsy. Otherwise
+ * patches to `paused`, polls `run.json` (no lock/fd held) until
+ * `pauseRequested` clears, then patches back to `running`.
+ */
+export async function checkpointPause(cwd, slug, { pollIntervalMs = 500 } = {}) {
+    const record = readJob(cwd, slug);
+    if (!record?.pauseRequested) return;
+
+    patchJob(cwd, slug, { state: 'paused' });
+
+    for (;;) {
+        await sleep(pollIntervalMs);
+        const current = readJob(cwd, slug);
+        if (!current?.pauseRequested) break;
+    }
+
+    patchJob(cwd, slug, { state: 'running' });
+}
+
+/** The pure operation behind `orch pause <slug>`. */
+export function requestPause(cwd, slug) {
+    const record = readJob(cwd, slug);
+    if (!record) throw new Error(`requestPause: unknown job ${slug}`);
+    if (TERMINAL_STATES.includes(record.state)) {
+        throw new Error(`requestPause: job ${slug} is in terminal state ${record.state}`);
+    }
+    if (record.state === 'pausing' || record.state === 'paused') return record;
+
+    const patch = { pauseRequested: true };
+    if (record.state === 'running') patch.state = 'pausing';
+    return patchJob(cwd, slug, patch);
+}
+
+/** The pure operation behind `orch resume <slug>`. */
+export function requestResume(cwd, slug) {
+    const record = readJob(cwd, slug);
+    if (!record) throw new Error(`requestResume: unknown job ${slug}`);
+    if (TERMINAL_STATES.includes(record.state)) {
+        throw new Error(`requestResume: job ${slug} is in terminal state ${record.state}`);
+    }
+    return patchJob(cwd, slug, { pauseRequested: false, state: 'running' });
+}
+
+/**
+ * The pure operation behind `orch stop <slug>`: signals a live pid (leaving
+ * the eventual `stopped` write to the child's own `shutdown()`), or
+ * reconciles a dead one to `crashed`. `kill` is injectable for tests.
+ */
+export function stopJob(cwd, slug, { kill = (pid, signal) => process.kill(pid, signal) } = {}) {
+    const record = readJob(cwd, slug);
+    if (!record) throw new Error(`stopJob: unknown job ${slug}`);
+
+    if (TERMINAL_STATES.includes(record.state)) {
+        return { action: 'already-terminal', record };
+    }
+
+    if (isPidAlive(record.pid)) {
+        kill(record.pid, 'SIGTERM');
+        return { action: 'signaled', record };
+    }
+
+    const reconciled = reconcileJob(cwd, slug, record);
+    if (reconciled.state === 'crashed' && record.state !== 'crashed') {
+        return { action: 'crashed', record: reconciled };
+    }
+    return { action: 'already-terminal', record: reconciled };
+}
+
+const LIVE_PAUSE_STATES = ['running', 'pausing', 'paused'];
+
+/**
+ * Parent → children pause: `requestPause` on the parent, then the same pause
+ * write on every child with `parent === parentSlug` in a live pause state.
+ * Returns how many children were cascade-targeted (CLI prints this count).
+ */
+export function cascadePause(cwd, parentSlug) {
+    requestPause(cwd, parentSlug);
+    let childrenSignaled = 0;
+    for (const job of listJobs(cwd)) {
+        if (job.parent !== parentSlug) continue;
+        if (!LIVE_PAUSE_STATES.includes(job.state)) continue;
+        requestPause(cwd, job.slug);
+        childrenSignaled += 1;
+    }
+    return { childrenSignaled };
+}
+
+/**
+ * Parent → children resume: `requestResume` on the parent, then cascade
+ * resume only to non-terminal children that are `paused`/`pausing`.
+ */
+export function cascadeResume(cwd, parentSlug) {
+    requestResume(cwd, parentSlug);
+    let childrenSignaled = 0;
+    for (const job of listJobs(cwd)) {
+        if (job.parent !== parentSlug) continue;
+        if (job.state !== 'paused' && job.state !== 'pausing') continue;
+        requestResume(cwd, job.slug);
+        childrenSignaled += 1;
+    }
+    return { childrenSignaled };
+}
+
+/**
+ * The pure operation behind `orch jobs clean`: removes every entry under
+ * `<cwd>/.orch/`. Returns the names that were deleted (empty if `.orch`
+ * is missing or already empty).
+ */
+export function cleanJobs(cwd) {
+    const orchDir = path.join(path.resolve(cwd), '.orch');
+    if (!fs.existsSync(orchDir)) return [];
+
+    const names = fs.readdirSync(orchDir);
+    for (const name of names) {
+        fs.rmSync(path.join(orchDir, name), { recursive: true, force: true });
+    }
+    return names;
+}

package/lib/parse-decomposition.js

@@ -0,0 +1,33 @@
+/** Parse decomposer agent final message as JSON. Returns null on any failure. */
+export function parseDecomposition(result) {
+    if (typeof result !== 'string') return null;
+
+    const trimmed = result.trim();
+    if (!trimmed) return null;
+
+    const tryParse = (text) => {
+        try {
+            return JSON.parse(text);
+        } catch {
+            return null;
+        }
+    };
+
+    let parsed = tryParse(trimmed);
+    if (parsed && typeof parsed === 'object') return parsed;
+
+    const fenceMatch = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    if (fenceMatch) {
+        parsed = tryParse(fenceMatch[1].trim());
+        if (parsed && typeof parsed === 'object') return parsed;
+    }
+
+    const start = trimmed.indexOf('{');
+    const end = trimmed.lastIndexOf('}');
+    if (start !== -1 && end > start) {
+        parsed = tryParse(trimmed.slice(start, end + 1));
+        if (parsed && typeof parsed === 'object') return parsed;
+    }
+
+    return null;
+}

package/lib/run-context.js

@@ -8,10 +8,22 @@ import { generateSlug as defaultGenerateSlug } from './slug.js';
  * generated directory already exists; throws once attempts are exhausted
  * rather than reusing or repairing an existing directory.
  */
-export function createRunContext({ cwd, generateSlug = defaultGenerateSlug, maxAttempts = 5 } = {}) {
+export function createRunContext({ cwd, slug, generateSlug = defaultGenerateSlug, maxAttempts = 5 } = {}) {
     const absCwd = path.resolve(cwd);
     const orchDir = path.join(absCwd, '.orch');
 
+    if (slug) {
+        const artifactDir = path.join(orchDir, slug);
+        fs.mkdirSync(artifactDir, { recursive: true });
+        return {
+            slug,
+            artifactDir,
+            researchPath: path.join(artifactDir, 'research.md'),
+            taskPath: path.join(artifactDir, 'task.md'),
+            statusPath: path.join(artifactDir, 'status.md'),
+        };
+    }
+
     for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
         const slug = generateSlug();
         const artifactDir = path.join(orchDir, slug);

package/lib/stage-summary.js

@@ -24,11 +24,93 @@ export function splitStageSummary(raw) {
 }
 
 /**
- * Print a blank line followed by `[label] summary: <summary>`. No-op when
- * summary is empty so stages that return no summary don't print a broken line.
+ * Split a one-paragraph summary into sentence-sized bullet lines. Splits at
+ * a `.`/`!`/`?` only when it's followed by whitespace and then a capital
+ * letter or digit, so periods inside filenames/versions (e.g. "status.md")
+ * don't cause a false split.
  */
-export function printStageSummary(label, summary) {
-    if (!summary) return;
+function splitSummaryIntoBullets(summary) {
+    const normalized = summary.replace(/\s+/g, ' ').trim();
+    if (!normalized) return [];
+    return normalized
+        .split(/(?<=[.!?])\s+(?=[A-Z0-9])/)
+        .map((sentence) => sentence.trim())
+        .filter(Boolean);
+}
+
+const FILES_NOTES_HEADER_RE = /^\s*files\s*:?\s*$/i;
+
+/**
+ * Pull an optional trailing `Files:` block (one `<path>: <one-line note>`
+ * per line) off the end of a stage summary, so writer agents can attach a
+ * short description to each file they touched. Returns the prose with that
+ * block removed plus a `path -> note` map; when no `Files:` line is present
+ * the summary passes through unchanged and the map is empty.
+ */
+function extractFileNotes(summary) {
+    const lines = summary.split('\n');
+    const headerIdx = lines.findIndex((line) => FILES_NOTES_HEADER_RE.test(line));
+    if (headerIdx === -1) return { prose: summary, notes: new Map() };
+
+    const notes = new Map();
+    for (const line of lines.slice(headerIdx + 1)) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        const sep = trimmed.indexOf(':');
+        if (sep === -1) continue;
+        const notePath = trimmed.slice(0, sep).trim();
+        const note = trimmed.slice(sep + 1).trim();
+        if (notePath && note) notes.set(notePath, note);
+    }
+
+    return { prose: lines.slice(0, headerIdx).join('\n').trim(), notes };
+}
+
+/**
+ * Print a titled, bulleted block for a stage's summary paragraph, e.g.:
+ *
+ *   ──────────
+ *    triage
+ *   ──────────
+ *     • Sentence one.
+ *     • Sentence two.
+ *   Files (2)
+ *     ~ lib/agent.js - wired the tracker into onToolEvent
+ *     + lib/file-tracker.js - added the ordered/deduped file collector
+ *
+ * A trailing `Files:` block in `summary` (one `<path>: <note>` per line)
+ * supplies the per-file note; a file with no matching note prints as before
+ * (marker + path only). Prints when prose or files are nonempty; both
+ * empty → no-op.
+ *
+ * @param {string} label
+ * @param {string} summary
+ * @param {{ marker: string, path: string }[]=} files
+ */
+export function printStageSummary(label, summary, files) {
+    const { prose, notes } = extractFileNotes(summary || '');
+    const hasSummary = Boolean(prose);
+    const hasFiles = Array.isArray(files) && files.length > 0;
+    if (!hasSummary && !hasFiles) return;
+
+    const title = ` ${label} `;
+    const rule = '─'.repeat(title.length);
+
+    console.log();
+    console.log(rule);
+    console.log(title);
+    console.log(rule);
+    if (hasSummary) {
+        for (const bullet of splitSummaryIntoBullets(prose)) {
+            console.log(`  • ${bullet}`);
+        }
+    }
+    if (hasFiles) {
+        console.log(`  Files (${files.length})`);
+        for (const { marker, path: filePath } of files) {
+            const note = notes.get(filePath);
+            console.log(`    ${marker} ${filePath}${note ? ` - ${note}` : ''}`);
+        }
+    }
     console.log();
-    console.log(`[${label}] summary: ${summary}`);
 }

package/lib/worktree.js

@@ -22,7 +22,7 @@ function runGit(execFile, args) {
  * `execFile` is injectable and defaults to a `child_process.execFileSync`
  * wrapper.
  */
-export function createWorktree({ cwd, slug, execFile = defaultExecFile }) {
+export function createWorktree({ cwd, slug, execFile = defaultExecFile, base }) {
     const repoRoot = runGit(execFile, ['-C', cwd, 'rev-parse', '--show-toplevel']).trim();
 
     const worktreePath = `${path.join(path.dirname(repoRoot), path.basename(repoRoot))}-${slug}`;
@@ -32,7 +32,9 @@ export function createWorktree({ cwd, slug, execFile = defaultExecFile }) {
         throw new Error(`createWorktree: refusing to overwrite existing path ${worktreePath}`);
     }
 
-    runGit(execFile, ['-C', repoRoot, 'worktree', 'add', '-b', branch, worktreePath]);
+    const args = ['-C', repoRoot, 'worktree', 'add', '-b', branch, worktreePath];
+    if (base) args.push(base);
+    runGit(execFile, args);
 
     return { repoRoot, worktreePath, branch };
 }