balladeer 0.0.5 → 1.0.1

package/dist/commands/prepare.js

@@ -0,0 +1,217 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { callAgentTool, noAgentCredentialSentence, selectAgent } from "../agent.js";
+import { inReadersZone } from "../local-time.js";
+import { commandLine } from "../release.js";
+import { repositoryHint } from "../repository.js";
+import { StoreError, readCredentials } from "../store.js";
+import {} from "../wire.js";
+const PROMISE_ID = /^prom_[a-z0-9]{8,64}$/;
+/**
+ * The tool's argument, as the person in front of this terminal would type it.
+ *
+ * `prepare_qualification` takes `again: true`, and its refusal says so, which is
+ * right for the agent that called the tool and wrong for the reader of this
+ * command: `balladeer prepare <id> again` is a usage error, and the flag is
+ * `--again`. The sentence is relayed verbatim otherwise, so this is the one word
+ * in it that has two correct spellings depending on who is reading.
+ */
+const TOOL_ARGUMENT_FOR_AGAIN = /`again(?::\s*true)?`/g;
+/**
+ * A refusal Balladeer wrote, as this terminal has to say it.
+ *
+ * Two changes and no others. The instants move onto the reader's own clock,
+ * because the server writes UTC and "already prepared by Robert Clark on
+ * 2026-09-07T18:05:10.698Z" reached somebody whose clock said two in the
+ * afternoon. And the argument is named the way this command takes it. Every
+ * other word, including what to do next and why, is the server's.
+ */
+export function atThisTerminal(text) {
+    return inReadersZone(text).replace(TOOL_ARGUMENT_FOR_AGAIN, "`--again`");
+}
+/**
+ * The six keys the sealed run reads, and nothing else.
+ *
+ * The runner rejects an unknown field outright, so a metadata file that carried
+ * a helpful comment, a timestamp, or the whole packet would fail the customer's
+ * protected run for a reason that had nothing to do with their behavior. This
+ * command therefore writes the packet's own `qualificationMetadata` object and
+ * refuses to write anything it does not recognise.
+ */
+const METADATA_KEYS = [
+    "schemaVersion",
+    "workspaceLocator",
+    "receiptId",
+    "revisionId",
+    "bindingId",
+    "workflowDigest",
+];
+export function readQualificationMetadata(structured) {
+    const packet = structured !== null && typeof structured === "object"
+        ? structured.packet
+        : undefined;
+    const metadata = packet !== null && typeof packet === "object"
+        ? packet.qualificationMetadata
+        : undefined;
+    if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) {
+        return { ok: false, reason: "the answer carried no qualification metadata" };
+    }
+    const record = metadata;
+    const unexpected = Object.keys(record).filter((key) => !METADATA_KEYS.includes(key));
+    if (unexpected.length > 0) {
+        return {
+            ok: false,
+            reason: `the metadata carries ${unexpected.join(", ")}, which the sealed run refuses, so nothing was written`,
+        };
+    }
+    const missing = METADATA_KEYS.filter((key) => typeof record[key] !== "string");
+    if (missing.length > 0) {
+        return { ok: false, reason: `the metadata is missing ${missing.join(", ")}` };
+    }
+    return {
+        ok: true,
+        value: Object.fromEntries(METADATA_KEYS.map((key) => [key, record[key]])),
+    };
+}
+/**
+ * Where the file goes, refusing any path that would leave this repository.
+ *
+ * The path comes off the server's answer, and the whole point of this command is
+ * that it writes a file the person did not type. A server that answered with
+ * `../../etc/something` would otherwise have this command write there, so the
+ * resolved path has to stay under the directory the command was run in.
+ */
+export function metadataDestination(cwd, metadataPath) {
+    if (isAbsolute(metadataPath)) {
+        return { ok: false, reason: "the path Balladeer answered with is absolute" };
+    }
+    const root = resolve(cwd);
+    const destination = resolve(join(root, metadataPath));
+    const inside = relative(root, destination);
+    if (inside.startsWith("..") || isAbsolute(inside)) {
+        return { ok: false, reason: "the path Balladeer answered with leaves this repository" };
+    }
+    return { ok: true, path: destination };
+}
+function stringList(structured, field) {
+    if (structured === null || typeof structured !== "object")
+        return [];
+    const value = structured[field];
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+}
+/**
+ * Prepares the one-time qualification setup for one promise, and writes the file
+ * where the sealed run reads it.
+ *
+ * It runs over this repository's own agent connection, which is what makes it
+ * usable at all: preparing a qualification setup is the agent's job, and the
+ * setup session that paired the machine expires. There is no sign-off here and
+ * no code to paste. Agreeing the meaning was the person's act; building the
+ * check that proves it is this command's caller's.
+ *
+ * The file is written once. A second run while nobody has published against the
+ * first packet is refused, naming who prepared it and when, and `--again` mints
+ * a replacement that invalidates the earlier one on the server as well as
+ * overwriting the file here.
+ */
+export async function runPrepare(options) {
+    const emit = (step) => {
+        if (options.json)
+            options.write(`${JSON.stringify(step)}\n`);
+    };
+    const fail = (reason, message, exitCode) => {
+        if (options.json)
+            emit({ step: "error", reason, message, changed: false, exitCode });
+        else
+            options.write(`${message}\n`);
+        return exitCode;
+    };
+    if (!PROMISE_ID.test(options.promiseId)) {
+        return fail("usage", `"${options.promiseId}" is not a promise id. A promise id looks like prom_ followed by letters and digits, and every promise page has a control that copies its own.`, 4);
+    }
+    let credentials;
+    try {
+        credentials = readCredentials(options.environment);
+    }
+    catch (error) {
+        return fail(error instanceof StoreError ? error.code : "credential_store_unusable", error instanceof StoreError ? error.message : String(error), 4);
+    }
+    const selection = selectAgent(credentials.agents, options.controlPlane, options.repository, options.repo ?? repositoryHint(options.cwd));
+    if (selection.kind === "refused") {
+        if (selection.missingFor !== undefined) {
+            return fail("no_agent_credential_on_this_machine", `${noAgentCredentialSentence(selection.missingFor)} Nothing was prepared.`, 4);
+        }
+        return fail("no_agent_connection", `${selection.reason} Run \`${commandLine(null, "setup")}\` in this repository first. Nothing was prepared.`, 4);
+    }
+    const { agent } = selection;
+    const call = await callAgentTool(agent, "prepare_qualification", {
+        promiseId: options.promiseId,
+        again: options.again,
+    });
+    switch (call.kind) {
+        case "endpoint_refused":
+            return fail("agent_endpoint_unsafe", `${call.reason} Nothing was prepared.`, 4);
+        case "unreachable":
+            return fail("control_plane_unreachable", `Balladeer could not be reached at ${options.controlPlane}. Nothing was prepared.`, 5);
+        case "client_too_old":
+            return fail("client_too_old", `This copy of the Balladeer command is too old for ${options.controlPlane}. Update it with: ${call.update}`, 3);
+        case "unauthorized":
+            return fail("agent_connection_revoked", `Balladeer refused this repository's agent connection: it was revoked, or the repository it was bound to is no longer enrolled. Retrying will not help. Run \`${commandLine(null, "setup")}\` here again, or issue a new connection at ${options.controlPlane}/setup. Nothing was prepared.`, 5);
+        case "tool_refusal":
+            // The server's own sentence, which names what to do next: use the packet
+            // that already exists, wait for the owner to agree, or run this again with
+            // --again. Rewriting it here would lose the part the person has to read,
+            // so `atThisTerminal` changes only the two things the server could not
+            // know: which clock the reader is on, and that they type a flag.
+            return fail("prepare_refused", `Balladeer refused this: ${atThisTerminal(call.text)}`, 5);
+        case "http":
+            return fail("prepare_failed", `Balladeer answered ${call.status} to this request. Nothing was prepared.`, 5);
+        case "malformed":
+            return fail("prepare_failed", "Balladeer could not prepare a qualification setup.", 5);
+        case "result":
+            break;
+    }
+    const structured = call.structured;
+    const metadataPath = typeof structured.metadataPath === "string" ? structured.metadataPath : "";
+    if (metadataPath === "") {
+        return fail("prepare_failed", "Balladeer could not prepare a qualification setup.", 5);
+    }
+    const destination = metadataDestination(options.cwd, metadataPath);
+    if (!destination.ok) {
+        // Minted on the server and not written here. Said plainly rather than
+        // silently: the packet is one-time, so somebody has to know it was spent.
+        return fail("metadata_path_unsafe", `Balladeer prepared the qualification setup, but ${destination.reason}, so nothing was written to disk. Nothing else was changed.`, 5);
+    }
+    const metadata = readQualificationMetadata(call.structured);
+    if (!metadata.ok) {
+        return fail("metadata_unusable", `Balladeer prepared the qualification setup, but ${metadata.reason}, so nothing was written to disk.`, 5);
+    }
+    try {
+        mkdirSync(dirname(destination.path), { recursive: true });
+        writeFileSync(destination.path, `${JSON.stringify(metadata.value, null, 2)}\n`, "utf8");
+    }
+    catch (error) {
+        return fail("metadata_unwritable", `Balladeer prepared the qualification setup, but ${metadataPath} could not be written: ${error instanceof Error ? error.message : String(error)}`, 4);
+    }
+    const superseded = typeof structured.supersededPackets === "number" ? structured.supersededPackets : 0;
+    emit({
+        step: "qualification",
+        status: "prepared",
+        promiseId: options.promiseId,
+        metadataPath,
+        supersededPackets: superseded,
+    });
+    if (!options.json) {
+        options.write(`${metadataPath}\n`);
+        if (superseded > 0) {
+            options.write(`The qualification setup prepared earlier is no longer valid: a run that publishes its identities is refused.\n`);
+        }
+        options.write("Next: build this promise's verifier, seal it, and push to the default branch.\n");
+        options.write("Protection starts by itself when that run qualifies. Nobody activates anything, and this file is removed in an ordinary follow-up change once the receipt appears.\n");
+        for (const step of stringList(call.structured, "nextSteps"))
+            options.write(`  ${step}\n`);
+    }
+    return 0;
+}

package/dist/commands/propose.d.ts

@@ -0,0 +1,69 @@
+export type ProposeOptions = Readonly<{
+    controlPlane: string;
+    json: boolean;
+    file?: string;
+    /** The repository whose connection to use, named as `owner/name`. */
+    repo?: string;
+    /** The repository whose connection to use, named by id, as `mcp` takes it. */
+    repository?: string;
+    environment: NodeJS.ProcessEnv;
+    cwd: string;
+    write: (text: string) => void;
+}>;
+export type TeachBackRequest = Readonly<{
+    explicitIntent: string;
+    teachBack: Readonly<{
+        meaning: Record<string, unknown>;
+        unresolvedQuestions?: unknown;
+        proposedOwnerId?: unknown;
+        /** How sure whoever wrote this file was, 0 to 1. Read, never assumed. */
+        confidence: number;
+        /**
+         * What going wrong looks like, in the words the person used. Required, and
+         * refused here as well as by the server: a behavior with no sentence of that
+         * shape has no failing case a check could ever catch, and a promise that can
+         * never fail is worse than no promise at all.
+         */
+        wrongOutcome: string;
+        /** The one thing least certain, which the review page reads instead of the
+         * confidence number. Optional: silence here means nothing was said. */
+        leastSure?: unknown;
+    }>;
+}>;
+/**
+ * The shape check that happens on the developer's machine, and the body it
+ * builds.
+ *
+ * `--file` reads whatever path it is handed, and an agent that mistypes one
+ * would otherwise upload a `.env`, a source file, or a log to a service whose
+ * whole boundary is that it never receives those. Refusing here means the wrong
+ * file never leaves the machine, rather than leaving it and being refused.
+ *
+ * So this returns the exact object to send rather than a verdict on the file.
+ * Spreading the parsed file into the request was the same mistake in a quieter
+ * form: whatever else the file happened to carry travelled with it, and the
+ * strict schema on the other side is a refusal after the fact, not a boundary.
+ */
+export declare function readTeachBackFile(raw: string): Readonly<{
+    ok: true;
+    value: TeachBackRequest;
+}> | Readonly<{
+    ok: false;
+    reason: string;
+}>;
+/**
+ * Proposes one promise over this repository's own agent connection.
+ *
+ * It used to go over the delegated setup session, which lives for a bounded time
+ * and is meant for setting Balladeer up. That made proposing something a person
+ * could only do for a while after pairing: the credential expired, and a command
+ * whose whole job is "propose this" answered "run setup again". The connection
+ * this uses instead is the one setup issued for this repository, the same one
+ * the agent host forwards, and it does not expire.
+ *
+ * Nothing widens by moving: the call is `propose_promise` on the MCP endpoint,
+ * so it is authenticated as the agent principal, bound to that one repository,
+ * and refused everything except proposing. It lands as a candidate awaiting a
+ * named person's agreement, and nothing this command can do agrees to it.
+ */
+export declare function runPropose(options: ProposeOptions): Promise<number>;

package/dist/commands/propose.js

@@ -0,0 +1,284 @@
+import { readFileSync } from "node:fs";
+import { callAgentTool, noAgentCredentialSentence, selectAgent, structuredString, } from "../agent.js";
+import { proposalReviewLink } from "../client.js";
+import { commandLine } from "../release.js";
+import { repositoryHint } from "../repository.js";
+import { StoreError, readCredentials } from "../store.js";
+import {} from "../wire.js";
+const MAX_FILE_BYTES = 64 * 1024;
+/**
+ * Every field the server's schema requires with no default. It is every
+ * required key of `semanticMeaningSchema` and nothing else: three of these were
+ * missing once, and a file without them passed this gate, left the machine, and
+ * was refused on the other side, which is exactly what this check exists to
+ * prevent. `refactorExamples` is deliberately absent because the schema now
+ * accepts a meaning without one; a file that still carries one is still sent.
+ */
+const REQUIRED_MEANING_FIELDS = [
+    "title",
+    "beneficiary",
+    "trigger",
+    "preconditions",
+    "observableOutcome",
+    "allowedVariations",
+    "nonGoals",
+    "passingExamples",
+    "failingExamples",
+    "scope",
+];
+/** The only keys this command sends, at each of the two levels it reads. */
+const ALLOWED_TOP_LEVEL = ["teachBack", "explicitIntent"];
+const ALLOWED_TEACH_BACK = [
+    "meaning",
+    "unresolvedQuestions",
+    "proposedOwnerId",
+    "confidence",
+    "wrongOutcome",
+    "leastSure",
+];
+function unexpectedKeys(value, allowed) {
+    return Object.keys(value).filter((key) => !allowed.includes(key));
+}
+/**
+ * The shape check that happens on the developer's machine, and the body it
+ * builds.
+ *
+ * `--file` reads whatever path it is handed, and an agent that mistypes one
+ * would otherwise upload a `.env`, a source file, or a log to a service whose
+ * whole boundary is that it never receives those. Refusing here means the wrong
+ * file never leaves the machine, rather than leaving it and being refused.
+ *
+ * So this returns the exact object to send rather than a verdict on the file.
+ * Spreading the parsed file into the request was the same mistake in a quieter
+ * form: whatever else the file happened to carry travelled with it, and the
+ * strict schema on the other side is a refusal after the fact, not a boundary.
+ */
+export function readTeachBackFile(raw) {
+    if (Buffer.byteLength(raw, "utf8") > MAX_FILE_BYTES) {
+        return { ok: false, reason: "the file is larger than 64 KiB" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, reason: "the file is not JSON" };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { ok: false, reason: "the file is not a JSON object" };
+    }
+    const extra = unexpectedKeys(parsed, ALLOWED_TOP_LEVEL);
+    if (extra.length > 0) {
+        return {
+            ok: false,
+            reason: `it carries ${extra.join(", ")}, which a proposal does not have and this command will not send`,
+        };
+    }
+    const value = parsed;
+    const teachBack = value.teachBack;
+    if (teachBack === undefined || typeof teachBack !== "object" || Array.isArray(teachBack)) {
+        return { ok: false, reason: "it has no teachBack object" };
+    }
+    const extraTeachBack = unexpectedKeys(teachBack, ALLOWED_TEACH_BACK);
+    if (extraTeachBack.length > 0) {
+        return {
+            ok: false,
+            reason: `teachBack carries ${extraTeachBack.join(", ")}, which this command will not send`,
+        };
+    }
+    const meaning = teachBack.meaning;
+    if (meaning === undefined || typeof meaning !== "object" || Array.isArray(meaning)) {
+        return { ok: false, reason: "it has no teachBack.meaning" };
+    }
+    const missing = REQUIRED_MEANING_FIELDS.filter((field) => meaning[field] === undefined);
+    if (missing.length > 0) {
+        return { ok: false, reason: `teachBack.meaning is missing ${missing.join(", ")}` };
+    }
+    if (typeof value.explicitIntent !== "string" || value.explicitIntent.trim().length === 0) {
+        return { ok: false, reason: "it has no explicitIntent saying why this is being proposed" };
+    }
+    // Read from the file, never assumed. Every proposal this command ever filed
+    // was recorded at 1 because 1 was written here in the code, so the number an
+    // owner reads on the review page said nothing about this proposal: it said
+    // what the constant said. A file that will not state how sure its author was
+    // is refused rather than answered on their behalf.
+    const confidence = teachBack.confidence;
+    if (typeof confidence !== "number" || !Number.isFinite(confidence)) {
+        return {
+            ok: false,
+            reason: "teachBack.confidence is missing. Say how sure you are that this is the behavior the person meant, as a number from 0 to 1",
+        };
+    }
+    if (confidence < 0 || confidence > 1) {
+        return { ok: false, reason: "teachBack.confidence must be between 0 and 1" };
+    }
+    // The server refuses a proposal that cannot say what going wrong looks like,
+    // and it is right to: a behavior with no sentence of that shape has no failing
+    // case a check could ever catch. Refusing here as well means the person who
+    // wrote the file reads why on their own machine rather than after a round trip.
+    const wrongOutcome = teachBack.wrongOutcome;
+    if (typeof wrongOutcome !== "string" || wrongOutcome.trim().length === 0) {
+        return {
+            ok: false,
+            reason: 'teachBack.wrongOutcome is missing. Say what going wrong looks like, in the words the person used and as a must-not: "a second payment must not go out". If no sentence of that shape exists, nothing could ever fail this promise, so do not propose it',
+        };
+    }
+    if (teachBack.leastSure !== undefined && typeof teachBack.leastSure !== "string") {
+        return { ok: false, reason: "teachBack.leastSure must be one sentence of text" };
+    }
+    return {
+        ok: true,
+        value: {
+            explicitIntent: value.explicitIntent,
+            teachBack: {
+                meaning,
+                confidence,
+                wrongOutcome,
+                ...(teachBack.leastSure === undefined ? {} : { leastSure: teachBack.leastSure }),
+                ...(teachBack.unresolvedQuestions === undefined
+                    ? {}
+                    : { unresolvedQuestions: teachBack.unresolvedQuestions }),
+                ...(teachBack.proposedOwnerId === undefined
+                    ? {}
+                    : { proposedOwnerId: teachBack.proposedOwnerId }),
+            },
+        },
+    };
+}
+/**
+ * The repository a proposal is about, taken from the connection rather than from
+ * the file.
+ *
+ * A teach-back file names surfaces and labels; it has never named a repository
+ * id, because the setup route stamped one from the repository the request
+ * resolved. The connection is now what resolves it, so it stamps it: a file that
+ * carried some other repository's id cannot reach that repository, because this
+ * overwrites it and the server refuses a candidate whose scope does not match
+ * the principal's repository anyway.
+ */
+function scopedMeaning(meaning, repositoryId) {
+    const scope = meaning.scope;
+    if (scope === null || typeof scope !== "object" || Array.isArray(scope))
+        return meaning;
+    return { ...meaning, scope: { ...scope, repositoryId } };
+}
+/**
+ * Proposes one promise over this repository's own agent connection.
+ *
+ * It used to go over the delegated setup session, which lives for a bounded time
+ * and is meant for setting Balladeer up. That made proposing something a person
+ * could only do for a while after pairing: the credential expired, and a command
+ * whose whole job is "propose this" answered "run setup again". The connection
+ * this uses instead is the one setup issued for this repository, the same one
+ * the agent host forwards, and it does not expire.
+ *
+ * Nothing widens by moving: the call is `propose_promise` on the MCP endpoint,
+ * so it is authenticated as the agent principal, bound to that one repository,
+ * and refused everything except proposing. It lands as a candidate awaiting a
+ * named person's agreement, and nothing this command can do agrees to it.
+ */
+export async function runPropose(options) {
+    const emit = (step) => {
+        if (options.json)
+            options.write(`${JSON.stringify(step)}\n`);
+    };
+    const fail = (reason, message, exitCode) => {
+        if (options.json)
+            emit({ step: "error", reason, message, changed: false, exitCode });
+        else
+            options.write(`${message}\n`);
+        return exitCode;
+    };
+    if (!options.file) {
+        return fail("usage", "Give a proposal file: balladeer propose --file <path>.", 4);
+    }
+    let raw;
+    try {
+        raw = readFileSync(options.file, "utf8");
+    }
+    catch {
+        return fail("teachback_unreadable", `I could not read ${options.file}.`, 4);
+    }
+    const parsed = readTeachBackFile(raw);
+    if (!parsed.ok) {
+        return fail("teachback_malformed", `${options.file} is not a proposal: ${parsed.reason}. Nothing was sent.`, 4);
+    }
+    let credentials;
+    try {
+        credentials = readCredentials(options.environment);
+    }
+    catch (error) {
+        return fail(error instanceof StoreError ? error.code : "credential_store_unusable", error instanceof StoreError ? error.message : String(error), 4);
+    }
+    const selection = selectAgent(credentials.agents, options.controlPlane, options.repository, options.repo ?? repositoryHint(options.cwd));
+    if (selection.kind === "refused") {
+        // The repository being connected somewhere else is not this machine holding
+        // a credential, and a proposal runs over the one this machine holds. Said in
+        // its own sentence, before anything is sent, because the remedy is to
+        // connect this machine rather than to pair again: a setup session, however
+        // fresh, cannot carry a proposal.
+        if (selection.missingFor !== undefined) {
+            return fail("no_agent_credential_on_this_machine", `${noAgentCredentialSentence(selection.missingFor)} Nothing was sent.`, 4);
+        }
+        return fail("no_agent_connection", `${selection.reason} Run \`${commandLine(null, "setup")}\` in this repository first. Nothing was sent.`, 4);
+    }
+    const { agent } = selection;
+    const call = await callAgentTool(agent, "propose_promise", {
+        // A person or an agent ran this command against a file that says why. That
+        // is the explicit act the server requires; nothing here infers one.
+        explicitHumanAction: true,
+        source: "protect_behavior",
+        explicitIntent: parsed.value.explicitIntent,
+        meaning: scopedMeaning(parsed.value.teachBack.meaning, agent.repositoryId),
+        unresolvedQuestions: parsed.value.teachBack.unresolvedQuestions ?? [],
+        ...(parsed.value.teachBack.proposedOwnerId === undefined
+            ? {}
+            : { proposedOwnerId: parsed.value.teachBack.proposedOwnerId }),
+        confidence: parsed.value.teachBack.confidence,
+        wrongOutcome: parsed.value.teachBack.wrongOutcome,
+        ...(parsed.value.teachBack.leastSure === undefined
+            ? {}
+            : { leastSure: parsed.value.teachBack.leastSure }),
+    });
+    switch (call.kind) {
+        case "endpoint_refused":
+            return fail("agent_endpoint_unsafe", `${call.reason} Nothing was sent.`, 4);
+        case "unreachable":
+            return fail("control_plane_unreachable", `Balladeer could not be reached at ${options.controlPlane}. Nothing was changed.`, 5);
+        case "client_too_old":
+            return fail("client_too_old", `This copy of the Balladeer command is too old for ${options.controlPlane}. Update it with: ${call.update}`, 3);
+        case "unauthorized":
+            return fail("agent_connection_revoked", `Balladeer refused this repository's agent connection: it was revoked, or the repository it was bound to is no longer enrolled. Retrying will not help. Run \`${commandLine(null, "setup")}\` here again, or issue a new connection at ${options.controlPlane}/setup. Nothing was recorded.`, 5);
+        case "tool_refusal":
+            return fail("propose_refused", `Balladeer refused this proposal: ${call.text}`, 5);
+        case "http":
+            return fail("propose_failed", `Balladeer answered ${call.status} to this proposal. Nothing was recorded.`, 5);
+        case "malformed":
+            return fail("propose_failed", "Balladeer could not record this proposal.", 5);
+        case "result":
+            break;
+    }
+    const candidateId = structuredString(call.structured, "id");
+    const status = structuredString(call.structured, "status");
+    if (candidateId === undefined) {
+        return fail("propose_failed", "Balladeer could not record this proposal.", 5);
+    }
+    if (status !== "pending_review") {
+        // The server matched something already on file rather than recording a new
+        // proposal, which is what the setup route used to answer as a conflict. It
+        // is reported as one here too: sending a person to agree to a record that
+        // was already decided is worse than saying nothing was recorded.
+        return fail("proposal_not_pending", `Balladeer matched an existing proposal, ${candidateId}, which is ${status ?? "in an unreported state"}. Nothing new was recorded.`, 5);
+    }
+    // The review link is built from the address this copy paired with. The tool
+    // answers with an id and no link at all, so there is nothing here a
+    // misconfigured public base URL could redirect.
+    const review = proposalReviewLink(options.controlPlane, candidateId);
+    emit({ step: "promise", status: "proposed", candidateId, reviewUrl: review });
+    if (!options.json) {
+        options.write("Proposed. You will own it unless you named someone else; the owner reads it and clicks Agree, and nothing else can.\n");
+        options.write(`${review}\n`);
+        options.write(`Sent over ${agent.repository ?? "this repository"}'s Balladeer agent connection, which does not expire.\n`);
+    }
+    return 0;
+}

package/dist/commands/repositories.d.ts

@@ -0,0 +1,18 @@
+export type RepositoriesOptions = Readonly<{
+    controlPlane: string;
+    json: boolean;
+    environment: NodeJS.ProcessEnv;
+    cwd: string;
+    write: (text: string) => void;
+}>;
+/**
+ * What this machine could add to Balladeer, and which of them are already in.
+ *
+ * It exists so the agent asking "which repositories shall I set up" has
+ * something to show. Setting one up is still `setup`, run in a checkout of it or
+ * named with `--repository`; this command changes nothing and sends nothing
+ * anywhere. The one network call it makes is to Balladeer, to find out which of
+ * these are already enrolled, and it is skipped entirely when no session is
+ * stored.
+ */
+export declare function runRepositories(options: RepositoriesOptions): Promise<number>;