cheap-agent 0.0.0-stage → 1.0.0

package/dist/plan.js

@@ -0,0 +1,117 @@
+import { DIFFICULTIES } from "./routing.js";
+const REQUIRED = ["files", "done-when"];
+/** The plan grammar in one line, for Claude: the delegate tool description and every plan-error FAIL carry it. */
+export const PLAN_FORMAT = 'Plan format: one "# <title>" line, then per step a "## <id> <title>" heading followed by "files: <paths>", "do: <what>", "done-when: <check>" (optional "dont:", "needs: <step ids>", "difficulty: easy|medium|hard"), each key at the start of its line, not a bullet. In done-when, `backticked` text is run as a shell command that must succeed; put only commands in backticks.';
+/** Parses a plan; throws with a precise, line-numbered reason when it does not follow the format. */
+export function parsePlan(source) {
+    const lines = source.split(/\r?\n/);
+    let title;
+    const context = [];
+    const steps = [];
+    let field;
+    lines.forEach((line, i) => {
+        const at = `line ${i + 1}`;
+        if (/^# /.test(line)) {
+            if (title !== undefined)
+                throw new Error(`${at}: a plan has exactly one H1 title`);
+            title = line.slice(2).trim();
+            return;
+        }
+        if (/^## /.test(line)) {
+            if (title === undefined)
+                throw new Error(`${at}: step before the plan's H1 title`);
+            const m = line.match(/^## +(\d+[a-z]?)(?: +(.*))?$/);
+            if (!m)
+                throw new Error(`${at}: step heading needs an id (integer or integer+letter), e.g. "## 3 add route"`);
+            if (steps.some((s) => s.id === m[1]))
+                throw new Error(`${at}: duplicate step id ${m[1]}`);
+            steps.push({ id: m[1], title: (m[2] ?? "").trim(), fields: {}, text: line, line: i + 1 });
+            field = undefined;
+            return;
+        }
+        const step = steps.at(-1);
+        if (!step) {
+            if (title !== undefined && line.trim())
+                context.push(line);
+            return;
+        }
+        step.text += `\n${line}`;
+        const kv = line.match(/^([a-z][a-z-]*):\s?(.*)$/);
+        if (kv) {
+            field = kv[1];
+            step.fields[field] = kv[2].trim();
+        }
+        else if (/^ {2,}\S/.test(line) && field) {
+            step.fields[field] += `\n${line.trim()}`;
+        }
+        else if (line.trim()) {
+            field = undefined; // free prose inside a step is kept in its text, not a field
+        }
+    });
+    if (title === undefined)
+        throw new Error("plan has no H1 title (\"# <title>\")");
+    if (!steps.length)
+        throw new Error("plan has no steps (\"## <id> <title>\")");
+    for (const step of steps) {
+        const missing = REQUIRED.filter((key) => !step.fields[key]);
+        if (missing.length)
+            throw new Error(`step ${step.id} (line ${step.line}): missing ${missing.map((k) => `${k}:`).join(", ")}`);
+        const d = step.fields.difficulty;
+        if (d !== undefined && !DIFFICULTIES.includes(d))
+            throw new Error(`step ${step.id} (line ${step.line}): difficulty: must be ${DIFFICULTIES.join(", ")} or left out`);
+    }
+    return { title, context: context.join("\n").trim(), steps: steps.map(({ line, ...step }) => ({ ...step, text: step.text.trim() })) };
+}
+/**
+ * Resolves a steps string to groups (spec D2): `"3"` one step, `"3-5"` a range run in order as one group, and commas
+ * separate groups (`"1-2,3,4"`). Groups come back in plan order; a step may be in only one group.
+ */
+export function selectGroups(plan, spec) {
+    const index = (id) => {
+        const i = plan.steps.findIndex((s) => s.id === id);
+        if (i < 0)
+            throw new Error(`step ${id} not found (plan steps: ${plan.steps.map((s) => s.id).join(", ")})`);
+        return i;
+    };
+    const seen = new Set();
+    const groups = spec.split(",").map((raw) => {
+        const part = raw.trim();
+        const m = part.match(/^(\d+[a-z]?)(?:\s*-\s*(\d+[a-z]?))?$/);
+        if (!m)
+            throw new Error(`steps "${spec}": "${part}" is not a step id or range; use e.g. "3", "3-5" or "1-2,3,4"`);
+        const [from, to] = [index(m[1]), index(m[2] ?? m[1])];
+        if (to < from)
+            throw new Error(`steps "${spec}": range ${part} runs backwards`);
+        const steps = plan.steps.slice(from, to + 1);
+        for (const s of steps) {
+            if (seen.has(s.id))
+                throw new Error(`steps "${spec}": step ${s.id} is in more than one group`);
+            seen.add(s.id);
+        }
+        return { label: m[2] ? `${m[1]}-${m[2]}` : m[1], steps, at: from };
+    });
+    const sorted = groups.sort((a, b) => a.at - b.at).map(({ at, ...g }) => g);
+    // groups land in step order, so a group waiting on a later one would never land
+    sorted.forEach((g, i) => {
+        const later = needsOf(g).find((id) => sorted.slice(i + 1).some((o) => o.steps.some((s) => s.id === id)));
+        if (later)
+            throw new Error(`steps "${spec}": step ${g.label} needs ${later}, which comes later in the plan; put dependencies first`);
+    });
+    return sorted;
+}
+/** Where two groups' `files:` overlap: an equal entry, or one inside the other's directory entry. Returns the inner path. */
+export function overlap(a, b) {
+    const files = (g) => g.steps.flatMap((s) => s.fields.files.split(/[,\n]/)).map((f) => f.trim().replace(/^\.\//, "").replace(/\/+$/, "")).filter(Boolean);
+    const theirs = files(b);
+    for (const x of files(a)) {
+        for (const y of theirs) {
+            if (x === y || x.startsWith(`${y}/`))
+                return x;
+            if (y.startsWith(`${x}/`))
+                return y;
+        }
+    }
+    return undefined;
+}
+/** The step ids a group's `needs:` names, outside the group itself (a range already runs in order). */
+export const needsOf = (g) => [...new Set(g.steps.flatMap((s) => (s.fields.needs ?? "").split(/[\s,]+/).filter(Boolean)))].filter((id) => !g.steps.some((s) => s.id === id));

package/dist/platform.js

@@ -0,0 +1,52 @@
+import { lstatSync, symlinkSync, unlinkSync } from "node:fs";
+import { sep } from "node:path";
+/**
+ * Platform: everything OS-specific lives here (spec A18). POSIX only in v1; a Windows port swaps in directory
+ * junctions, long-path handling and `taskkill /T` behind these same functions.
+ */
+export const UNSUPPORTED_REASON = "Windows not supported yet; use WSL";
+export const UNSUPPORTED = `FAIL reason: ${UNSUPPORTED_REASON}`;
+/** macOS and Linux (WSL reports linux) are supported; native Windows is not yet. */
+export const isSupported = (platform = process.platform) => platform !== "win32";
+/** Links a dependency directory into a worktree. */
+export function link(target, path) {
+    symlinkSync(target, path, "dir");
+}
+/** Removes a link made by `link`, never what it points to; does nothing if `path` is not a link. */
+export function removeLink(path) {
+    try {
+        if (lstatSync(path).isSymbolicLink())
+            unlinkSync(path);
+    }
+    catch {
+        // already gone
+    }
+}
+/** Forward-slash form of a relative path, as result blocks show paths. */
+export const normalisePath = (path) => path.split(sep).join("/");
+/** Whether a process is still running (one we may not signal still counts as running). */
+export function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/** How OpenCode's per-platform npm packages name this OS, and its binary's file name. */
+export function opencodePlatform() {
+    const os = process.platform === "win32" ? "windows" : process.platform;
+    return { os, binary: os === "windows" ? "opencode.exe" : "opencode" };
+}
+/** Signals a whole process group (a child spawned `detached`), ignoring one that is already gone. */
+export function killProcessGroup(pid, signal = "SIGTERM") {
+    if (!pid)
+        return;
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        // already gone
+    }
+}

package/dist/report.js

@@ -0,0 +1,178 @@
+const STATUS_SECTIONS = {
+    OK: [],
+    PARTIAL: ["found", "missing", "worktree"],
+    FAIL: ["error", "found", "tried", "reason", "worktree"],
+    BLOCKED: ["question"],
+    CONFLICT: ["conflict", "worktree"],
+    CANCELLED: ["reason", "worktree"],
+    TIMEOUT: ["found", "reason", "missing", "worktree"],
+    BUDGET: ["found", "reason", "worktree"],
+};
+// D6 urgency; CANCELLED is not ranked by the spec and sits with BUDGET/TIMEOUT
+const URGENCY = ["BLOCKED", "CONFLICT", "FAIL", "BUDGET", "TIMEOUT", "CANCELLED", "PARTIAL", "RUNNING", "OK"];
+const rank = (s) => (s === "TIMEOUT" || s === "CANCELLED" ? URGENCY.indexOf("BUDGET") : URGENCY.indexOf(s));
+const BUDGET_TOKENS = 400;
+const LINE_MAX = 200;
+const FULL = { changed: 15, tried: Infinity, risks: 5, review: 5, error: Infinity, summary: 160 };
+/** A FAIL before any job exists (bad input, setup). */
+export const failBlock = (reason) => `FAIL reason: ${reason}`;
+/** A job block within `budget` tokens (chars/4), cutting in D9 order only while over it. Never cut: headline, question/options, conflict, reason, worktree, log. */
+export function renderJob(r, budget = BUDGET_TOKENS) {
+    if (r.status === "RUNNING")
+        return fit(`RUNNING ${r.job} step=${r.steps} turns=${r.usage.turns}`);
+    let cuts = FULL;
+    let text = layout(r, cuts);
+    const over = () => text.length / 4 > budget;
+    const cut = (c) => {
+        if (over())
+            text = layout(r, (cuts = { ...cuts, ...c }));
+    };
+    cut({ changed: 5 });
+    cut({ tried: 1 });
+    cut({ risks: 3 });
+    cut({ review: 3 });
+    for (let n = r.error?.length ?? 0; n > 12 && over();)
+        cut({ error: --n });
+    cut({ summary: 100 });
+    return text;
+}
+function layout(r, c) {
+    const sections = STATUS_SECTIONS[r.status];
+    const has = (s) => sections.includes(s);
+    const add = r.changed.reduce((n, x) => n + x.add, 0);
+    const del = r.changed.reduce((n, x) => n + x.del, 0);
+    const lines = [
+        [
+            r.status, r.job, `step=${r.steps}`, `files=${r.changed.length}`, `+${add}/-${del}`, r.tests && `tests=${r.tests}`,
+            `turns=${r.usage.turns}`, `cost=$${r.usage.costUsd.toFixed(3)}`,
+            r.selfFix && `fix=${r.selfFix}`, r.models.escalated && "esc=1",
+            r.models.final !== r.models.requested && `model=${r.models.final}`, r.redo && "redo=1", r.billing && `billing=${r.billing}`, r.repro && `repro=${r.repro}`, r.test && `test=${r.test}`,
+        ].filter(Boolean).join(" "),
+    ];
+    const keep = new Set(); // question/options lines are never elided
+    if (r.summary)
+        lines.push(`summary: ${clip(oneLine(r.summary), c.summary)}`);
+    // D5: a BLOCKED block counts its files in the headline but lists them only once the job settles
+    if (r.changed.length && r.status !== "BLOCKED") {
+        lines.push("changed:", ...r.changed.slice(0, c.changed).map((x) => `  ${x.status} ${x.path}${x.add ? ` +${x.add}` : ""}${x.del ? ` -${x.del}` : ""}`));
+        if (r.changed.length > c.changed)
+            lines.push(`  … +${r.changed.length - c.changed} more`);
+    }
+    if (r.risks.length)
+        lines.push("risks:", ...r.risks.slice(0, c.risks).map((x) => `  - ${clip(oneLine(x), 120)}`));
+    if (r.review.length)
+        lines.push(`review: ${r.review.slice(0, c.review).map((v) => `${v.path}:${v.start}-${v.end}`).join(", ")}`);
+    const asked = r.questions ?? (r.question ? [r.question] : []);
+    if (has("question"))
+        asked.forEach((question, n) => {
+            const q = [`question${asked.length > 1 ? ` ${n + 1}` : ""}: ${oneLine(question.text)}`];
+            if (question.options.length)
+                q.push("options:", ...question.options.slice(0, 4).map((o, i) => `  ${"abcd"[i]}) ${oneLine(o)}`));
+            q.forEach((l) => keep.add(l));
+            lines.push(...q);
+        });
+    if (has("conflict") && r.conflict?.length)
+        lines.push("conflict:", ...r.conflict.map((x) => `  ${oneLine(x)}`));
+    if (has("error") && r.error?.length) {
+        const e = r.error.slice(0, c.error);
+        if (e.length < r.error.length)
+            e[e.length - 1] = `  … +${r.error.length - e.length + 1} more lines (see log)`;
+        lines.push(`error: ${e[0]}`, ...e.slice(1));
+    }
+    if (has("found") && r.found)
+        lines.push(...wrap(`found: ${oneLine(r.found)}`));
+    if (has("tried") && r.tried?.length)
+        lines.push("tried:", ...r.tried.slice(-c.tried).map((x) => `  - ${oneLine(x)}`));
+    if (has("reason") && r.reason)
+        lines.push(`reason: ${oneLine(r.reason)}`);
+    if (has("missing") && r.missing.length)
+        lines.push("missing:", ...r.missing.map((x) => `  - ${oneLine(x)}`));
+    if (has("worktree") && r.worktree)
+        lines.push(`worktree: ${r.worktree}/`);
+    lines.push(`log: .cheapag/jobs/${r.job}/`);
+    return lines.map((l) => (keep.has(l) ? l.replaceAll("\t", "  ") : fit(l))).join("\n");
+}
+/** D7. A research CONSENT renders through `renderConsent`. */
+export function renderResearch(r) {
+    const lines = [
+        [
+            r.status, r.job, `files_read=${r.filesRead}`, `turns=${r.usage.turns}`, `cost=$${r.usage.costUsd.toFixed(3)}`,
+            r.models && r.models.final !== r.models.requested && `model=${r.models.final}`,
+        ].filter(Boolean).join(" "),
+    ];
+    // a scout brief (ticket 23.4): ranked files, the reproduction, dead ends, then the prose
+    if (r.refs.length)
+        lines.push(`files: ${r.refs.map((v) => `${v.path}:${v.start}${v.end !== v.start ? `-${v.end}` : ""}`).join(", ")}`);
+    if (r.repro)
+        lines.push(`repro: ${oneLine(r.repro)}`);
+    if (r.deadEnds)
+        lines.push(`dead ends: ${oneLine(r.deadEnds)}`);
+    // prose is word-wrapped, not elided like other long lines
+    if (r.answer.trim())
+        lines.push("notes:", ...r.answer.trim().split("\n").flatMap((l) => wrap(l.trimEnd())));
+    if (r.confidence)
+        lines.push(`confidence: ${r.confidence}`);
+    if (r.reason)
+        lines.push(`reason: ${oneLine(r.reason)}`);
+    const n = r.unlanded.length;
+    if (n)
+        lines.push(`note: ${n} job${n > 1 ? "s" : ""} not yet landed (${r.unlanded.join(", ")}); their changes are not visible to research`);
+    lines.push(`log: .cheapag/jobs/${r.job}/`);
+    return lines.map(fit).join("\n");
+}
+/**
+ * D6: header, notes, integration error, the integration fix job's block, then job blocks by urgency (RUNNING ones as
+ * adjacent single lines), then `next:`. The fix job is not a group: it counts in the cost only.
+ */
+export function renderBatch(b, jobs, fix) {
+    const sorted = [...jobs].sort((x, y) => rank(x.status) - rank(y.status));
+    const counts = URGENCY.map((s) => [s, sorted.filter((j) => j.status === s).length]).filter(([, n]) => n);
+    const head = [
+        [
+            `BATCH ${b.batch} groups=${b.groups.length}`, ...counts.map(([s, n]) => `${s}=${n}`),
+            `landed=${jobs.filter((j) => j.landed).length}`, `integration=${b.integration}`,
+            `cost=$${[...jobs, ...(fix ? [fix] : [])].reduce((n, j) => n + j.usage.costUsd, 0).toFixed(3)}`,
+        ].join(" "),
+    ];
+    if (b.notes.length)
+        head.push(`note: ${b.notes.join("; ")}`);
+    if (b.integrationError?.length)
+        head.push(`error: ${b.integrationError[0]}`, ...b.integrationError.slice(1));
+    const chunks = fix ? [renderJob(fix)] : [];
+    sorted.forEach((j, i) => {
+        if (j.status === "RUNNING" && sorted[i - 1]?.status === "RUNNING")
+            chunks[chunks.length - 1] += `\n${renderJob(j)}`;
+        else
+            chunks.push(renderJob(j));
+    });
+    const blocked = sorted.find((j) => j.status === "BLOCKED");
+    const next = [
+        blocked && `reply(job="${blocked.job}", ...)`,
+        (b.integration === "running" || sorted.some((j) => j.status === "BLOCKED" || j.status === "RUNNING")) && `jobs(action="wait", job="${b.batch}")`,
+    ].filter(Boolean).join(" then ");
+    return [head.map(fit).join("\n"), chunks.join("\n\n"), next && fit(`next: ${next}`)].filter(Boolean).join("\n");
+}
+/** D5 CONSENT: no job is created. */
+export const renderConsent = (c) => [`CONSENT repo=${c.repo}`, `send: ${c.send}`, `retention: ${c.retention}`, `approve: ${c.approve}`].map(fit).join("\n");
+const oneLine = (s) => s.trim().replace(/\s*\n\s*/g, " ");
+const clip = (s, max) => (s.length > max ? `${s.slice(0, max - 1)}…` : s);
+/** A line broken at spaces into lines of at most 200 chars (a longer word is left to `fit`). */
+function wrap(line) {
+    const out = [""];
+    for (const word of line.replaceAll("\t", "  ").split(" ")) {
+        const last = out[out.length - 1];
+        if (last && last.length + 1 + word.length > LINE_MAX)
+            out.push(word);
+        else
+            out[out.length - 1] = last ? `${last} ${word}` : word;
+    }
+    return out;
+}
+/** D9 line rules: no tabs (2 spaces), at most 200 chars with the middle elided. */
+function fit(line) {
+    const l = line.replaceAll("\t", "  ");
+    if (l.length <= LINE_MAX)
+        return l;
+    const half = (LINE_MAX - 1) / 2;
+    return `${l.slice(0, Math.ceil(half))}…${l.slice(l.length - Math.floor(half))}`;
+}

package/dist/research.js

@@ -0,0 +1,264 @@
+import { randomBytes } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+import { loadConfig } from "./config.js";
+import { consentGate } from "./consent.js";
+import { redact } from "./credentials.js";
+import { records } from "./jobs.js";
+import { holdOpencode } from "./opencode.js";
+import { projectScripts, researchRuleset } from "./permissions.js";
+import { normalisePath } from "./platform.js";
+import { failBlock, renderResearch } from "./report.js";
+import { chain, modelName, recordSpend, runRouted } from "./routing.js";
+import { openSession } from "./worker.js";
+import { createWorktree, projectRoot, removeWorktree } from "./workspace.js";
+/**
+ * Research: one question about the codebase, answered by a worker that reads, searches and runs test commands but
+ * never edits (agent `cheapag-research`, ruleset `researchRuleset`), in a throwaway worktree of the developer's current
+ * state (uncommitted work included) so a command can't touch their tree. It runs alongside jobs. The worker reports a
+ * scout brief (ticket 23.4) in a fenced `cheapag-research` block in its final text; a claimed reproduction is checked
+ * against the commands it actually ran.
+ */
+export const RESEARCH_AGENT = "cheapag-research";
+export const MAX_WORDS = 600;
+const DEFAULT_WORDS = 200;
+/** At most this many refs: the refs line must stay within the 200-char line rule. */
+const MAX_REFS = 5;
+export async function research(input, ctx) {
+    const root = projectRoot(process.cwd());
+    // first: an unapproved repo gets CONSENT before any record, OpenCode boot or provider call
+    const gate = consentGate(root, ctx.provider.provider);
+    if ("block" in gate)
+        return gate.block;
+    const scope = [];
+    for (const path of (input.paths ?? "").split(",").map((p) => p.trim()).filter(Boolean)) {
+        const rel = relative(root, join(root, path));
+        if (isAbsolute(path) || rel === ".." || rel.startsWith("../"))
+            return failBlock(`path ${path} must be inside the repository, relative to its root`);
+        if (!existsSync(join(root, path)))
+            return failBlock(`path ${path} not found`);
+        if (rel)
+            scope.push(normalisePath(rel)); // "." is the whole repo: no scope
+    }
+    let config;
+    try {
+        config = loadConfig(root);
+    }
+    catch (err) {
+        return failBlock(err.message);
+    }
+    const { limits } = config;
+    const maxWords = Math.min(input.max_words ?? DEFAULT_WORDS, MAX_WORDS);
+    const opencode = await ctx.opencode(gate.route);
+    const release = holdOpencode();
+    const { id, dir } = newResearch(root);
+    const write = (name, value) => writeFileSync(join(dir, name), redact(typeof value === "string" ? value : JSON.stringify(value, null, 2) + "\n"));
+    // the research model, then its fallbacks, each only if the repo's allowlist kept it (src/consent.ts)
+    const models = chain(gate.route.research ?? gate.route.implement, gate.route.researchFallbacks);
+    const startedAt = new Date();
+    write("request.json", { ...input, scope, maxWords, models: [models.first, ...models.rest].map(modelName), startedAt });
+    const prompt = [
+        `Question: ${input.question}`,
+        scope.length && `Scope: look only under ${scope.join(", ")}; cite only files there.`,
+        REPRO_RULE,
+        `Answer in at most ${maxWords} words.`,
+        // repeated here because real models skipped the agent prompt's format (seen live): without it a right answer is UNSURE
+        BRIEF_FORMAT,
+    ].filter(Boolean).join("\n");
+    const files = new Set();
+    const ran = []; // the commands the worker actually ran: a claimed reproduction must be one of them
+    const spent = { turns: 0, costUsd: 0 };
+    let text = "";
+    let error;
+    let budget;
+    // set from event callbacks: keep TS from narrowing it to undefined
+    let stopped = undefined;
+    let worktree;
+    try {
+        worktree = createWorktree(root, id, config.link_dirs);
+        const { scripts, exact } = projectScripts(worktree.path);
+        const permission = researchRuleset({ scripts, exact: [...exact, ...(config.test_cmd ? [config.test_cmd] : [])], allowCommands: config.allow_commands });
+        const halt = new AbortController();
+        const stop = (why) => {
+            stopped ??= why;
+            halt.abort();
+        };
+        const timer = setTimeout(() => stop({ status: "FAIL", reason: `minute cap (${limits.max_minutes} min) reached` }), limits.max_minutes * 60_000);
+        const session = await openSession({
+            opencode, directory: worktree.path, model: models.first, agent: RESEARCH_AGENT, permission, signal: halt.signal,
+            onEvent: (event, turns) => {
+                appendFileSync(join(dir, "events.jsonl"), redact(JSON.stringify(event)) + "\n");
+                if (event.type === "message.part.updated" && event.properties.part.type === "tool") {
+                    const { tool, state } = event.properties.part;
+                    if (state.status === "completed" && tool === "read")
+                        files.add(String(state.input.filePath));
+                    if (state.status === "completed" && tool === "bash")
+                        ran.push(String(state.input.command ?? ""));
+                    if (state.status === "completed" || state.status === "error") {
+                        ctx.progress(turns, `turn ${turns}: ${tool}`);
+                        if (turns >= limits.max_turns)
+                            stop({ status: "FAIL", reason: `turn cap (${limits.max_turns}) reached` });
+                    }
+                }
+                if (event.type === "message.updated" && session.totals().usage.costUsd >= limits.max_cost_usd) {
+                    stop({ status: "BUDGET", reason: `job cap ($${limits.max_cost_usd.toFixed(2)}) reached` });
+                }
+            },
+        });
+        try {
+            // a provider limit continues the same session on the next fallback (src/routing.ts), never waiting it out
+            ({ text, error, budget } = await runRouted(session, prompt, models, ctx.provider.provider));
+        }
+        finally {
+            clearTimeout(timer);
+            const totals = session.totals();
+            spent.turns = totals.turns;
+            spent.costUsd = totals.usage.costUsd;
+            try {
+                recordSpend(totals.spend); // research draws on the same Go windows as jobs
+            }
+            catch {
+                // the ledger only steers later escalations: never fail an answer over it
+            }
+        }
+    }
+    catch (err) {
+        error = err.message;
+    }
+    finally {
+        release(); // the session is done: a config change may reboot OpenCode now
+        if (worktree)
+            removeWorktree(root, worktree);
+    }
+    const answer = stopped ? { status: stopped.status, answer: "", refs: [] }
+        : budget ? { status: "BUDGET", answer: "", refs: [] }
+            : error ? { status: "FAIL", answer: "", refs: [] }
+                : verifyRepro(parseAnswer(text, root, scope, maxWords), ran) ?? { status: "FAIL", answer: "", refs: [] };
+    const reason = stopped?.reason
+        ?? budget
+        ?? (error ? `worker error: ${error}` : answer.status === "FAIL" ? "the research worker gave no answer" : undefined);
+    const final = models.current;
+    const record = {
+        format: "cheapag/1", job: id, kind: "research", provider: ctx.provider.provider, question: input.question, scope,
+        ...answer, reason, filesRead: files.size, unlanded: unlandedJobs(root),
+        models: { requested: modelName(models.first), final: modelName(final) },
+        usage: spent,
+        timing: { startedAt, endedAt: new Date(), ms: Date.now() - startedAt.getTime() },
+    };
+    const block = renderResearch(record);
+    // research.json, not result.json: `jobs list` reads only job records
+    write("research.json", record);
+    write("result.txt", block + "\n");
+    return block;
+}
+/** Research verifies before it claims (ticket 23.4: unverified handoffs inject false confidence). */
+export const REPRO_RULE = "If the question is about a failure or wrong behaviour, reproduce it: run the relevant test or command and report exactly what it showed. Never claim a reproduction you did not run.";
+export const BRIEF_FORMAT = "End your reply with exactly one fenced ```cheapag-research block: status (answer or unsure), confidence (high, medium or low), files (path:start-end, most relevant first, comma-separated), repro (`command` → what it showed, or not attempted), dead ends (what you ruled out, or none), then notes: and your prose.";
+/**
+ * A claimed reproduction stands only if its `command` is one the worker ran; otherwise it is marked unverified and the
+ * confidence drops to low, so Claude doesn't build on a guess.
+ */
+export function verifyRepro(answer, ran) {
+    const repro = answer?.repro?.trim();
+    if (!answer || !repro || /^not attempted|^none$/i.test(repro))
+        return answer && { ...answer, repro: repro || undefined };
+    const norm = (c) => c.replace(/\s+/g, " ").trim();
+    const claimed = norm(repro.match(/`([^`]+)`/)?.[1] ?? "");
+    const verified = !!claimed && ran.some((c) => norm(c).includes(claimed) || claimed.includes(norm(c)));
+    return verified ? { ...answer, repro } : { ...answer, repro: `unverified (not run): ${repro}`, confidence: "low" };
+}
+/**
+ * Jobs whose changes research cannot see (D7 note): not landed, and either still in flight (RUNNING or BLOCKED: their
+ * changes may land later) or holding changes in a worktree that still exists (PARTIAL, FAIL, CONFLICT, TIMEOUT,
+ * BUDGET, CANCELLED with edits; `land apply` could still land them). A discarded or cleaned-up job, or one that changed
+ * nothing, has nothing to miss. Oldest first.
+ */
+export function unlandedJobs(root) {
+    return records(root)
+        .filter((r) => !r.landed && (r.status === "RUNNING" || r.status === "BLOCKED" || (!!r.worktree && !!r.changed?.length && existsSync(join(root, r.worktree)))))
+        .sort((a, b) => String(a.timing?.startedAt ?? "").localeCompare(String(b.timing?.startedAt ?? "")))
+        .map((r) => r.job);
+}
+/**
+ * The worker's last fenced `cheapag-research` block, parsed leniently. Without one, its final text is the answer,
+ * UNSURE with low confidence (the worker never rated it). Nothing at all → undefined.
+ */
+export function parseAnswer(text, root, scope, maxWords) {
+    const block = [...text.matchAll(/```cheapag-research[^\n]*\n([\s\S]*?)```/g)].at(-1)?.[1];
+    if (!block)
+        return text.trim() ? { status: "UNSURE", answer: capWords(text.trim(), maxWords), refs: refs(text, root, scope), confidence: "low" } : undefined;
+    const fields = {};
+    let key;
+    for (const line of block.split("\n")) {
+        const kv = line.match(/^\s*(status|confidence|refs|files|repro|dead[ _]ends|answer|notes):\s*(.*)$/i);
+        // files/notes are the brief's names (ticket 23.4); refs/answer still read
+        if (kv)
+            fields[(key = { files: "refs", notes: "answer", "dead ends": "deadEnds", dead_ends: "deadEnds" }[kv[1].toLowerCase()] ?? kv[1].toLowerCase())] = kv[2];
+        else if (key === "answer")
+            fields.answer += `\n${line}`; // the answer is prose: it may span lines
+    }
+    const answer = (fields.answer ?? "").trim();
+    if (!answer)
+        return undefined;
+    const listed = refs(fields.refs ?? "", root, scope);
+    const confidence = fields.confidence?.trim().toLowerCase().match(/^(high|medium|low)/)?.[1];
+    return {
+        status: /^unsure/i.test(fields.status?.trim() ?? "") ? "UNSURE" : "ANSWER",
+        answer: capWords(answer, maxWords),
+        // refs from the refs line; failing that, any cited in the prose
+        refs: listed.length ? listed : refs(answer, root, scope),
+        confidence: confidence ?? "low",
+        repro: fields.repro?.trim() || undefined,
+        deadEnds: fields.deadEnds?.trim() && !/^none\.?$/i.test(fields.deadEnds.trim()) ? fields.deadEnds.trim() : undefined,
+    };
+}
+/**
+ * Validated `path:line(-line)` refs from free text, at most 5: the file exists in the main checkout, inside the repo
+ * (and the scope, when there is one), and has those lines. Absolute paths inside the repo are made relative.
+ */
+function refs(text, root, scope) {
+    const out = [];
+    for (const [, path, from, to] of text.matchAll(/([\w./@-]+):(\d+)(?:-(\d+))?/g)) {
+        const abs = isAbsolute(path) ? path : join(root, path);
+        const rel = normalisePath(relative(root, abs));
+        const start = Number(from);
+        const end = Number(to ?? from);
+        if (!rel || rel === ".." || rel.startsWith("../") || isAbsolute(rel) || start < 1 || end < start)
+            continue;
+        if (scope.length && !scope.some((s) => rel === s || rel.startsWith(`${s}/`)))
+            continue;
+        if (out.some((r) => r.path === rel && r.start === start && r.end === end))
+            continue;
+        try {
+            if (!statSync(abs).isFile())
+                continue;
+            const content = readFileSync(abs, "utf8");
+            const lines = content.split("\n").length - (content.endsWith("\n") ? 1 : 0);
+            if (end > lines)
+                continue;
+        }
+        catch {
+            continue; // no such file
+        }
+        out.push({ path: rel, start, end });
+        if (out.length === MAX_REFS)
+            break;
+    }
+    return out;
+}
+/** The text cut after `max` words, line breaks kept. */
+function capWords(text, max) {
+    const words = [...text.matchAll(/\S+/g)];
+    return words.length <= max ? text : `${text.slice(0, words[max].index).trimEnd()} …`;
+}
+/** A fresh `r` + 4 base36 id whose folder (beside the job folders, D7 `log:`) does not exist yet. */
+function newResearch(root) {
+    for (;;) {
+        const id = `r${randomBytes(4).readUInt32BE().toString(36).slice(-4).padStart(4, "0")}`;
+        const dir = join(root, ".cheapag", "jobs", id);
+        if (existsSync(dir))
+            continue;
+        mkdirSync(dir, { recursive: true });
+        return { id, dir };
+    }
+}