cheap-agent 0.0.0-stage → 1.1.0

package/dist/research.js

@@ -0,0 +1,270 @@
+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, releaseDirectory } 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 = normalisePath(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(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) {
+            await releaseDirectory(worktree.path); // release before the worktree is removed
+            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,
+    };
+}
+/** The raw `path:line(-line)` candidates in text, before validation. Accepts a Windows drive letter and backslashes. */
+export function refTokens(text) {
+    return [...text.matchAll(/((?:[A-Za-z]:)?[\w./\\@-]+):(\d+)(?:-(\d+))?/g)].map(([, path, from, to]) => ({ path, from, to }));
+}
+/**
+ * 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 refTokens(text)) {
+        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 };
+    }
+}

package/dist/routing.js

@@ -0,0 +1,212 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { providerLabel } from "./credentials.js";
+// verified on OpenCode 1.19.0: options.provider becomes OpenRouter's request-body routing preference, so upstreams that
+// collect data are never used. Every OpenRouter model carries it.
+const OPENROUTER_PRIVATE = { provider: { data_collection: "deny" } };
+/**
+ * Default models per provider and role (spec: Models and limits): each list is the role's model, then its fallbacks.
+ * Go and DeepSeek ids are in OpenCode 1.19.0's bundled model catalog; OpenRouter's are on openrouter.ai/api/v1/models
+ * (checked 2026-10-16). Direct DeepSeek has no other models to fall back to.
+ */
+export const ROLES = {
+    "opencode-go": {
+        implement: ["deepseek-v4.1-flash", "qwen3.7-plus", "glm-5.3", "kimi-k3"],
+        research: ["qwen3.8-flash", "deepseek-v4.1-flash"],
+        escalation: "deepseek-v4-pro",
+    },
+    openrouter: {
+        implement: ["deepseek/deepseek-v4.1-flash", "qwen/qwen3.7-plus", "z-ai/glm-5.3", "moonshotai/kimi-k3"],
+        research: ["qwen/qwen3.8-flash", "deepseek/deepseek-v4.1-flash"],
+        // GLM-5.3-Flash: 37% on Terminal-Bench 4.0 vs V4 Pro 14% (Vals, 2026-10-16), and cheaper ($0.05 in / $0.20 out)
+        escalation: "z-ai/glm-5.3-flash",
+    },
+    deepseek: { implement: ["deepseek-flash"], research: ["deepseek-flash"], escalation: "deepseek-v4-pro" },
+};
+/** `cheapag login`'s worker-model presets (ticket 27): a named `models` per provider; roles a preset leaves out keep the defaults above. */
+export const PRESET_NAMES = ["cheapest", "balanced", "strongest"];
+// balanced is the default route, Flash for every tier: GLM-5.3 cost Claude 1.5x fewer tokens than Flash on the tasks Flash
+// lost (ticket 25) but showed no gain on the hard tier (26), so it is opt-in as strongest. cheapest is balanced until a
+// cheaper worker than Flash exists (a tie reports balanced). Kimi K3 was dropped: $0.36 worker per task, BUDGET on half.
+export const PRESETS = {
+    "opencode-go": {
+        cheapest: { implement: "opencode-go/deepseek-v4.1-flash" },
+        balanced: { implement: "opencode-go/deepseek-v4.1-flash" },
+        strongest: { implement: "opencode-go/glm-5.3", medium: "opencode-go/glm-5.3" },
+    },
+    openrouter: {
+        cheapest: { implement: "openrouter/deepseek/deepseek-v4.1-flash" },
+        balanced: { implement: "openrouter/deepseek/deepseek-v4.1-flash" },
+        strongest: { implement: "openrouter/z-ai/glm-5.3", medium: "openrouter/z-ai/glm-5.3" },
+    },
+    // direct DeepSeek has no GLM: strongest implements on V4 Pro
+    deepseek: {
+        cheapest: { implement: "deepseek/deepseek-flash" },
+        balanced: { implement: "deepseek/deepseek-flash" },
+        strongest: { implement: "deepseek/deepseek-v4-pro" },
+    },
+};
+/** The preset whose route `models` gives on this provider, else custom (`preset=` in ping and status); a tie names balanced, the default. */
+export function presetOf(provider, models = {}) {
+    const key = (m) => JSON.stringify(fullRoute(provider, m));
+    return ["balanced", "cheapest", "strongest"].find((p) => key(PRESETS[provider][p]) === key(models)) ?? "custom";
+}
+const model = (provider, id) => provider === "openrouter" ? { providerID: provider, id, options: OPENROUTER_PRIVATE } : { providerID: provider, id };
+/** Claude's rating of a task from the issue (ticket 26): easy < 15 min, medium < 1 h, hard > 1 h of an engineer new to the code. */
+export const DIFFICULTIES = ["easy", "medium", "hard"];
+/** The model a job implements on: hard takes the hard model, else the medium one; medium the medium one; easy or no hint `implement`. */
+export const tierModel = (r, d) => (d === "hard" ? r.hard ?? r.medium : d === "medium" ? r.medium : undefined) ?? r.implement;
+/** Every model a provider's worker may run, defaults overridden by the config, before the repo's allowlist filters them. */
+export function fullRoute(provider, models = {}) {
+    const roles = ROLES[provider];
+    const own = (name) => (name?.startsWith(`${provider}/`) ? name.slice(provider.length + 1) : undefined);
+    const ownFallbacks = models.fallback?.map(own).filter((id) => !!id);
+    const [research, ...researchFallbacks] = [own(models.research) ?? roles.research[0], ...roles.research.slice(1)];
+    const tier = (name) => (own(name) ? model(provider, own(name)) : undefined);
+    return {
+        implement: model(provider, own(models.implement) ?? roles.implement[0]),
+        medium: tier(models.medium),
+        hard: tier(models.hard),
+        fallbacks: (models.fallback ? ownFallbacks : roles.implement.slice(1)).map((id) => model(provider, id)),
+        escalation: model(provider, own(models.escalation) ?? roles.escalation),
+        research: model(provider, research),
+        researchFallbacks: researchFallbacks.map((id) => model(provider, id)),
+    };
+}
+/** Every distinct model a route may send code to, first to last (for the config, the CONSENT block and `cheapag allow`). */
+export const routeModels = (r) => unique([r.implement, r.medium, r.hard, r.research, r.escalation, ...r.fallbacks, ...r.researchFallbacks]);
+const unique = (ms) => ms.filter((m, i) => !!m && ms.findIndex((o) => o && modelName(o) === modelName(m)) === i);
+export const modelName = (m) => `${m.providerID}/${m.id}`;
+export const chain = (first, fallbacks) => ({ first, current: first, rest: [...fallbacks], limits: [], used: [] });
+const CONTINUE = "The previous model hit a usage limit and was stopped. Continue the current step from where it left off.";
+/**
+ * One prompt on the chain's current model. On a provider limit the worker has already aborted the session (never waiting
+ * out the retry); the same session continues on the next fallback. `budget` is set when the job must stop as BUDGET:
+ * every allowed model is limited, or (OpenRouter) the credit is gone, which no other model can help with.
+ * With `escalation`, the prompt runs on that model alone: a limit there is returned (in `limit`), never fallen back from.
+ */
+export async function runRouted(session, prompt, c, provider, escalation, interrupt) {
+    // the first model is the session's own; once moved, every prompt names the fallback explicitly
+    let result = await session.run(prompt, escalation ?? (c.current === c.first ? undefined : c.current), interrupt);
+    if (escalation && result.limit)
+        c.limits.push(result.limit);
+    while (result.limit && !escalation) {
+        c.limits.push(result.limit);
+        const next = c.rest.shift();
+        if (!next)
+            return { ...result, budget: exhausted(provider, c.limits) };
+        c.current = next;
+        c.used.push(modelName(next));
+        result = await session.run(CONTINUE, next, interrupt);
+    }
+    if (provider === "openrouter" && result.httpStatus === 402)
+        return { ...result, budget: "OpenRouter credits exhausted" };
+    return result;
+}
+/** The BUDGET reason once every allowed model is limited, with the earliest reset the provider gave. */
+function exhausted(provider, limits) {
+    const ids = [...new Set(limits.map((l) => l.model.slice(l.model.indexOf("/") + 1)))].join(", ");
+    // OpenCode's next retry honours the provider's retry-after, i.e. the reset; a next only seconds away is just its backoff
+    // (no retry-after was sent), so then quote the provider's own text instead
+    const next = Math.min(...limits.map((l) => l.next).filter((n) => Number.isFinite(n) && n > Date.now() + 60_000));
+    const when = Number.isFinite(next) ? `~${clock(next)}` : limits.at(-1).message;
+    const go = limits.find((l) => l.reason === "account_rate_limit" || l.reason === "free_tier_limit");
+    if (go) {
+        // OpenCode words it "<limitName> usage limit reached. It will reset in …"
+        const window = go.reason === "free_tier_limit" ? "free tier" : go.message.match(/^(.+?) usage limit reached/i)?.[1].toLowerCase() ?? "usage";
+        return `Go ${window} window exhausted for ${ids} (resets ${when})`;
+    }
+    return `${providerLabel(provider)} rate limit on every allowed model: ${ids} (retry ${when})`;
+}
+/** Local time as HH:MM, with the date in front when it is not today. */
+function clock(ms) {
+    const d = new Date(ms);
+    const hhmm = d.toTimeString().slice(0, 5);
+    return d.toDateString() === new Date().toDateString() ? hhmm : `${d.toLocaleDateString("en-US", { month: "short", day: "numeric" })} ${hhmm}`;
+}
+// ---- spend ledger ----
+/**
+ * Go's monthly caps per model in USD (spec C4, the Go plan; models without a known cap are not tracked against one).
+ * shortcut: Go Plus caps (4x) are not known to Cheap Agent; add a plan setting if Go Plus users report early skips.
+ */
+const GO_CAPS = {
+    "opencode-go/deepseek-v4.1-flash": 80, "opencode-go/deepseek-v4-pro": 15, "opencode-go/qwen3.8-max": 15,
+    "opencode-go/qwen3.8-flash": 30, "opencode-go/qwen3.7-plus": 60,
+};
+/** Go enforces 20% of the monthly cap per 5 h, 50% per week, 100% per month (spec C4); tracked here as rolling windows. */
+const WINDOWS = [
+    { name: "5h", ms: 5 * 3_600_000, share: 0.2 },
+    { name: "weekly", ms: 7 * 86_400_000, share: 0.5 },
+    { name: "monthly", ms: 30 * 86_400_000, share: 1 },
+];
+/**
+ * The ledger is per user, not per repo: Go's windows are per account, so every repo's jobs draw on the same caps.
+ * One JSON line per model per job: `{at, model, costUsd}`.
+ * shortcut: never pruned (a line per job and model); trim entries older than the monthly window if it ever grows large.
+ */
+export const ledgerFile = () => join(process.env.XDG_STATE_HOME || join(homedir(), ".local", "state"), "cheapag", "spend.jsonl");
+export function recordSpend(spend) {
+    const lines = Object.entries(spend).filter(([, cost]) => cost > 0).map(([m, costUsd]) => JSON.stringify({ at: new Date().toISOString(), model: m, costUsd }) + "\n");
+    if (!lines.length)
+        return;
+    mkdirSync(dirname(ledgerFile()), { recursive: true });
+    appendFileSync(ledgerFile(), lines.join(""));
+}
+/** A model's fullest tracked window: the share of its cap used (plus `extra` not yet recorded); undefined without a known cap. */
+export function capUse(name, extra = 0) {
+    const monthly = GO_CAPS[name];
+    if (!monthly)
+        return undefined;
+    const now = Date.now();
+    const entries = readLedger().filter((e) => e.model === name);
+    return WINDOWS.map(({ name: window, ms, share }) => {
+        const spent = extra + entries.filter((e) => now - e.at < ms).reduce((sum, e) => sum + e.costUsd, 0);
+        return { used: spent / (monthly * share), window, capUsd: monthly * share };
+    }).reduce((a, b) => (b.used > a.used ? b : a));
+}
+/** Tracked spend per model and window, with the window's cap where Go has one (for `cheapag status`); models unspent this month are left out. */
+export function spendWindows(now = Date.now()) {
+    const ledger = readLedger();
+    return [...new Set(ledger.map((e) => e.model))].sort().flatMap((model) => {
+        const windows = WINDOWS.map(({ name: window, ms, share }) => ({
+            window,
+            spent: ledger.filter((e) => e.model === model && now - e.at < ms).reduce((sum, e) => sum + e.costUsd, 0),
+            capUsd: GO_CAPS[model] ? GO_CAPS[model] * share : undefined,
+        }));
+        return windows.at(-1).spent > 0 ? [{ model, windows }] : [];
+    });
+}
+function readLedger() {
+    if (!existsSync(ledgerFile()))
+        return [];
+    return readFileSync(ledgerFile(), "utf8").split("\n").flatMap((line) => {
+        try {
+            const e = JSON.parse(line);
+            return typeof e.model === "string" && typeof e.costUsd === "number" ? [{ model: e.model, costUsd: e.costUsd, at: Date.parse(e.at) }] : [];
+        }
+        catch {
+            return []; // a torn or damaged line only loses that entry
+        }
+    });
+}
+/**
+ * Why the escalation attempt is skipped, as its `tried:` line, or undefined to run it: not allowed by consent, limited
+ * earlier in this job, or at `skipAt` (E4 `escalation_skip_at`) or more of a tracked cap (spec A7: V4 Pro's Go cap is small).
+ */
+export function escalationSkip(escalation, c, skipAt, spent) {
+    if (!escalation)
+        return "esc: skipped, the escalation model is not allowed by this repo's consent";
+    const name = modelName(escalation);
+    if (c.limits.some((l) => l.model === name))
+        return `esc: skipped, ${escalation.id} hit its usage limit in this job`;
+    const use = capUse(name, spent[name] ?? 0);
+    if (use && use.used >= skipAt)
+        return `esc: skipped, ${escalation.id} at ${Math.round(use.used * 100)}% of its tracked ${use.window} cap ($${use.capUsd.toFixed(2)})`;
+    return undefined;
+}
+/**
+ * Whether the job ran on pay-as-you-go balance (`billing=zen`). OpenCode reports no balance signal, so it is inferred:
+ * a Go model whose tracked spend, this job included, is past a window's cap kept answering, which only balance allows.
+ */
+export const usedBalance = (spent) => Object.keys(spent).some((m) => (capUse(m)?.used ?? 0) > 1);

package/dist/rules.js

@@ -0,0 +1,25 @@
+/**
+ * The verification budget (ticket 23.3): Claude ran tests ~3 times per task, and again after an OK job. Part of the
+ * server instructions, and appended verbatim to the benchmark's baseline arm so both arms get the same rule.
+ */
+export const VERIFY_RULE = "Tests: run only the test file or id the task concerns, once before if it names a failure and once after; never the whole suite; chain commands with &&.";
+/**
+ * Trusting results (ticket 24.1): reading the diff of every bigger OK cost +28% tokens and caught no wrong fix. Ticket 30:
+ * unverified OKs were as correct as verified ones (83% vs 80%) yet re-checking them cost 229k tokens vs 63k, so every OK is
+ * trusted and the hook enforces it. Part of the server instructions.
+ */
+export const REVIEW_RULE = "An OK is done: don't re-run its tests or read its diff or its test.";
+/**
+ * Who finishes a step the worker could not (ticket 30). With Opus doing it, a failure costs at least what stock does,
+ * capping the saving near 1.9x; a Sonnet subagent working from the worker's found: note does it at a fraction of the
+ * usage. The hook enforces either: sonnet leaves Opus only Agent and cheapag's tools, self caps its tool calls.
+ */
+export const TAKE_OVER_RULE = {
+    sonnet: "After a FAIL or PARTIAL (land apply a PARTIAL first), don't delegate it again or open files: give the step to your Agent tool with model: sonnet, passing the task, the user's words and the block's found:, test=, error: and worktree; report its answer, and if it did not finish, say what is left.",
+    self: "After a FAIL or PARTIAL, do the task yourself instead of delegating it again: start from its found:, test= and worktree, open only the files they name, no background runs.",
+};
+/**
+ * Delegate before reading (ticket 23.4): Claude read ~2 files before each delegation, so the code entered its context
+ * anyway and the worker only typed. Part of the server instructions.
+ */
+export const SCOUT_RULE = "Don't open source files before delegating; the worker explores. To learn the code first, call research and pass its id as delegate brief:, not Read/Bash.";