cheap-agent 0.0.0-stage → 1.0.0

package/dist/verify.js

@@ -0,0 +1,121 @@
+import { spawn } from "node:child_process";
+import { killProcessGroup } from "./platform.js";
+// a backstop per command; the job's minute cap (its `signal`) bounds the whole job
+const COMMAND_TIMEOUT_MS = 5 * 60_000;
+const OUTPUT_LIMIT = 1024 * 1024;
+/** The backticked fragments of each step's `done-when`, in order; else the configured test_cmd; else none. */
+export function verifyCommands(doneWhen, testCmd) {
+    const backticked = doneWhen.flatMap((text) => [...text.matchAll(/`([^`]+)`/g)].map((m) => m[1].trim())).filter(Boolean);
+    return backticked.length ? backticked : testCmd ? [testCmd] : [];
+}
+/**
+ * Runs the commands in order in `cwd`, stopping at the first failure; `onStart` hears each command as it begins.
+ * Aborting `signal` kills the running command's process group (cap or cancel) and fails it.
+ */
+export async function runVerify(cwd, cmds, onStart, signal) {
+    const runs = [];
+    for (const cmd of cmds) {
+        if (signal?.aborted)
+            break;
+        onStart(cmd);
+        const run = await runOne(cwd, cmd, signal);
+        runs.push(run);
+        if (!run.ok)
+            break;
+    }
+    return runs;
+}
+function runOne(cwd, cmd, signal) {
+    const started = Date.now();
+    return new Promise((resolve) => {
+        // its own process group, so everything it spawned can be stopped with it
+        const child = spawn("sh", ["-c", cmd], { cwd, detached: true, stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, CI: "1", FORCE_COLOR: "0" } });
+        const killGroup = () => killProcessGroup(child.pid, "SIGKILL");
+        let output = "";
+        let code = null;
+        // keep the end: failures and summaries come last
+        const collect = (chunk) => (output = (output + chunk).slice(-OUTPUT_LIMIT));
+        child.stdout.setEncoding("utf8").on("data", collect);
+        child.stderr.setEncoding("utf8").on("data", collect);
+        const timer = setTimeout(() => {
+            output += `\n(cheapag: stopped after ${COMMAND_TIMEOUT_MS / 60_000} min)`;
+            killGroup();
+        }, COMMAND_TIMEOUT_MS);
+        const halt = () => {
+            output += "\n(cheapag: stopped, job cap or cancel)";
+            killGroup();
+        };
+        signal?.addEventListener("abort", halt, { once: true });
+        // a backgrounded child (`server &`) would hold the pipes open: when the shell exits, stop its whole group
+        child.on("exit", (exitCode) => {
+            code = exitCode;
+            killGroup();
+        });
+        child.on("close", () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", halt);
+            resolve({ cmd, ok: code === 0 && !signal?.aborted, ms: Date.now() - started, output });
+        });
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", halt);
+            resolve({ cmd, ok: false, ms: Date.now() - started, output: err.message });
+        });
+    });
+}
+const MARKER = /✗|✘|×|\bFAIL\b|Error:|error TS\d+|AssertionError|Traceback|panicked|^E\s{2,}/;
+const DETAIL = /expected|received|\bgot\b|\bwant\b|^\s*[-+] /i;
+const FRAME = /^\s*(at |File ")|\.(ts|tsx|js|mjs|cjs|py|go|rs):\d+/;
+// pass lines and progress only: a line that also carries a failure marker is never noise
+const NOISE = /^\s*(✓|√|PASS\b|ok\b)|^\s*(Tests?|Test Files|Suites?)\b.*\bpassed\b|^\s*[.·•⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏]+$/;
+const MAX_FAILURES = 3;
+const MAX_LINES = 25;
+/**
+ * Spec D9: the failing command, then up to 3 distinct failures (similar ones counted ×N), each with its message,
+ * expected/received lines and first in-repo frame; at most 25 lines of 200 chars, with `root` made repo-relative.
+ * Falls back to the last lines when no failure marker is found.
+ */
+export function errorTail(run, root) {
+    const lines = run.output
+        .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
+        .split(`${root}/`).join("")
+        .split(/\r?\n/)
+        .map((l) => l.replace(/\t/g, "  ").trimEnd())
+        .filter((l) => l.trim() && (MARKER.test(l) || !NOISE.test(l)));
+    const failures = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (!MARKER.test(lines[i]))
+            continue;
+        const block = [lines[i].trim()];
+        let frame = false;
+        let j = i + 1;
+        // a runner's headline ("FAIL a > b") and its error ("AssertionError: …") on adjacent lines are one failure
+        if (j < lines.length && MARKER.test(lines[j]) && block[0].length + lines[j].length < 400 && /^\s*(FAIL|✗|×)/.test(lines[i]) && /Error/.test(lines[j])) {
+            block.push(`  ${lines[j].trim()}`);
+            j++;
+        }
+        for (; j < lines.length && j <= i + 12 && !MARKER.test(lines[j]); j++) {
+            if (DETAIL.test(lines[j]) && block.length < 5)
+                block.push(`  ${lines[j].trim()}`);
+            else if (!frame && FRAME.test(lines[j]) && !/node_modules|node:internal|site-packages/.test(lines[j])) {
+                block.push(`  ${lines[j].trim()}`);
+                frame = true;
+            }
+        }
+        i = Math.max(i, j - 1);
+        const key = block[0].replace(/\d+/g, "#");
+        const same = failures.find((f) => f.key === key);
+        if (same)
+            same.count++;
+        else
+            failures.push({ key, lines: block, count: 1 });
+    }
+    const body = failures.length
+        ? failures.slice(0, MAX_FAILURES).flatMap((f) => [f.count > 1 ? `${f.lines[0]} (×${f.count})` : f.lines[0], ...f.lines.slice(1)])
+        : lines.slice(-(MAX_LINES - 1));
+    return [`\`${run.cmd}\``, ...body.slice(0, MAX_LINES - 1).map((l) => clip(`  ${l}`))];
+}
+/** Whether two tails show the same failure, ignoring numbers (timings, counts, ports). */
+export const sameFailure = (a, b) => a.join("\n").replace(/\d+/g, "#") === b.join("\n").replace(/\d+/g, "#");
+/** At most 200 chars, eliding the middle. */
+const clip = (line) => (line.length <= 200 ? line : `${line.slice(0, 120)} … ${line.slice(-77)}`);

package/dist/worker.js

@@ -0,0 +1,237 @@
+import { createOpencodeClient } from "@opencode-ai/sdk/v2";
+import { rejectionMessage } from "./permissions.js";
+import { modelName } from "./routing.js";
+/** Worker: one OpenCode session for one job, reduced to what the job layer needs. */
+export const WORKER_AGENT = "cheapag-worker";
+/** How long an aborted prompt may take to go idle before its run is ended anyway. */
+const ABORT_GRACE_MS = 10_000;
+/**
+ * Opens one worker session. `run` prompts it (optionally on another model, e.g. escalation) and resolves when the
+ * session goes idle; self-fixes and escalation are further `run`s of the same session.
+ */
+export async function openSession(opts) {
+    const { opencode, directory } = opts;
+    const client = createOpencodeClient({
+        baseUrl: opencode.url,
+        directory,
+        headers: { authorization: `Basic ${Buffer.from(`opencode:${opencode.password}`).toString("base64")}` },
+    });
+    const created = await client.session.create({
+        directory, agent: opts.agent ?? WORKER_AGENT, model: { providerID: opts.model.providerID, id: opts.model.id }, ...(opts.permission && { permission: opts.permission }),
+    });
+    if (!created.data)
+        throw new Error(`could not create a worker session: ${JSON.stringify(created.error)}`);
+    const sessionID = created.data.id;
+    const calls = new Set();
+    const messages = new Map(); // assistant message id → its model and latest running totals
+    const rejections = [];
+    /**
+     * `interrupt` ends this prompt only (the session stays usable, e.g. to hand it to another model); `opts.signal` ends the
+     * session. `afterStop` runs one more prompt on a stopped session (the findings note), bounded by `interrupt` alone.
+     */
+    async function run(prompt, model, interrupt, afterStop = false) {
+        const signal = afterStop ? undefined : opts.signal;
+        if (signal?.aborted)
+            return { text: "", error: "aborted" };
+        const abort = new AbortController();
+        let backstop;
+        const stop = () => {
+            void client.session.abort({ sessionID, directory }).catch(() => { });
+            // live, an abort ends in session.idle; if it never comes, drop the stream so the run cannot hang
+            backstop = setTimeout(() => abort.abort(), ABORT_GRACE_MS);
+        };
+        // the SDK's stream only connects when first read: wait for server.connected before prompting, or early events are lost
+        const { stream } = await client.event.subscribe({ directory }, { signal: abort.signal });
+        await stream.next();
+        try {
+            const texts = new Map(); // text part id → latest text
+            let idle = false;
+            let finish;
+            let error;
+            let httpStatus;
+            let limit;
+            const prompted = await client.session.promptAsync({
+                sessionID, directory, parts: [{ type: "text", text: prompt }],
+                ...(model && { model: { providerID: model.providerID, modelID: model.id } }),
+            });
+            if (prompted.error)
+                throw new Error(`could not prompt the worker: ${JSON.stringify(prompted.error)}`);
+            // after the prompt, so an abort can never race ahead of it
+            signal?.addEventListener("abort", stop, { once: true });
+            if (signal?.aborted)
+                stop();
+            interrupt?.addEventListener("abort", stop, { once: true });
+            if (interrupt?.aborted)
+                stop();
+            for await (const raw of stream) {
+                const event = raw;
+                const props = event.properties;
+                if (props.sessionID !== sessionID)
+                    continue;
+                if (event.type === "message.part.updated") {
+                    const part = event.properties.part;
+                    if (part.type === "tool" && (part.state.status === "completed" || part.state.status === "error")) {
+                        // shortcut: OpenCode 1.19's wording for a call its ruleset denied; update if a new pin rewords it
+                        if (!calls.has(part.callID) && part.state.status === "error" && part.state.error.startsWith("The user has specified a rule which prevents")) {
+                            rejections.push({ kind: "denied", permission: part.tool, what: describeCall(part.state.input) });
+                        }
+                        calls.add(part.callID);
+                        if (part.tool === "finish" && part.state.status === "completed")
+                            finish = asReport(part.state.input);
+                    }
+                    if (part.type === "text")
+                        texts.set(part.id, { messageID: part.messageID, text: part.text });
+                }
+                else if (event.type === "message.updated" && event.properties.info.role === "assistant") {
+                    const { id, cost, tokens, error: failed, providerID, modelID } = event.properties.info;
+                    // seen live on 1.19.0: some failures (e.g. abort) arrive only on the assistant message, with no session.error
+                    if (failed) {
+                        error ??= describe(failed);
+                        httpStatus ??= statusOf(failed);
+                    }
+                    messages.set(id, {
+                        model: `${providerID}/${modelID}`,
+                        inputTokens: tokens.input, outputTokens: tokens.output, reasoningTokens: tokens.reasoning,
+                        cacheRead: tokens.cache.read, cacheWrite: tokens.cache.write, costUsd: cost,
+                    });
+                }
+                else if (event.type === "permission.asked") {
+                    // an unanswered ask blocks forever in server mode: reject every one, with a reason the worker sees
+                    const what = event.properties.patterns.join(" ") || event.properties.permission;
+                    rejections.push({ kind: "asked", permission: event.properties.permission, what });
+                    const replied = await client.permission
+                        .reply({ requestID: event.properties.id, directory, reply: "reject", message: rejectionMessage(what) })
+                        .catch((err) => ({ error: err.message }));
+                    // a reject that did not go through would leave the session blocked: end this run as a worker error instead
+                    if (replied.error) {
+                        error ??= `could not reject a ${event.properties.permission} permission request: ${JSON.stringify(replied.error)}`;
+                        break;
+                    }
+                }
+                else if (event.type === "question.asked") {
+                    opts.onEvent(event, calls.size); // logged now: the answer may be a long way off
+                    const questions = event.properties.questions.map((q) => ({ question: q.question, options: q.options.map((o) => o.label) }));
+                    const requestID = event.properties.id;
+                    // a stop (cap or cancel) while waiting ends the wait: the question is rejected and the session aborted
+                    const stopped = new Promise((resolve) => (signal?.aborted ? resolve(undefined) : signal?.addEventListener("abort", () => resolve(undefined), { once: true })));
+                    // a question asked after a stop is never put to Claude: the job is ending, not blocked
+                    const answers = opts.onQuestion && questions.length && !signal?.aborted ? await Promise.race([opts.onQuestion(questions), stopped]) : undefined;
+                    // nowhere to put the question (a parallel group until early return exists, or the login check): it is rejected, and said so
+                    if (!opts.onQuestion && questions.length)
+                        rejections.push({ kind: "asked", permission: "question", what: questions.map((q) => q.question).join(" / ") });
+                    const replied = await (answers === undefined
+                        ? client.question.reject({ requestID, directory })
+                        : client.question.reply({ requestID, directory, answers: answers.map((a) => [a]) })).catch((err) => ({ error: err.message }));
+                    // an answer that did not go through would leave the session paused forever: end this run as a worker error instead
+                    if (replied.error) {
+                        error ??= `could not answer the worker's question: ${JSON.stringify(replied.error)}`;
+                        break;
+                    }
+                    continue;
+                }
+                else if (event.type === "session.error") {
+                    error = describe(event.properties.error);
+                    httpStatus = statusOf(event.properties.error);
+                }
+                else if (event.type === "session.status" && event.properties.status.type === "retry" && !limit && isLimit(event.properties.status, (model ?? opts.model).providerID)) {
+                    // a provider limit or rate limit: OpenCode would retry, honouring retry-after, possibly for hours. Stop now, so the
+                    // job can fall back; this aborts the session directly, not through the job's stop signal (which means a cap)
+                    const { action, message, next } = event.properties.status;
+                    limit = { model: modelName(model ?? opts.model), reason: action?.reason, message: action?.message ?? message, next };
+                    stop();
+                }
+                opts.onEvent(event, calls.size);
+                if (event.type === "session.idle") {
+                    idle = true;
+                    break;
+                }
+            }
+            if (!idle)
+                error ??= "worker event stream ended before the session went idle";
+            // the fallback block is read from this prompt's last message only, so a stale one from earlier cannot win
+            const last = [...texts.values()].at(-1)?.messageID;
+            const text = [...texts.values()].filter((t) => t.messageID === last).map((t) => t.text).join("\n");
+            // an interrupted prompt ends on OpenCode's abort error; that is the hand-over, not a worker failure
+            if (interrupt?.aborted && !signal?.aborted)
+                return { finish, text, interrupted: true };
+            return { finish, text, error, ...(httpStatus && { httpStatus }), ...(limit && { limit }) };
+        }
+        finally {
+            signal?.removeEventListener("abort", stop);
+            interrupt?.removeEventListener("abort", stop);
+            clearTimeout(backstop);
+            abort.abort();
+        }
+    }
+    function totals() {
+        const usage = { inputTokens: 0, outputTokens: 0, reasoningTokens: 0, cacheRead: 0, cacheWrite: 0, costUsd: 0 };
+        const spend = {};
+        for (const m of messages.values()) {
+            for (const key of Object.keys(usage))
+                usage[key] += m[key];
+            spend[m.model] = (spend[m.model] ?? 0) + m.costUsd;
+        }
+        return { sessionID, turns: calls.size, usage, rejections: [...rejections], spend };
+    }
+    return { sessionID, run, totals };
+}
+/** One prompt in a fresh session (the login live check). */
+export async function runSession(opts) {
+    const session = await openSession(opts);
+    const result = await session.run(opts.prompt);
+    return { ...session.totals(), ...result };
+}
+/** OpenCode validates the tool's args, but the record must not trust a malformed one either. */
+function asReport(input) {
+    const list = (v) => (Array.isArray(v) ? v.map(String) : typeof v === "string" && v ? [v] : []);
+    return { summary: String(input.summary ?? ""), risks: list(input.risks), review: list(input.review), missing: list(input.missing), ...(typeof input.repro === "string" && input.repro.trim() && { repro: input.repro.trim() }), ...(typeof input.disagree === "string" && input.disagree.trim() && { disagree: input.disagree.trim() }) };
+}
+/**
+ * A retry that means a limit, not a blip: a Go account or free-tier limit, any OpenRouter retry (its 429s), or a retry
+ * scheduled more than a minute out. A transient 5xx retry on Go or DeepSeek is left to OpenCode's own quick retries.
+ */
+function isLimit(status, providerID) {
+    return ["account_rate_limit", "free_tier_limit"].includes(status.action?.reason ?? "") || providerID === "openrouter" || status.next - Date.now() > 60_000;
+}
+/** The command or path a tool call targeted, for rejection records. */
+function describeCall(input) {
+    return String(input.command ?? input.filePath ?? input.url ?? input.pattern ?? JSON.stringify(input)).slice(0, 200);
+}
+function describe(err) {
+    const e = err;
+    return e?.data?.message ?? e?.name ?? "unknown worker error";
+}
+/** The HTTP status of a provider error (APIError), e.g. OpenRouter's 402 for insufficient credits. */
+const statusOf = (err) => err?.data?.statusCode;
+const NO_REPORT = { summary: "(worker gave no summary)", risks: ["worker did not report; review diff"], review: [], missing: [] };
+/** The finish tool's report; else the last fenced `cheapag-result` block, parsed leniently; else a placeholder. */
+export function finishReport(result) {
+    if (result.finish)
+        return result.finish;
+    const block = [...result.text.matchAll(/```cheapag-result\s*\n([\s\S]*?)```/g)].at(-1)?.[1];
+    if (!block)
+        return NO_REPORT;
+    const report = { summary: "", risks: [], review: [], missing: [] };
+    let list;
+    for (const line of block.split("\n")) {
+        const kv = line.match(/^(summary|risks|review|missing|repro|disagree):\s*(.*)$/);
+        if (kv) {
+            const [, key, value] = kv;
+            if (key === "summary" || key === "repro" || key === "disagree") {
+                if (value.trim())
+                    report[key] = value.trim();
+                list = undefined;
+            }
+            else {
+                list = key;
+                // inline values: "review: a.ts:1-2, b.ts:3-4"
+                if (value.trim())
+                    report[list].push(...value.split(",").map((v) => v.trim()).filter(Boolean));
+            }
+        }
+        else if (list && /^\s*-\s+/.test(line)) {
+            report[list].push(line.replace(/^\s*-\s+/, "").trim());
+        }
+    }
+    return { ...report, summary: report.summary || NO_REPORT.summary };
+}

package/dist/workspace.js

@@ -0,0 +1,278 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { copyFileSync, cpSync, existsSync, linkSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { isAlive, link, normalisePath, removeLink } from "./platform.js";
+export function git(cwd, args, env) {
+    return execFileSync("git", args, { cwd, stdio: "pipe", env: env && { ...process.env, ...env }, maxBuffer: 256 * 1024 * 1024 }).toString();
+}
+/** The repository root containing `cwd`; throws when it is not a git repository. */
+export function projectRoot(cwd) {
+    try {
+        return git(cwd, ["rev-parse", "--show-toplevel"]).trim();
+    }
+    catch {
+        throw new Error(`${cwd} is not inside a git repository`);
+    }
+}
+/**
+ * A detached worktree under `.cheapag/worktrees/<job>` holding the developer's current state (ADR-0003):
+ * HEAD, plus uncommitted tracked changes (a `git stash create` snapshot, which leaves the checkout and the stash list
+ * alone), plus copies of untracked non-ignored files such as a freshly written plan. Dependency directories from
+ * `linkDirs` are linked in from the main checkout. Nothing in the main checkout is modified.
+ */
+export function createWorktree(root, job, linkDirs) {
+    const head = git(root, ["rev-parse", "HEAD"]).trim();
+    const stash = git(root, ["stash", "create"]).trim() || null;
+    const path = join(root, ".cheapag", "worktrees", job);
+    git(root, ["worktree", "add", "--detach", path, head]);
+    const links = [];
+    try {
+        if (stash)
+            git(path, ["stash", "apply", "--quiet", stash]);
+        // untracked dependency dirs are linked below, never copied
+        const untracked = git(root, ["ls-files", "--others", "--exclude-standard", "-z", "--", ".", ...outside(linkDirs)]).split("\0").filter(Boolean);
+        // an entry ending in "/" is an untracked nested repository: not part of this repo, so not carried over
+        // (git would refuse to index it, or record it as a gitlink that would then land)
+        for (const file of untracked.filter((f) => !f.endsWith("/"))) {
+            mkdirSync(dirname(join(path, file)), { recursive: true });
+            cpSync(join(root, file), join(path, file), { verbatimSymlinks: true });
+        }
+        for (const dir of linkDirs) {
+            const source = join(root, dir);
+            const target = join(path, dir);
+            // tracked dependency dirs (e.g. a committed vendor/) are already in the worktree, and stay part of the diff
+            if (!isDirectory(source) || existsSync(target))
+                continue;
+            mkdirSync(dirname(target), { recursive: true });
+            link(source, target);
+            links.push(target);
+        }
+    }
+    catch (err) {
+        discard(root, path, links);
+        throw err;
+    }
+    const linked = links.map((l) => normalisePath(relative(path, l)));
+    // the carried-over state as a tree object: the job's baseline, without committing anything
+    git(path, ["add", "-A", "--", ".", ...outside(linked)]);
+    const base = git(path, ["write-tree"]).trim();
+    return { path, head, stash, base, links, linked };
+}
+function discard(root, path, links) {
+    for (const l of links)
+        removeLink(l); // unlink first, so nothing can reach through into the real dirs
+    try {
+        git(root, ["worktree", "remove", "--force", path]);
+    }
+    catch {
+        // git no longer knows it (pruned by hand): rm never follows symlinks
+        rmSync(path, { recursive: true, force: true });
+        git(root, ["worktree", "prune"]);
+    }
+}
+/** Pathspecs that keep Cheap Agent's state and the given dependency dirs out of a git operation. */
+const outside = (dirs) => [".cheapag", ...dirs].map((d) => `:(exclude,top,literal)${d}`);
+const isDirectory = (path) => {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+/** Everything the job changed relative to its baseline tree, as a binary patch plus per-file stats. */
+export function worktreeDiff(worktree) {
+    const { path, base } = worktree;
+    // the worktree's own index: throwaway, never committed. A linked dir is a symlink, which a `node_modules/`
+    // ignore rule does not match, so the linked ones (only those: a tracked vendor/ stays in) are excluded.
+    git(path, ["add", "-A", "--", ".", ...outside(worktree.linked)]);
+    const patch = git(path, ["diff", "--cached", "--binary", base]);
+    const stats = git(path, ["diff", "--cached", "--numstat", "-z", "--no-renames", base]).split("\0").filter(Boolean);
+    const statuses = new Map();
+    const names = git(path, ["diff", "--cached", "--name-status", "-z", "--no-renames", base]).split("\0").filter(Boolean);
+    for (let i = 0; i < names.length; i += 2)
+        statuses.set(names[i + 1], names[i]);
+    const changed = stats.map((line) => {
+        const [add, del, file] = line.split("\t");
+        // binary files report "-" for both counts
+        return { status: statuses.get(file) ?? "M", path: file, add: Number(add) || 0, del: Number(del) || 0 };
+    });
+    return { patch, changed };
+}
+/** Why the checkout cannot be a job's starting point right now (a merge, rebase… or unresolved conflicts), if it cannot. */
+export function operationInProgress(root) {
+    const markers = { MERGE_HEAD: "a merge", "rebase-merge": "a rebase", "rebase-apply": "a rebase", CHERRY_PICK_HEAD: "a cherry-pick", REVERT_HEAD: "a revert" };
+    for (const [marker, name] of Object.entries(markers)) {
+        if (existsSync(git(root, ["rev-parse", "--path-format=absolute", "--git-path", marker]).trim()))
+            return `${name} is in progress`;
+    }
+    // e.g. after a conflicted `git stash pop`: no marker file, but `git stash create` would fail
+    if (git(root, ["ls-files", "--unmerged"]).trim())
+        return "there are unresolved conflicts";
+}
+export function removeWorktree(root, worktree) {
+    discard(root, worktree.path, worktree.links);
+}
+/** How long landing waits for another holder. `CHEAPAG_LOCK_TIMEOUT_MS` is a test hook (like CHEAPAG_OPENCODE_URL), not a setting. */
+const lockTimeoutMs = () => Number(process.env.CHEAPAG_LOCK_TIMEOUT_MS) || 10 * 60_000;
+/** Serialises landing and integration checks across Cheap Agent processes on one project: `.cheapag/land.lock` holds pid + timestamp + token. */
+export async function withLock(root, fn) {
+    const lock = join(root, ".cheapag", "land.lock");
+    const token = randomBytes(8).toString("hex");
+    // unique per call: parallel groups in one process wait on the lock at once, and must not delete each other's file
+    const mine = `${lock}.${process.pid}.${token}`;
+    mkdirSync(join(root, ".cheapag"), { recursive: true });
+    // written whole, then hard-linked into place: the lock never exists without its contents
+    writeFileSync(mine, JSON.stringify({ pid: process.pid, at: new Date().toISOString(), token }));
+    const timeout = lockTimeoutMs();
+    const deadline = Date.now() + timeout;
+    try {
+        for (;;) {
+            try {
+                linkSync(mine, lock);
+                break;
+            }
+            catch (err) {
+                if (err.code !== "EEXIST")
+                    throw err;
+            }
+            const holder = readHolder(lock); // gone: released meanwhile, so try again at once
+            if (!holder)
+                continue;
+            if (!(holder.pid > 0 && isAlive(holder.pid)))
+                breakStale(lock, holder);
+            else if (Date.now() > deadline) {
+                const waited = timeout >= 60_000 ? `${Math.round(timeout / 60_000)} min` : `${timeout / 1000} s`;
+                throw new Error(`timed out after ${waited} waiting for .cheapag/land.lock (held by pid ${holder.pid} since ${holder.at}); try again once it is released`);
+            }
+            else
+                await new Promise((r) => setTimeout(r, 200));
+        }
+    }
+    finally {
+        rmSync(mine, { force: true });
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        // only our own: never a lock someone else holds now
+        if (readHolder(lock)?.token === token)
+            rmSync(lock, { force: true });
+    }
+}
+/**
+ * Removes a lock whose holder is dead. The rename (to a name of our own) lets only one waiter break it. Between reading
+ * the dead holder and renaming, another waiter may have broken it and a live process taken it: then that lock goes back.
+ */
+function breakStale(lock, dead) {
+    const stale = `${lock}.stale.${randomBytes(4).toString("hex")}`;
+    try {
+        renameSync(lock, stale);
+    }
+    catch {
+        return; // another waiter already broke it
+    }
+    if (readHolder(stale)?.token !== dead.token) {
+        try {
+            linkSync(stale, lock);
+        }
+        catch {
+            // shortcut: a third process took the free name in the instant before the put-back, so two hold it; needs OS file locks (flock) to close
+        }
+    }
+    rmSync(stale, { force: true });
+}
+/** The lock's holder, or undefined when the file is gone. */
+function readHolder(file) {
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { pid: 0, at: "unknown", token: text }; // never written partly, so not a Cheap Agent lock: no live holder
+    }
+}
+const literal = (path) => `:(literal)${path}`;
+/**
+ * 3-way applies `patch` to the user's working tree, uncommitted and leaving their index alone.
+ * Runs against a throwaway index synced to the working tree, so their unstaged edits are the merge base side.
+ * Returns undefined on success, or the conflict text with the tree untouched.
+ */
+export function land(root, job, patch, paths) {
+    return withLock(root, () => {
+        if (!patch.trim())
+            return undefined;
+        const index = join(root, ".cheapag", "jobs", job, "land.index");
+        copyFileSync(git(root, ["rev-parse", "--path-format=absolute", "--git-path", "index"]).trim(), index);
+        const env = { GIT_INDEX_FILE: index };
+        try {
+            // bring exactly the patch's paths into the throwaway index as they are on disk now, untracked files included:
+            // the job's baseline had them (carry-over), so the patch expects them
+            const tracked = new Set(git(root, ["ls-files", "-z", "--", ...paths.map(literal)], env).split("\0"));
+            const present = paths.filter((p) => tracked.has(p) || existsSync(join(root, p)));
+            if (present.length)
+                git(root, ["add", "-A", "--", ...present.map(literal)], env);
+            const check = applyOutput(root, ["apply", "--3way", "--check", "-"], env, patch);
+            // shortcut: `apply --3way --check` exits 0 even when it would leave conflict markers, so read its message; upgrade if git changes the wording
+            if (check.failed || /with conflicts/.test(check.output))
+                return check.output.trim() || "patch does not apply";
+            // shortcut: the lock does not stop the developer's editor; an edit to these files in the milliseconds since the check
+            // could still leave markers here. Upgrade by applying with --cached to the throwaway index and checking out its paths.
+            const applied = applyOutput(root, ["apply", "--3way", "-"], env, patch);
+            return applied.failed ? applied.output.trim() : undefined;
+        }
+        finally {
+            rmSync(index, { force: true });
+        }
+    });
+}
+/** git apply's verdict lives in stderr even when it exits 0. */
+function applyOutput(root, args, env, patch) {
+    const r = spawnSync("git", args, { cwd: root, env: { ...process.env, ...env }, input: patch, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+    return { failed: r.status !== 0, output: `${r.stdout}${r.stderr}` };
+}
+/** The paths a failed landing names as conflicting, from git apply's messages. */
+export function conflictPaths(text) {
+    const named = [...text.matchAll(/^Applied patch to '(.+)' with conflicts\.$|^error: (.+?): (?:does not exist in index|does not match index|already exists in (?:index|working directory)|patch does not apply)$/gm)];
+    return [...new Set(named.map((m) => m[1] ?? m[2]))];
+}
+/**
+ * For a redo: 3-way applies a job's earlier patch onto its fresh worktree, so clashing hunks are left there as conflict
+ * markers for the worker to reconcile. Returns the paths left conflicted. Only the worktree (and its own index) changes.
+ */
+export function reapply(worktree, patch) {
+    applyOutput(worktree.path, ["apply", "--3way", "-"], {}, patch); // a patch that cannot apply at all leaves the worktree as it was
+    return git(worktree.path, ["diff", "--name-only", "-z", "--diff-filter=U"]).split("\0").filter(Boolean);
+}
+/** Paths whose changes still add conflict marker lines; run after `worktreeDiff`, which stages the worktree. */
+export function leftoverMarkers(worktree) {
+    const r = spawnSync("git", ["diff", "--cached", "--check", worktree.base], { cwd: worktree.path, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+    return [...new Set([...r.stdout.matchAll(/^(.+?):\d+: leftover conflict marker$/gm)].map((m) => m[1]))];
+}
+/**
+ * The worktree a finished job left behind, for `land`: always `.cheapag/worktrees/<job>` (never a path read from a
+ * record), and only a real directory. The `linkDirs` entries that are links in it are its dependency links.
+ */
+export function jobWorktree(root, job, base, linkDirs) {
+    const path = join(root, ".cheapag", "worktrees", job);
+    if (!lstatOf(path)?.isDirectory())
+        return undefined;
+    const links = linkDirs.map((d) => join(path, d)).filter((l) => lstatOf(l)?.isSymbolicLink());
+    return { path, head: "", stash: null, base, links, linked: links.map((l) => normalisePath(relative(path, l))) };
+}
+const lstatOf = (path) => {
+    try {
+        return lstatSync(path);
+    }
+    catch {
+        return undefined;
+    }
+};