balladeer 1.0.15 → 1.0.16

package/dist/commands/offers.js

@@ -0,0 +1,801 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { PROMISE_ID } from "../behavior-map-schema.js";
+import { repositoryRoot } from "../git.js";
+import { JUDGE_ACTIVE_VARIABLE, runHeadlessAgent, } from "../headless-agent.js";
+import { MAX_OFFERS, MAX_RULES_READ, OFFER_BRIEF_REVISION, OFFER_QUESTION, boundDiff, grouped, offerPrompt, } from "../offer-brief.js";
+import { runOwnedProcess } from "../owned-process.js";
+import { connectionReader, normalizePromise, readPromiseFile, } from "../promise-meaning.js";
+import { readBehaviorMaps } from "../risk/pipeline.js";
+import { resolveCommit } from "../scratch-worktree.js";
+import { normalizeControlPlane, StoreError } from "../store.js";
+import { CLI_INVOCATION, DEFAULT_CONTROL_PLANE } from "../wire.js";
+import { changedFiles, defaultBase } from "./judge.js";
+/**
+ * `balladeer offers`: the rules a change establishes that no promise records,
+ * for the person pushing it to be offered in that same session.
+ *
+ * It reads and reports. It stores nothing, records nothing and proposes
+ * nothing: a rule becomes a proposal only when the person says yes to the
+ * question each offer carries, in the session this hands its findings to, and
+ * that session records it. No offer outlives the session it was made in.
+ */
+export const OFFERS_SCHEMA_VERSION = "balladeer-offers/v1";
+/** The most existing promises read through the connection for one reading. */
+export const MAX_EXISTING_PROMISES = 200;
+/** How long `balladeer offers` gives the reader by hand, unless told otherwise. */
+export const DEFAULT_OFFER_TIMEOUT_SECONDS = 240;
+/**
+ * What the pushing session is told to do with the offers, stated once after
+ * them. It asks for the offers to be shown word for word because the first
+ * Codex canary's agent, told only to "offer these", answered that no hook
+ * message had appeared: in four sessions it surfaced them once, and with this
+ * wording three times in three.
+ */
+export const OFFER_INSTRUCTIONS = "Show the person these offers now, word for word and apart from the push, each ending with that question, unless your Balladeer guidance says to make no unsolicited offers here. " +
+    "A yes to that question, and only that, is consent to record that one: then record it with propose_promise, with your offer and their words of agreement, kept apart, as the explicit intent and the rule as your interpretation, and never quote your wording as theirs. " +
+    "A yes to the push is not that yes. " +
+    "If they decline or do not answer, say nothing was recorded and do not raise it again. " +
+    "Nothing has been stored.";
+// ---------------------------------------------------------------------------
+// Reading the reader's answer.
+const text = (value, max) => {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 && trimmed.length <= max ? trimmed : undefined;
+};
+/** A path as the change names it: forward slashes, no `./`, no diff side prefix. */
+function changedPath(value, changed) {
+    const path = value.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+    if (changed.has(path))
+        return path;
+    const unprefixed = path.replace(/^[ab]\//, "");
+    return changed.has(unprefixed) ? unprefixed : undefined;
+}
+/**
+ * Keeps what is well formed and whose evidence names a file the change
+ * touches, in the reader's own order. The first three are offered, each with
+ * the question; the rest are held, in the same shape without it. Covered
+ * rules must name a promise the reader was given, and there are none when the
+ * existing promises could not be read.
+ */
+export function readOfferAnswer(answer, input) {
+    const changed = new Set(input.changedFiles);
+    const found = [];
+    const rules = new Set();
+    for (const raw of Array.isArray(answer?.offers) ? answer.offers : []) {
+        if (found.length >= MAX_RULES_READ)
+            break;
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+            continue;
+        const entry = raw;
+        const rule = text(entry.rule, 240);
+        const beneficiary = text(entry.beneficiary, 200);
+        const trigger = text(entry.trigger, 300);
+        const passingExample = text(entry.passingExample, 500);
+        const failingExample = text(entry.failingExample, 500);
+        const evidence = [];
+        for (const item of Array.isArray(entry.evidence) ? entry.evidence : []) {
+            const record = (item ?? {});
+            const named = typeof record.file === "string" ? changedPath(record.file, changed) : undefined;
+            const shows = text(record.shows, 400);
+            if (named === undefined || shows === undefined)
+                continue;
+            if (evidence.some((kept) => kept.file === named))
+                continue;
+            evidence.push({ file: named, shows });
+            if (evidence.length === 5)
+                break;
+        }
+        const statedBy = entry.statedBy;
+        const confidence = entry.confidence;
+        if (rule === undefined ||
+            /[\n\r]/.test(rule) ||
+            beneficiary === undefined ||
+            trigger === undefined ||
+            passingExample === undefined ||
+            failingExample === undefined ||
+            // A rule with nothing in the change behind it is an opinion, not a finding.
+            evidence.length === 0 ||
+            (statedBy !== "commit" && statedBy !== "test" && statedBy !== "code") ||
+            (confidence !== "high" && confidence !== "medium") ||
+            rules.has(rule.toLowerCase()))
+            continue;
+        rules.add(rule.toLowerCase());
+        found.push({
+            rule,
+            beneficiary,
+            trigger,
+            passingExample,
+            failingExample,
+            evidence,
+            statedBy,
+            confidence,
+        });
+    }
+    const covered = [];
+    if (input.existingKnown)
+        for (const item of Array.isArray(answer?.covered) ? answer.covered : []) {
+            const record = (item ?? {});
+            const promiseId = text(record.promiseId, 128);
+            const rule = text(record.rule, 300);
+            if (promiseId === undefined || rule === undefined)
+                continue;
+            if (!PROMISE_ID.test(promiseId) || !input.existingIds.has(promiseId))
+                continue;
+            if (covered.some((kept) => kept.promiseId === promiseId && kept.rule === rule))
+                continue;
+            covered.push({ promiseId, rule });
+            if (covered.length === 10)
+                break;
+        }
+    const notes = typeof answer?.notes === "string" ? answer.notes.trim().slice(0, 600) : "";
+    return {
+        offers: found
+            .slice(0, MAX_OFFERS)
+            .map((rule) => ({ ...rule, question: OFFER_QUESTION })),
+        held: found.slice(MAX_OFFERS),
+        covered,
+        notes,
+    };
+}
+// ---------------------------------------------------------------------------
+// What a person or a session reads.
+function flat(value, limit) {
+    const line = value.replace(/\s+/g, " ").trim();
+    return line.length <= limit ? line : `${line.slice(0, limit - 3).trimEnd()}...`;
+}
+function sentence(value) {
+    const line = value.trim();
+    return /[.!?]$/.test(line) ? line : `${line}.`;
+}
+/** What in the change shows a rule, as the lines say it. */
+function shownBy(rule) {
+    const first = rule.evidence[0];
+    const more = rule.evidence.length - 1;
+    return `Shown by ${first.file}: ${flat(first.shows, 180).replace(/[.!?]+$/, "")}${more > 0 ? `, and ${more} more file${more === 1 ? "" : "s"}` : ""}.`;
+}
+/**
+ * The lines handed to the pushing session, through the hook and as the
+ * command's `question`: each rule, what shows it, and the exact question; then
+ * what the session may do with them, stated once. Nothing when there is no
+ * offer, so a push with nothing to offer hears nothing about it.
+ */
+export function offerLines(result) {
+    if (result.offers.length === 0)
+        return [];
+    const count = result.offers.length;
+    const lines = [
+        `Separately from the push, Balladeer read this change for rules no promise records yet and has ${count === 1 ? "one" : count} to offer:`,
+    ];
+    result.offers.forEach((offer, index) => {
+        lines.push(`${index + 1}. ${sentence(offer.rule)} ${shownBy(offer)} ${offer.question}`);
+    });
+    lines.push(OFFER_INSTRUCTIONS);
+    return lines;
+}
+function sourceName(source, count, directory) {
+    const promises = `${count} promise${count === 1 ? "" : "s"}`;
+    if (source === "connection")
+        return `${promises} read through this repository's connection`;
+    if (source === "directory")
+        return `${promises} from ${directory ?? "the directory named"}`;
+    return `${promises} sealed or mapped in this checkout`;
+}
+/**
+ * What a person reads at a terminal: one line per offer, what an existing
+ * promise already covers and which, and one sentence saying nothing was
+ * recorded. The git pre-push hook prints the same, since whoever ran git
+ * reads it.
+ */
+export function personLines(result, options = {}) {
+    if (result.offers.length === 0 && options.quietWhenEmpty === true)
+        return [];
+    const lines = [];
+    if (result.offers.length === 0)
+        lines.push("Balladeer found no rule in this change that a promise does not already record.");
+    else {
+        lines.push("Balladeer read this change for rules no promise records yet:");
+        result.offers.forEach((offer, index) => {
+            lines.push(`${index + 1}. ${sentence(offer.rule)} ${shownBy(offer)}`);
+        });
+        if (result.held.length > 0)
+            lines.push(`${result.held.length} more ${result.held.length === 1 ? "was" : "were"} found and left out of this list; --json shows ${result.held.length === 1 ? "it" : "them"} under held.`);
+    }
+    for (const covered of result.covered)
+        lines.push(`Already covered by ${covered.promiseId}: ${sentence(flat(covered.rule, 240))}`);
+    lines.push(result.existing.known
+        ? `Compared against ${sourceName(result.existing.source, result.existing.count, options.directory)}.`
+        : "The promises already recorded could not be read, so none of this was compared against them.");
+    lines.push(result.offers.length === 0
+        ? "Nothing was recorded."
+        : "Nothing was recorded; to keep one, ask your coding agent to record it as a promise for your review.");
+    return lines;
+}
+const meaningText = (value) => typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+/** One promise as the reader is told it: title, outcome, who, when, and what it forbids. */
+export function existingFromDocument(document) {
+    const meaning = document.meaning;
+    const outcome = meaningText(meaning.oneSentenceOutcome) ?? meaningText(meaning.observableOutcome);
+    const beneficiary = meaningText(meaning.beneficiary);
+    const trigger = meaningText(meaning.trigger);
+    const failing = meaning.failingExamples
+        .map((example) => meaningText(example.label) ?? flat(example.expectedOutcome, 80))
+        .filter((label) => label !== "");
+    return {
+        promiseId: document.promiseId,
+        title: document.title,
+        ...(outcome === undefined ? {} : { outcome }),
+        ...(beneficiary === undefined ? {} : { beneficiary }),
+        ...(trigger === undefined ? {} : { trigger }),
+        ...(failing.length === 0 ? {} : { failingExamples: failing }),
+    };
+}
+/**
+ * Every promise in a directory of promise files, or in one file.
+ *
+ * Each `*.json` holds one promise in `get_promise`'s shape or a sealed
+ * package's, read with `readPromiseFile`, or an object with a `promises` array
+ * of them, which is how the evaluation's promise sets are laid out. A file
+ * holding neither is skipped and named.
+ */
+export function readPromisesDirectory(path) {
+    let files;
+    try {
+        const stat = statSync(path);
+        if (stat.isFile())
+            files = [path];
+        else if (stat.isDirectory())
+            files = readdirSync(path)
+                .filter((name) => name.endsWith(".json"))
+                .sort()
+                .map((name) => join(path, name));
+        else
+            return { ok: false, reason: `${path} is neither a directory nor a file` };
+    }
+    catch {
+        return { ok: false, reason: `${path} could not be read` };
+    }
+    const promises = new Map();
+    const skipped = [];
+    for (const file of files) {
+        const single = readPromiseFile(file);
+        if (single.ok) {
+            if (!promises.has(single.promise.promiseId))
+                promises.set(single.promise.promiseId, single.promise);
+            continue;
+        }
+        let listed;
+        try {
+            listed = JSON.parse(readFileSync(file, "utf8"))?.promises;
+        }
+        catch {
+            listed = undefined;
+        }
+        if (!Array.isArray(listed)) {
+            skipped.push(file);
+            continue;
+        }
+        for (const entry of listed) {
+            const read = normalizePromise(entry);
+            if (read.ok && !promises.has(read.promise.promiseId))
+                promises.set(read.promise.promiseId, read.promise);
+        }
+    }
+    return { ok: true, promises: [...promises.values()], skipped };
+}
+async function inBatches(items, size, work) {
+    const out = [];
+    for (let at = 0; at < items.length; at += size)
+        out.push(...(await Promise.all(items.slice(at, at + size).map(work))));
+    return out;
+}
+/**
+ * Every agreed promise through the connection: the ids with `list_promises`,
+ * page after page, then each meaning with `get_promise`, which the reader
+ * always marks unattended. Any read that fails fails the whole source, so a
+ * partial list is never presented as the repository's promises.
+ */
+export async function readThroughConnection(reader) {
+    const listed = await reader.list({ max: MAX_EXISTING_PROMISES });
+    if (!listed.ok)
+        return { ok: false, reason: `listing its promises failed: ${listed.reason}` };
+    const ids = listed.ids.slice(0, MAX_EXISTING_PROMISES);
+    const reads = await inBatches(ids, 8, (id) => reader.get(id));
+    const failed = reads.flatMap((read, index) => (read.ok ? [] : [{ id: ids[index], read }]));
+    if (failed.length > 0) {
+        const first = failed[0];
+        return {
+            ok: false,
+            reason: `${failed.length} of ${ids.length} promises could not be read through it (${first.id}: ${flat(first.read.ok ? "" : first.read.reason, 200)})`,
+        };
+    }
+    return {
+        ok: true,
+        promises: reads.flatMap((read) => (read.ok ? [read.promise] : [])),
+        capped: listed.more === true || listed.ids.length > MAX_EXISTING_PROMISES,
+    };
+}
+/** The promises this checkout holds: sealed packages first, then behavior-map excerpts. */
+export function readCheckoutPromises(root) {
+    const found = new Map();
+    const packages = join(root, ".continuity", "packages");
+    let names = [];
+    try {
+        names = readdirSync(packages)
+            .filter((name) => name.endsWith(".json"))
+            .sort();
+    }
+    catch {
+        names = [];
+    }
+    for (const name of names) {
+        const read = readPromiseFile(join(packages, name));
+        if (read.ok)
+            found.set(read.promise.promiseId, existingFromDocument(read.promise));
+    }
+    for (const map of readBehaviorMaps(join(root, ".continuity", "behavior-maps")).maps) {
+        if (found.has(map.promiseId) || map.meaning === undefined)
+            continue;
+        const failing = map.meaning.failingExamples.map((example) => {
+            const colon = example.text.indexOf(": ");
+            return flat(colon > 0 ? example.text.slice(0, colon) : example.text, 80);
+        });
+        found.set(map.promiseId, {
+            promiseId: map.promiseId,
+            title: map.meaning.title,
+            outcome: map.meaning.observableOutcome,
+            ...(failing.length === 0 ? {} : { failingExamples: failing }),
+        });
+    }
+    return [...found.values()];
+}
+/**
+ * The promises already recorded, from the first source that answers: a
+ * directory named by the caller; else this repository's agent connection;
+ * else what the checkout holds. A connection that is missing or fails in any
+ * read falls through to the checkout, and the notes say why.
+ */
+export async function readExistingPromises(input) {
+    const notes = [];
+    if (input.directory !== undefined)
+        return {
+            known: true,
+            source: "directory",
+            promises: input.directory.map(existingFromDocument),
+            notes,
+        };
+    let reader;
+    if (input.reader !== undefined && input.reader !== null)
+        reader = input.reader;
+    else if (input.reader === undefined) {
+        const connection = connectionReader({
+            environment: input.environment,
+            controlPlane: input.controlPlane,
+            cwd: input.root,
+        });
+        if (connection.ok)
+            reader = connection.reader;
+    }
+    if (reader !== undefined) {
+        const read = await readThroughConnection(reader);
+        if (read.ok) {
+            if (read.capped)
+                notes.push(`Only the first ${MAX_EXISTING_PROMISES} promises this repository's connection lists were compared.`);
+            return {
+                known: true,
+                source: "connection",
+                promises: read.promises.map(existingFromDocument),
+                notes,
+            };
+        }
+        notes.push(`This repository's connection could not be used, so the checkout's promises were used instead: ${read.reason}.`);
+    }
+    const checkout = readCheckoutPromises(input.root);
+    if (checkout.length > 0) {
+        notes.push("Only the promises sealed or mapped in this checkout were compared; others may be recorded.");
+        return { known: true, source: "checkout", promises: checkout, notes };
+    }
+    return { known: false, source: "none", promises: [], notes };
+}
+// ---------------------------------------------------------------------------
+// The change.
+const RAW_DIFF_BYTES = 4 * 1024 * 1024;
+/** `git diff --no-color <base> <head>`, bounded as the prompt carries it. */
+export async function readChangeDiff(root, base, head) {
+    const run = await runOwnedProcess({
+        command: "git",
+        args: ["-C", root, "diff", "--no-color", "--no-ext-diff", base, head],
+        cwd: root,
+        env: process.env,
+        timeoutMs: 60_000,
+        maxOutputBytes: RAW_DIFF_BYTES,
+    });
+    return boundDiff(run.stdout, { base, head, totalIsFloor: run.bounded });
+}
+/** The change's commit messages, oldest first, with trailers that carry an address removed. */
+export async function readCommitMessages(root, base, head) {
+    const run = await runOwnedProcess({
+        command: "git",
+        args: ["-C", root, "log", "--no-color", "--reverse", "--format=%B%x00", `${base}..${head}`],
+        cwd: root,
+        env: process.env,
+        timeoutMs: 30_000,
+        maxOutputBytes: 256 * 1024,
+    });
+    return run.stdout
+        .split("\0")
+        .map((message) => message
+        .split("\n")
+        .filter((line) => !/^[A-Za-z][A-Za-z-]*:\s.*<[^>]*@[^>]*>\s*$/.test(line.trim()))
+        .join("\n")
+        .trim())
+        .filter((message) => message !== "")
+        .join("\n---\n");
+}
+// ---------------------------------------------------------------------------
+// One reading.
+/** Tools the reader has: reading files and git's read commands, nothing that writes. */
+const READING_TOOLS = ["Read", "Grep", "Glob", "Bash"];
+const READING_RULES = [
+    "Read",
+    "Grep",
+    "Glob",
+    "Bash(git diff:*)",
+    "Bash(git log:*)",
+    "Bash(git show:*)",
+];
+const REFUSED_RULES = ["Bash(git push:*)", "Bash(gh:*)", "Edit", "Write"];
+function failureMessage(run) {
+    switch (run.reason) {
+        case "no_verified_login":
+            return "no Claude Code signed in through claude.ai, and no Codex signed in with ChatGPT, is on this machine";
+        case "timed_out":
+            return "the reader was still reading when its time ran out";
+        case "aborted":
+            return "the reading was stopped";
+        case "spawn_failed":
+            return `${run.client === "none" ? "the coding agent" : run.client} could not be started`;
+        case "no_json":
+        case "no_answer":
+            return "the reader's answer was not the JSON it was asked for";
+        default:
+            return `the reader stopped without an answer (${run.reason ?? "unknown"})`;
+    }
+}
+/** Read one change for rules no promise records. Never throws for the agent or the machine. */
+export async function readOffers(input) {
+    const diff = await readChangeDiff(input.root, input.base, input.head);
+    const commitMessages = await readCommitMessages(input.root, input.base, input.head);
+    const prompt = offerPrompt({
+        base: input.base,
+        head: input.head,
+        changedFiles: input.files,
+        diff,
+        commitMessages,
+        existing: input.existing.promises,
+        existingKnown: input.existing.known,
+        minutes: Math.max(1, Math.floor(input.timeoutMs / 60_000)),
+    });
+    const run = await (input.runAgent ?? runHeadlessAgent)({
+        client: input.client,
+        ...(input.prefer === undefined ? {} : { prefer: input.prefer }),
+        cwd: input.root,
+        prompt,
+        tools: READING_TOOLS,
+        allowedTools: READING_RULES,
+        disallowedTools: REFUSED_RULES,
+        sandbox: "read-only",
+        timeoutMs: input.timeoutMs,
+        env: input.environment,
+        jsonOutput: true,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    });
+    if (!run.ok || run.client === "none")
+        return { ok: false, reason: run.reason ?? "no_answer", message: failureMessage(run) };
+    const read = readOfferAnswer(run.json, {
+        changedFiles: input.files,
+        existingIds: new Set(input.existing.promises.map((promise) => promise.promiseId)),
+        existingKnown: input.existing.known,
+    });
+    const notes = [
+        ...input.existing.notes,
+        ...(diff.cutLine === undefined
+            ? []
+            : [
+                `The reader was handed ${grouped(diff.shownCharacters)} of ${diff.totalIsFloor ? "more than " : ""}${grouped(diff.totalCharacters)} characters of the diff.`,
+            ]),
+        ...(read.notes === "" ? [] : [read.notes]),
+    ];
+    return {
+        ok: true,
+        result: {
+            schemaVersion: OFFERS_SCHEMA_VERSION,
+            brief: OFFER_BRIEF_REVISION,
+            base: input.base,
+            head: input.head,
+            offers: read.offers,
+            held: read.held,
+            covered: read.covered,
+            existing: {
+                known: input.existing.known,
+                count: input.existing.promises.length,
+                source: input.existing.source,
+            },
+            notes: notes.join(" "),
+            agent: {
+                client: run.client,
+                model: run.model ?? "",
+                durationMs: run.durationMs,
+                inputTokens: run.inputTokens ?? 0,
+                outputTokens: run.outputTokens ?? 0,
+            },
+        },
+    };
+}
+/**
+ * Whether a change repairs something, read from what its author wrote: a
+ * commit whose subject is a fix, a hotfix or a revert by the usual convention,
+ * or says in words that it fixes, restores or reverts, or names a regression.
+ *
+ * The first measurement (29 September 2026, 24 real regressions) is why this
+ * is the default gate. Read at the fix, a change offered the rule that had
+ * broken in 20 cases of 24, and as its first offer in 18. Read at the change
+ * that first built the behavior, it offered that rule in 3 of 23, while
+ * offering two rules or more on almost every feature. A repair is where a rule
+ * has just shown what losing it costs; everywhere else the reader is mostly
+ * guessing which of many rules will matter, and the person is asked too often.
+ * No model is asked: the subject line is what the author said.
+ */
+export function isRepairChange(messages) {
+    const subjects = messages
+        .split("\n---\n")
+        .map((message) => message.split("\n")[0]?.trim() ?? "")
+        .filter((subject) => subject !== "");
+    return subjects.some((subject) => /^(fix|hotfix|revert)(\([^)]*\))?!?:/i.test(subject) ||
+        /^revert\b/i.test(subject) ||
+        /\b(fix(es|ed)?|hotfix(es)?|regression|regressed|restore[sd]?|revert(s|ed)?)\b/i.test(subject));
+}
+/** The first `max` offers stay offers; the rest join what was held, without their question. */
+export function limitOffers(result, max) {
+    if (result.offers.length <= max)
+        return result;
+    const over = result.offers.slice(max).map((offer) => ({
+        rule: offer.rule,
+        beneficiary: offer.beneficiary,
+        trigger: offer.trigger,
+        passingExample: offer.passingExample,
+        failingExample: offer.failingExample,
+        evidence: offer.evidence,
+        statedBy: offer.statedBy,
+        confidence: offer.confidence,
+    }));
+    return { ...result, offers: result.offers.slice(0, max), held: [...over, ...result.held] };
+}
+/**
+ * The same reading, for the push hook: the change is already identified, and
+ * what comes back is the lines the pushing session or person is handed. Any
+ * failure, a missing login or a reading still running at the deadline is no
+ * lines at all: finding rules never holds or fails a push.
+ */
+export async function offersForPush(input) {
+    const now = input.now ?? Date.now;
+    try {
+        if (input.files.length === 0)
+            return [];
+        // Decided before anything is read: a push that repairs nothing costs no
+        // reading, no tokens and no question.
+        if (input.policy === "fixes" &&
+            !isRepairChange(await readCommitMessages(input.root, input.base, input.head)))
+            return [];
+        const existing = await readExistingPromises({
+            root: input.root,
+            ...(input.reader === undefined ? {} : { reader: input.reader }),
+            environment: input.environment,
+            controlPlane: input.controlPlane,
+        });
+        const remaining = input.deadline - now();
+        if (remaining < 1000 || input.signal.aborted)
+            return [];
+        const reading = await readOffers({
+            root: input.root,
+            base: input.base,
+            head: input.head,
+            files: input.files,
+            existing,
+            client: input.client,
+            ...(input.host === "git" ? {} : { prefer: input.host }),
+            timeoutMs: remaining,
+            environment: input.environment,
+            signal: input.signal,
+            ...(input.runAgent === undefined ? {} : { runAgent: input.runAgent }),
+        });
+        if (!reading.ok || input.signal.aborted)
+            return [];
+        const handed = limitOffers(reading.result, input.max ?? MAX_OFFERS);
+        return input.host === "git"
+            ? personLines(handed, { quietWhenEmpty: true })
+            : offerLines(handed);
+    }
+    catch {
+        return [];
+    }
+}
+export const OFFERS_USAGE = `  ${CLI_INVOCATION} offers [--base <ref>] [--head <ref>] [--json] [--repo <root>]
+                  [--promises-dir <dir>] [--client auto|claude|codex] [--timeout <seconds>]
+      Read this change for rules it establishes that no promise records yet,
+      on your own Claude Code or Codex login, and list at most three, each with
+      the files in the change that show it. It records nothing and stores
+      nothing: to keep one, ask your coding agent to record it as a promise for
+      your review. The promises already recorded come from --promises-dir,
+      else this repository's Balladeer connection, else the promises sealed or
+      mapped in this checkout. The change runs from the fork point with the
+      remote default branch to HEAD unless named. --json prints the result.
+`;
+export function parseOffersArguments(argv) {
+    const args = [...argv];
+    let base;
+    let head;
+    let json = false;
+    let repo;
+    let promisesDir;
+    let client = "auto";
+    let timeoutSeconds = DEFAULT_OFFER_TIMEOUT_SECONDS;
+    const value = (flag, inline) => {
+        const next = inline ?? args.shift();
+        if (next === undefined || next === "")
+            throw new StoreError("usage", `${flag} needs a value.`);
+        return next;
+    };
+    while (args.length > 0) {
+        const arg = args.shift();
+        if (!arg.startsWith("--"))
+            throw new StoreError("usage", `offers takes no bare arguments: ${arg}.`);
+        const [name, ...rest] = arg.split("=");
+        const inline = rest.length > 0 ? rest.join("=") : undefined;
+        if (name === "--base")
+            base = value(name, inline);
+        else if (name === "--head")
+            head = value(name, inline);
+        else if (name === "--json")
+            json = true;
+        else if (name === "--repo")
+            repo = value(name, inline);
+        else if (name === "--promises-dir")
+            promisesDir = value(name, inline);
+        else if (name === "--client") {
+            const requested = value(name, inline);
+            if (requested !== "auto" && requested !== "claude" && requested !== "codex")
+                throw new StoreError("usage", "--client needs auto, claude or codex.");
+            client = requested;
+        }
+        else if (name === "--timeout") {
+            const seconds = Number(value(name, inline));
+            if (!Number.isFinite(seconds) || seconds <= 0 || seconds > 3600)
+                throw new StoreError("usage", "--timeout needs a number of seconds from 1 to 3600.");
+            timeoutSeconds = seconds;
+        }
+        else
+            throw new StoreError("usage", `Unknown option ${arg} for offers.`);
+    }
+    return {
+        ...(base === undefined ? {} : { base }),
+        ...(head === undefined ? {} : { head }),
+        json,
+        ...(repo === undefined ? {} : { repo }),
+        ...(promisesDir === undefined ? {} : { promisesDir }),
+        client,
+        timeoutSeconds,
+    };
+}
+/** `balladeer offers`, from arguments already parsed. */
+export async function runOffers(options) {
+    const { args } = options;
+    const deps = options.deps ?? {};
+    const step = (fields) => {
+        if (args.json)
+            options.write(`${JSON.stringify(fields)}\n`);
+        else if (fields.exitCode === 0)
+            options.write(`${fields.message}\n`);
+        else
+            options.error(`${fields.message}\n`);
+        return fields.exitCode;
+    };
+    const refuse = (reason, message) => {
+        if (args.json)
+            options.write(`${JSON.stringify({ step: "error", reason, message, changed: false, exitCode: 4 })}\n`);
+        else
+            options.error(`${message}\n`);
+        return 4;
+    };
+    // A judge or a reader's own agent runs with this set; reading offers from
+    // inside one would start another reading all over again.
+    if (options.environment[JUDGE_ACTIVE_VARIABLE] === "1")
+        return refuse("nested_run", "Balladeer does not read a change for offers from inside its own judge or reader runs.");
+    const root = args.repo !== undefined ? resolve(options.cwd, args.repo) : await repositoryRoot(options.cwd);
+    if (root === undefined || (await repositoryRoot(root)) === undefined)
+        return refuse("not_a_repository", "This is not a git repository, so there is no change to read.");
+    const head = await resolveCommit(root, args.head ?? "HEAD");
+    if (head === undefined)
+        return refuse("no_head", `${args.head ?? "HEAD"} is not a commit here, so nothing was read.`);
+    const base = args.base !== undefined ? await resolveCommit(root, args.base) : await defaultBase(root, head);
+    if (base === undefined)
+        return refuse("no_base", `${args.base ?? "The base"} is not a commit here, so nothing was read.`);
+    let directory;
+    let directoryNote;
+    if (args.promisesDir !== undefined) {
+        const path = resolve(options.cwd, args.promisesDir);
+        const read = readPromisesDirectory(path);
+        if (!read.ok)
+            return refuse("promises_unreadable", `--promises-dir: ${read.reason}.`);
+        directory = read.promises;
+        if (read.skipped.length > 0)
+            directoryNote = `${read.skipped.length} file${read.skipped.length === 1 ? "" : "s"} in ${args.promisesDir} held no promise and ${read.skipped.length === 1 ? "was" : "were"} skipped.`;
+    }
+    const files = base === head ? [] : await changedFiles(root, base, head);
+    if (files.length === 0)
+        return step({
+            step: "offers",
+            status: "nothing_to_read",
+            reason: "empty_change",
+            message: "Nothing to read: the change is empty. Nothing was recorded.",
+            exitCode: 0,
+        });
+    const existing = await readExistingPromises({
+        root,
+        ...(directory === undefined ? {} : { directory }),
+        ...(deps.reader === undefined ? {} : { reader: deps.reader }),
+        environment: options.environment,
+        controlPlane: options.controlPlane,
+    });
+    const reading = await readOffers({
+        root,
+        base,
+        head,
+        files,
+        existing: directoryNote === undefined
+            ? existing
+            : { ...existing, notes: [directoryNote, ...existing.notes] },
+        client: args.client,
+        timeoutMs: args.timeoutSeconds * 1000,
+        environment: options.environment,
+        ...(deps.runAgent === undefined ? {} : { runAgent: deps.runAgent }),
+    });
+    if (!reading.ok) {
+        const exitCode = reading.reason === "no_verified_login" ? 3 : 5;
+        return step({
+            step: "offers",
+            status: "not_read",
+            reason: reading.reason,
+            message: `No rules were read from this change: ${reading.message}. Nothing was recorded.`,
+            exitCode,
+        });
+    }
+    if (args.json)
+        options.write(`${JSON.stringify(reading.result)}\n`);
+    else
+        options.write(`${personLines(reading.result, args.promisesDir === undefined ? {} : { directory: args.promisesDir }).join("\n")}\n`);
+    return 0;
+}
+/** `balladeer offers ...` from raw arguments, as `cli.ts` hands them over. */
+export async function offersCommand(argv, io) {
+    let args;
+    let controlPlane;
+    try {
+        args = parseOffersArguments(argv);
+        controlPlane = normalizeControlPlane(io.environment.BALLADEER_CONTROL_PLANE?.trim() || DEFAULT_CONTROL_PLANE);
+    }
+    catch (error) {
+        io.error(`${error instanceof Error ? error.message : String(error)}\n\n${OFFERS_USAGE}`);
+        return 4;
+    }
+    return runOffers({
+        args,
+        cwd: io.cwd,
+        environment: io.environment,
+        controlPlane,
+        write: io.write,
+        error: io.error,
+    });
+}