cheap-agent 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,95 @@
+Copyright (c) 2026 muaaz9329
+
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+No Liability
+
+As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.
+
+Definitions
+
+The licensor is the entity offering these terms, and the software is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+you refers to the individual or entity agreeing to these terms.
+
+your company is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. control means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+your licenses are all the licenses granted to you for the software under
+these terms.
+
+use means anything you do with the software requiring one of your licenses.
+
+trademark means trademarks, service marks, and similar rights.

package/README.md

@@ -1,3 +1,188 @@
-# Temporary Holding Version
+<h1 align="center">Cheap Agent</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <em>Your Opus is a principal engineer. Stop paying it to type.</em>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/cheap-agent?style=flat-square&color=111111&label=npm" alt="npm">
+  <img src="https://img.shields.io/npm/dt/cheap-agent?style=flat-square&color=111111&label=downloads" alt="npm downloads">
+  <img src="https://img.shields.io/badge/for-Claude%20Code-111111?style=flat-square" alt="For Claude Code">
+  <img src="https://img.shields.io/badge/cheap%20model-%C2%BD%C2%A2%20a%20task-111111?style=flat-square" alt="Cheap model: half a cent a task">
+  <img src="https://img.shields.io/badge/tested%20on-SWE--bench%20Verified-111111?style=flat-square" alt="Tested on SWE-bench Verified">
+  <img src="https://img.shields.io/badge/license-Elastic%202.0-111111?style=flat-square" alt="Elastic License 2.0">
+</p>
+
+<p align="center">
+  <img src="assets/hero.svg" width="880" alt="Same feature, same prompt: Claude Code alone used 154k Opus tokens in 5 turns; with Cheap Agent 57k Opus tokens in 2 turns, 63% fewer, and the cheap model cost half a cent. Both versions pass all their tests.">
+</p>
+
+<p align="center">
+  <strong>Same feature. Same prompt. 63% fewer Opus tokens.</strong><br>
+  <strong>Your Claude plan lasts longer. Your code still ships with tests.</strong>
+</p>
+
+---
+
+You know the principal engineer. Twenty years in. Sees the whole system at once. Costs a fortune per hour.
+
+You would never pay them to type out a CSV exporter.
+
+But that's exactly what happens every time Opus writes your code: the most expensive model you have, reading files, typing boilerplate, re-running tests, burning through your plan.
+
+**Cheap Agent fixes the org chart.** Opus plans and decides. A model that costs half a cent per task does the typing, in its own copy of your project, and has to prove its work with a test before anything reaches you.
+
+## Why I built this
+
+The idea: get **$200-plan usage out of the $100 Claude plan**, and **$50–70 worth out of the $20 plan**, with a few dollars of DeepSeek doing the typing.
+
+I've met a lot of students, mostly in developing countries, who really want Opus for the hard problems and simply can't afford $100 a month. I wanted to find something that helps them.
+
+This is a small effort from my side. It won't make Opus ten times cheaper. But stretching the plan you already pay for is something, and something is better than nothing.
+
+## Install
+
+**Easiest:** paste this into Claude Code. It asks what you want, then gives you one command to run.
+
+```text
+Set up Cheap Agent (npm: cheap-agent) for me.
+1. Ask me: which provider (OpenRouter recommended, DeepSeek or OpenCode Go), and which
+   models (balanced is the default; cheapest, strongest, or my own provider/model).
+2. Check that node is 20+ and the claude CLI is installed.
+3. If I picked my own model, save {"models":{"implement":"<model>"}} in
+   ~/.config/cheapag/config.json, keeping what else is there.
+4. Give me the command to run in my terminal: npx cheap-agent login --preset <my choice,
+   or custom>, and which number to pick for my provider (1 OpenCode Go, 2 OpenRouter,
+   3 DeepSeek). I run it and type my API key there. Never ask for my key.
+5. When I say done, check `claude mcp list` shows cheapag, then tell me to run
+   /cheapag:allow in a new Claude Code session in my project.
+```
+
+**Or do it yourself:**
+
+```bash
+npx cheap-agent
+```
+
+Pick a provider (**OpenRouter** if unsure), press Enter for the recommended models, paste your API key. It checks the key works, then adds itself to Claude Code for every project.
+
+Then, in each project, once:
+
+```
+/cheapag:allow
+```
+
+**That's it.** Ask Claude for changes like you always do.
+
+**You need:**
+- [Claude Code](https://claude.com/claude-code)
+- [Node.js](https://nodejs.org) 20+
+- An API key with a few dollars on it from [OpenRouter](https://openrouter.ai/keys), [DeepSeek](https://platform.deepseek.com) or [OpenCode Go](https://opencode.ai)
+
+A few dollars lasts hundreds of tasks. It runs on macOS and Linux.
+
+**Windows (beta):** tested in CI, not yet by a Windows user. You also need [Git for Windows](https://git-scm.com/downloads/win) (Git Bash). Known so far:
+- The very first job can take about 2 minutes while the cheap model's engine (OpenCode) sets itself up. Later jobs start in seconds.
+- If that engine crashes mid-session, Cheap Agent starts a new one, but the crashed copy can stay running (`opencode.exe` in Task Manager) until you end it or restart.
+- The cheap model can't read your dependency folders (like `node_modules`) inside its copy of the project. Your tests still run normally.
+
+## The numbers
+
+Tested on [SWE-bench Verified](https://www.swebench.com): real bugs from real open-source projects, graded by the official harness. Same prompts in Claude Code with Opus 5.5, with and without Cheap Agent.
+
+<p align="center">
+  <img src="assets/chart.svg" width="880" alt="Opus tokens, Claude Code alone versus with Cheap Agent. Adding a feature: 154k vs 57k, 63% less, both pass all tests. 7 everyday bug fixes: 1.6M vs 655k, 59% less, 7 of 7 solved by both. 9 of the hardest bugs: 3.0M vs 1.0M, 67% less, 5 of 9 solved vs 7 of 9, with a Sonnet helper doing the leftovers.">
+</p>
+
+**What I won't hide:**
+- On the very hardest bugs it solved 5 of 9 where plain Opus solved 7.
+- On tiny jobs (a few lines, or a whole small app from nothing), Opus is already quick, so there's nothing to save.
+
+Cheap Agent shines on the work in between: real features and real fixes in real code. That's most of your day.
+
+## Before / after
+
+**The ask:** *"Add monthly budgets to the expense tracker, plus a CSV export. Tests for everything."*
+
+|  | Claude Code alone | Claude Code + Cheap Agent |
+|---|---|---|
+| Opus tokens | 154k | **57k** |
+| Opus turns | 5 | **2** |
+| Who wrote the code | Opus | a cheap model, for **$0.005** |
+| Tests | 33 passing | **38 passing** |
+
+Opus wrote one task. The cheap model did the rest, tests included.
+
+## Built with itself
+
+Native Windows support (36 files, +753/−278 lines) was built with Cheap Agent. Claude found the problems and wrote the plans. The cheap model wrote the code in 30 jobs for **$0.29 in total**, Sonnet helpers finished what it couldn't and read OpenCode's source to find the two Windows-only bugs, and the full test suite now passes on Linux and Windows.
+
+## How it works
+
+<p align="center">
+  <img src="assets/flow.svg" width="880" alt="How it works: Opus writes a short task; a cheap model works in its own copy of your project, writes a test that fails, fixes the code and makes the test pass; Cheap Agent runs the tests itself and only passing work lands, uncommitted; Opus reads a ten-line result and tells you. If the cheap model can't finish, a Sonnet helper finishes the step instead of Opus.">
+</p>
+
+- **Every change is proven.** The cheap model must write a test that fails before its fix and passes after. Cheap Agent runs the tests itself; it doesn't take the model's word for it.
+- **Your project stays clean.** Work happens in a private copy (a git worktree). Only passing work lands, uncommitted, so you review the diff like any other.
+- **Opus stays in charge,** but it's held to it: Cheap Agent's hooks stop Opus from quietly redoing work that already passed, or doing a failed step itself when Sonnet can.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `/cheapag:allow` | Your OK to send this project's code to the cheap model. Once per project. |
+| `/cheapag:status` | Recent jobs, and what the cheap model has cost you. |
+| `/cheapag:hook on` | No more "I'll just do it myself": Claude *must* hand code changes to the cheap model. |
+| `/cheapag:clean` | Tidy up old job folders. |
+
+## Settings
+
+Optional. Put a `cheapag.json` in a project:
+
+| Setting | Default | What it does |
+|---|---|---|
+| `takeover` | `"sonnet"` | Who finishes a step the cheap model couldn't: a Sonnet helper, or `"self"` (Opus, capped at 15 tool calls). |
+| `limits.max_turns` | `25` | The most turns the cheap model gets per step. |
+| `models` | from setup | Which cheap models to use. Switch with `npx cheap-agent login --preset strongest`. |
+
+## FAQ
+
+**Is a half-cent model actually any good?**
+On its own, no. With a written task from Opus, a test it has to pass, and a referee that runs that test, yes, most of the time. When it isn't, it says so and Sonnet takes over.
+
+**Does Claude check the work?**
+The tests check the work, and Cheap Agent runs them. Opus checking every passing change cost three times the tokens and caught nothing in my runs, so it trusts a pass. You still review the diff before you commit.
+
+**Where does my code go?**
+To the provider you picked, only after you run `/cheapag:allow` in that project, which also shows exactly which models will see it. Your API key stays on your machine, in a hidden prompt and a local credential store, never in chat.
+
+**Will it commit or push anything?**
+Never. Changes land uncommitted. Your git, your call.
+
+**Why not just use Sonnet for everything?**
+Sonnet still costs real usage on every line it types. The cheap model types for half a cent. Sonnet only gets called when the cheap model is stuck.
+
+**Can I sell it as a service?**
+No. Use it, change it, share it, at any company, for free. Just don't host it and sell it ([Elastic License 2.0](./LICENSE)).
+
+**Why "Cheap Agent"?**
+Because your plan isn't.
+
+## Update or remove
+
+**Update:**
+
+```bash
+npx cheap-agent@latest
+```
+
+**Remove** (two commands):
+
+```bash
+claude plugin uninstall cheapag@cheapag
+```
+
+```bash
+claude mcp remove -s user cheapag
+```

package/dist/allow.js

@@ -0,0 +1,48 @@
+import { consentGate, describe, writeConsent } from "./consent.js";
+import { detectProvider, LOGIN_COMMAND, providerLabel, redact } from "./credentials.js";
+import { modelName, routeModels } from "./routing.js";
+import { projectRoot } from "./workspace.js";
+const USAGE = "usage: cheapag allow [--zdr-only | --models <provider/model,…>]";
+/**
+ * `cheapag allow`: the developer's opt-in for the current repo (spec: Consent). Non-interactive, so the plugin's
+ * user-only `/cheapag:allow` can wrap it. No MCP tool calls this. Modes: all models (no flag), zero-retention only,
+ * or an explicit model list. The consent is for the provider logged in now; a later switch asks again.
+ */
+export function allow(args) {
+    const out = (line) => process.stdout.write(redact(line) + "\n");
+    let consent;
+    if (!args.length)
+        consent = { mode: "all" };
+    else if (args.length === 1 && args[0] === "--zdr-only")
+        consent = { mode: "zdr-only" };
+    else if (args.length === 2 && args[0] === "--models" && args[1].split(",").some((m) => m.trim())) {
+        consent = { mode: "models", models: args[1].split(",").map((m) => m.trim()).filter(Boolean) };
+    }
+    else {
+        out(`✗ ${USAGE}`);
+        return 1;
+    }
+    const provider = detectProvider();
+    if (!provider) {
+        out(`✗ no worker provider; run ${LOGIN_COMMAND} first`);
+        return 1;
+    }
+    let root;
+    try {
+        root = projectRoot(process.cwd());
+    }
+    catch (err) {
+        out(`✗ ${err.message}`);
+        return 1;
+    }
+    const record = { ...consent, provider: provider.provider, approvedAt: new Date().toISOString() };
+    writeConsent(root, record);
+    out(`✓ ${root}: code may go to ${providerLabel(provider.provider)} (${describe(record)})`);
+    // the same gate delegate uses, so what this prints is what jobs will run
+    const gate = consentGate(root, provider.provider);
+    if ("block" in gate)
+        out(`! ${gate.block}`);
+    else
+        out(`  models: ${routeModels(gate.route).map(modelName).join(", ")}`);
+    return 0;
+}

package/dist/cleanup.js

@@ -0,0 +1,173 @@
+import { existsSync, lstatSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { loadConfig } from "./config.js";
+import { redact } from "./credentials.js";
+import { recoverJobs } from "./jobs.js";
+import { isAlive, removeLink } from "./platform.js";
+import { git, projectRoot } from "./workspace.js";
+/**
+ * Cleanup (spec: Concurrency, platform, cleanup; A20), part of the Workspace module: at server start and on
+ * `cheapag clean`. Unlanded worktrees go after `retention.unlanded_worktree_days`, job folders after `job_log_days`
+ * (`all`: both at once). It only ever touches `.cheapag/worktrees/<id>` and `.cheapag/jobs/<id>`: consent.json,
+ * opencode/ and land.lock are never cleaned. Run `recoverJobs` first, so a crashed server's jobs age like any other.
+ */
+const DAY_MS = 86_400_000;
+// only folders named like our job ids are ours to remove
+const JOB_ID = /^j[0-9a-z]{4}$/;
+/** A job (`j…`) or research (`r…`) log folder under `.cheapag/jobs/`. */
+const LOG_ID = /^[jr][0-9a-z]{4}$/;
+const BATCH_FILE = /^b[0-9a-z]{4}\.json$/;
+/** How long a job folder without a readable record counts as just created, so even --all leaves it alone. */
+const UNKNOWN_GRACE_MS = 60 * 60_000;
+export function cleanup(root, retention, linkDirs, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const out = { removed: [], kept: [] };
+    const state = join(root, ".cheapag");
+    // a symlinked state dir (or subdir) would put what we delete outside the repo: leave it alone
+    if (!realDir(state))
+        return out;
+    const jobsDir = join(state, "jobs");
+    const treesDir = join(state, "worktrees");
+    const days = (since) => Math.floor((now - since) / DAY_MS);
+    const old = (since, limit) => opts.all || now - since >= limit * DAY_MS;
+    /** A job folder's record: whether it is in flight, and its age from when it ended (else started), else the folder's mtime. */
+    const job = (id) => {
+        const dir = join(jobsDir, id);
+        let record;
+        try {
+            // research logs keep their record as research.json (never in flight across a restart: it has no RUNNING state)
+            record = JSON.parse(readFileSync(join(dir, id.startsWith("r") ? "research.json" : "result.json"), "utf8"));
+        }
+        catch {
+            // no record (yet), or unreadable
+        }
+        // the record's own time, not mtime: recovery rewrites a record long after its job stopped
+        const at = Date.parse(record?.timing?.endedAt ?? record?.timing?.startedAt ?? "");
+        // no readable record: a job being created (or its record being rewritten) right now, unless the folder is long untouched
+        const unknown = !record && now - (mtime(dir) ?? 0) < UNKNOWN_GRACE_MS;
+        const live = unknown || ((record?.status === "RUNNING" || record?.status === "BLOCKED") && !!record.pid && isAlive(record.pid));
+        return { live, status: record?.status ?? (unknown ? "STARTING" : undefined), since: Number.isNaN(at) ? mtime(dir) ?? mtime(join(treesDir, id)) ?? now : at };
+    };
+    let removedTree = false;
+    for (const id of entries(treesDir, LOG_ID)) { // r…: a research worktree left by a crash
+        const path = join(treesDir, id);
+        const j = job(id);
+        if (j.live)
+            out.kept.push(`worktree ${id}: ${j.status} job in flight`);
+        else if (!old(j.since, retention.unlanded_worktree_days))
+            out.kept.push(`worktree ${id}: ${days(j.since)}d old, kept ${retention.unlanded_worktree_days}d`);
+        else {
+            // unlink first, so nothing can reach through into the real dependency dirs
+            for (const dir of linkDirs)
+                removeLink(join(path, dir));
+            try {
+                git(root, ["worktree", "remove", "--force", path]);
+            }
+            catch {
+                rmSync(path, { recursive: true, force: true }); // git no longer knows it; rm never follows symlinks
+            }
+            removedTree = true;
+            out.removed.push(`worktree ${id}: ${opts.all ? "--all" : `unlanded, ${days(j.since)}d old`}`);
+        }
+    }
+    if (removedTree)
+        git(root, ["worktree", "prune"]);
+    for (const id of entries(jobsDir, LOG_ID)) {
+        const j = job(id);
+        if (j.live)
+            out.kept.push(`job ${id}: ${j.status} job in flight`);
+        // the record explains its worktree: it stays while the worktree does
+        else if (realDir(join(treesDir, id)))
+            out.kept.push(`job ${id}: its worktree is kept`);
+        else if (!old(j.since, retention.job_log_days))
+            out.kept.push(`job ${id}: ${days(j.since)}d old, kept ${retention.job_log_days}d`);
+        else {
+            rmSync(join(jobsDir, id), { recursive: true, force: true });
+            out.removed.push(`job ${id}: ${opts.all ? "--all" : `${days(j.since)}d old`}`);
+        }
+    }
+    // a batch record goes with its last job folder; one that never got a job (a crashed start) goes by age
+    const batchesDir = join(state, "batches");
+    if (realDir(batchesDir)) {
+        for (const name of readdirSync(batchesDir).filter((n) => BATCH_FILE.test(n))) {
+            const file = join(batchesDir, name);
+            let jobs = [];
+            try {
+                jobs = JSON.parse(readFileSync(file, "utf8")).jobs ?? [];
+            }
+            catch {
+                // unreadable: judged by age alone
+            }
+            const id = name.slice(0, -".json".length);
+            if (jobs.some((j) => JOB_ID.test(j) && existsSync(join(jobsDir, j))))
+                continue; // its jobs say what it was: kept silently
+            const since = mtime(file) ?? now;
+            if (jobs.length === 0 && !old(since, retention.job_log_days))
+                continue;
+            rmSync(file, { force: true });
+            out.removed.push(`batch ${id}: ${jobs.length ? "its jobs are gone" : opts.all ? "--all" : `${days(since)}d old`}`);
+        }
+    }
+    return out;
+}
+/** Cleans the repo containing `cwd` with its configured retention (throws on a bad config or outside a repo). */
+export function cleanProject(cwd, all = false) {
+    const root = projectRoot(cwd);
+    const config = loadConfig(root);
+    return cleanup(root, config.retention, config.link_dirs, { all });
+}
+/** `cheapag clean [--all]`: non-interactive, so the plugin's `/cheapag:clean` can wrap it; prints what went and what stayed. */
+export function clean(args) {
+    const out = (line) => process.stdout.write(redact(line) + "\n");
+    if (args.length > 1 || (args.length && args[0] !== "--all")) {
+        out("✗ usage: cheapag clean [--all]   (--all: remove everything not in flight)");
+        return 1;
+    }
+    let result;
+    try {
+        recoverJobs(process.cwd()); // a crashed server's RUNNING/BLOCKED jobs become CANCELLED, then age normally
+        result = cleanProject(process.cwd(), args[0] === "--all");
+    }
+    catch (err) {
+        out(`✗ ${err.message}`);
+        return 1;
+    }
+    out(`✓ removed ${result.removed.length}, kept ${result.kept.length}`);
+    for (const line of result.removed)
+        out(`  removed ${line}`);
+    for (const line of result.kept)
+        out(`  kept ${line}`);
+    return 0;
+}
+/** A one-line offer to gitignore `.cheapag/` when the repo containing `cwd` does not ignore it (spec E5); never edits .gitignore. */
+export function gitignoreHint(cwd) {
+    try {
+        git(projectRoot(cwd), ["check-ignore", "-q", ".cheapag/"]);
+        return undefined;
+    }
+    catch (err) {
+        // exit 1: not ignored; anything else (not a repo, git error) offers nothing
+        return err.status === 1
+            ? "hint: .cheapag/ (Cheap Agent's runtime state) is not gitignored; add a `.cheapag/` line to .gitignore so it is never committed"
+            : undefined;
+    }
+}
+/** Our job-id folders directly under `dir`, if `dir` is a real directory. */
+const entries = (dir, ids = JOB_ID) => (realDir(dir) ? readdirSync(dir).filter((id) => ids.test(id) && realDir(join(dir, id))) : []);
+/** A directory that is not a symlink. */
+function realDir(path) {
+    try {
+        return lstatSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function mtime(path) {
+    try {
+        return lstatSync(path).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/config.js

@@ -0,0 +1,133 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+/** Who implements a hard task (ticket 26): the worker on `models.hard`, Claude itself, or Claude's own Sonnet subagent. */
+export const HARD_TASKS = ["delegate", "self", "sonnet"];
+/** Who finishes a step the worker could not (ticket 30): a Sonnet subagent, or Claude itself within limits.takeover_calls. */
+export const TAKE_OVER = ["sonnet", "self"];
+const DEFAULTS = {
+    link_dirs: ["node_modules", ".venv", "venv", "vendor"], allow_commands: ["npx tsc --noEmit"],
+    limits: { max_turns: 25, max_minutes: 20, max_cost_usd: 0.5, max_parallel: 3, max_blocked_minutes: 60, repro_by_turns: 12, takeover_calls: 15 },
+    retention: { unlanded_worktree_days: 7, job_log_days: 30 },
+    models: {}, // the provider's role defaults (src/routing.ts)
+    escalation_skip_at: 0.8,
+    guard_lines: 20,
+    hard_tasks: "delegate",
+    takeover: "sonnet",
+};
+// build output is never linked: a job must build its own (ADR-0003)
+const BUILD_OUTPUT = /^(dist|build|out|\.next|\.nuxt|target|coverage)$/;
+/** The user-level config every repo's `cheapag.json` overrides; `cheapag login` writes its `models` (the preset). */
+export const userConfigFile = () => join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "cheapag", "config.json");
+export function loadConfig(root) {
+    const [mine, repo] = [read(userConfigFile()), read(join(root, "cheapag.json"))];
+    // caps, retention and models merge key by key, so a repo can set one and keep the user's others
+    return {
+        ...DEFAULTS, ...mine, ...repo,
+        limits: { ...DEFAULTS.limits, ...mine.limits, ...repo.limits },
+        retention: { ...DEFAULTS.retention, ...mine.retention, ...repo.retention },
+        models: { ...mine.models, ...repo.models },
+    };
+}
+function read(file) {
+    if (!existsSync(file))
+        return {};
+    let raw;
+    try {
+        raw = readFileSync(file, "utf8");
+    }
+    catch (err) {
+        throw new Error(`cannot read ${file}: ${err.message}`);
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${file} is not valid JSON: ${err.message}`);
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error(`${file} must hold a JSON object`);
+    const { test_cmd, integration_cmd, link_dirs, allow_commands, limits, retention, models, escalation_skip_at, guard_lines, hard_tasks, takeover } = value;
+    if (limits !== undefined && (typeof limits !== "object" || limits === null || Array.isArray(limits)))
+        throw new Error(`${file}: limits must be an object`);
+    const caps = {};
+    // E4's self_fix_attempts is not read yet
+    for (const key of ["max_turns", "max_minutes", "max_cost_usd", "max_parallel", "max_blocked_minutes", "repro_by_turns", "takeover_calls"]) {
+        const v = limits?.[key];
+        if (v === undefined)
+            continue;
+        const whole = key === "max_turns" || key === "max_parallel" || key === "repro_by_turns" || key === "takeover_calls";
+        // takeover_calls 0 turns the take-over budget off (ticket 29)
+        const min = key === "takeover_calls" ? 0 : Number.MIN_VALUE;
+        if (typeof v !== "number" || !Number.isFinite(v) || v < min || (whole && !Number.isInteger(v))) {
+            throw new Error(`${file}: limits.${key} must be a ${min ? "positive" : "non-negative"} ${whole ? "whole number" : "number"}`);
+        }
+        caps[key] = v;
+    }
+    if (retention !== undefined && (typeof retention !== "object" || retention === null || Array.isArray(retention)))
+        throw new Error(`${file}: retention must be an object`);
+    const keep = {};
+    for (const key of ["unlanded_worktree_days", "job_log_days"]) {
+        const v = retention?.[key];
+        if (v === undefined)
+            continue;
+        if (typeof v !== "number" || !Number.isFinite(v) || v < 0)
+            throw new Error(`${file}: retention.${key} must be a number of days (0 or more)`);
+        keep[key] = v;
+    }
+    if (allow_commands !== undefined && (!Array.isArray(allow_commands) || allow_commands.some((c) => typeof c !== "string" || !c.trim()))) {
+        throw new Error(`${file}: allow_commands must be a list of commands`);
+    }
+    if (models !== undefined && (typeof models !== "object" || models === null || Array.isArray(models)))
+        throw new Error(`${file}: models must be an object`);
+    const roles = (models ?? {});
+    const name = (v) => typeof v === "string" && /^[\w.-]+\/\S+$/.test(v);
+    for (const role of ["implement", "medium", "hard", "research", "escalation"]) {
+        if (roles[role] !== undefined && !name(roles[role]))
+            throw new Error(`${file}: models.${role} must be a provider/model name, e.g. opencode-go/deepseek-v4.1-flash`);
+    }
+    if (roles.fallback !== undefined && (!Array.isArray(roles.fallback) || !roles.fallback.every(name)))
+        throw new Error(`${file}: models.fallback must be a list of provider/model names`);
+    if (escalation_skip_at !== undefined && (typeof escalation_skip_at !== "number" || !(escalation_skip_at > 0 && escalation_skip_at <= 1))) {
+        throw new Error(`${file}: escalation_skip_at must be a number above 0 and at most 1`);
+    }
+    if (hard_tasks !== undefined && !HARD_TASKS.includes(hard_tasks))
+        throw new Error(`${file}: hard_tasks must be one of ${HARD_TASKS.join(", ")}`);
+    if (takeover !== undefined && !TAKE_OVER.includes(takeover))
+        throw new Error(`${file}: takeover must be one of ${TAKE_OVER.join(", ")}`);
+    if (guard_lines !== undefined && (typeof guard_lines !== "number" || !Number.isInteger(guard_lines) || guard_lines <= 0)) {
+        throw new Error(`${file}: guard_lines must be a positive whole number`);
+    }
+    if (test_cmd !== undefined && (typeof test_cmd !== "string" || !test_cmd.trim()))
+        throw new Error(`${file}: test_cmd must be a non-empty string`);
+    // null is E4's written default: test_cmd
+    if (integration_cmd != null && (typeof integration_cmd !== "string" || !integration_cmd.trim()))
+        throw new Error(`${file}: integration_cmd must be a non-empty string`);
+    let dirs;
+    if (link_dirs !== undefined) {
+        if (!Array.isArray(link_dirs) || link_dirs.some((d) => typeof d !== "string" || !d.trim()))
+            throw new Error(`${file}: link_dirs must be a list of directory paths`);
+        dirs = link_dirs.map((dir) => {
+            const parts = dir.split(/[\\/]+/).filter(Boolean);
+            if (isAbsolute(dir) || parts.includes(".."))
+                throw new Error(`${file}: link_dirs entry "${dir}" must be a path inside the repository`);
+            if (BUILD_OUTPUT.test(parts.at(-1)))
+                throw new Error(`${file}: link_dirs entry "${dir}" is build output, which is never linked`);
+            return parts.join("/");
+        });
+    }
+    return {
+        ...(test_cmd !== undefined && { test_cmd }),
+        ...(integration_cmd != null && { integration_cmd }),
+        ...(dirs && { link_dirs: dirs }),
+        ...(allow_commands !== undefined && { allow_commands: allow_commands.map((c) => c.trim()) }),
+        limits: caps,
+        retention: keep,
+        ...(models !== undefined && { models: roles }),
+        ...(escalation_skip_at !== undefined && { escalation_skip_at }),
+        ...(guard_lines !== undefined && { guard_lines }),
+        ...(hard_tasks !== undefined && { hard_tasks: hard_tasks }),
+        ...(takeover !== undefined && { takeover: takeover }),
+    };
+}