balladeer 1.0.0 → 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

@@ -18,6 +18,16 @@ export type TeachBackRequest = Readonly<{
         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;
     }>;
 }>;
 /**

package/dist/commands/propose.js

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import { callAgentTool, noAgentCredentialSentence, selectAgent, structuredString, } from "../agent.js";
-import { reviewLink } from "../client.js";
+import { proposalReviewLink } from "../client.js";
 import { commandLine } from "../release.js";
 import { repositoryHint } from "../repository.js";
 import { StoreError, readCredentials } from "../store.js";
@@ -33,6 +33,8 @@ const ALLOWED_TEACH_BACK = [
     "unresolvedQuestions",
     "proposedOwnerId",
     "confidence",
+    "wrongOutcome",
+    "leastSure",
 ];
 function unexpectedKeys(value, allowed) {
     return Object.keys(value).filter((key) => !allowed.includes(key));
@@ -110,6 +112,20 @@ export function readTeachBackFile(raw) {
     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: {
@@ -117,6 +133,8 @@ export function readTeachBackFile(raw) {
             teachBack: {
                 meaning,
                 confidence,
+                wrongOutcome,
+                ...(teachBack.leastSure === undefined ? {} : { leastSure: teachBack.leastSure }),
                 ...(teachBack.unresolvedQuestions === undefined
                     ? {}
                     : { unresolvedQuestions: teachBack.unresolvedQuestions }),
@@ -217,6 +235,10 @@ export async function runPropose(options) {
             ? {}
             : { 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":
@@ -246,12 +268,12 @@ export async function runPropose(options) {
         // 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("candidate_not_pending", `Balladeer matched an existing proposal, ${candidateId}, which is ${status ?? "in an unreported state"}. Nothing new was recorded.`, 5);
+        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 = reviewLink(options.controlPlane, `candidates/${candidateId}`);
+    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");

package/dist/commands/session.d.ts

@@ -0,0 +1,35 @@
+export type SessionOptions = Readonly<{
+    controlPlane: string;
+    json: boolean;
+    /**
+     * Read the session out of the commit at HEAD and tell Balladeer which commit
+     * it wrote, instead of printing an id.
+     */
+    record: boolean;
+    /** Start a new session even though one is still current. */
+    fresh: boolean;
+    /** 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;
+    now?: string;
+    write: (text: string) => void;
+}>;
+/**
+ * The id that joins what an agent was told to what it then wrote.
+ *
+ * Retrieval happens before the commit exists, so nothing ties the two together
+ * on its own, and without the tie a red check on Tuesday cannot be read back
+ * against what Balladeer had said on Monday. The agent's own working session
+ * spans both: it reads the index under this id and writes the same id into the
+ * commit it produces.
+ *
+ * `balladeer session` prints the id and the exact line to write.
+ * `balladeer session --record` reads that line back out of the commit at HEAD
+ * and tells Balladeer which commit the session wrote. The commit message itself
+ * never leaves this machine: only the pair of a session id and a forty-
+ * character SHA is sent, and the SHA is a fact CI already reports.
+ */
+export declare function runSession(options: SessionOptions): Promise<number>;

package/dist/commands/session.js

@@ -0,0 +1,118 @@
+import { callAgentTool, noAgentCredentialSentence, selectAgent } from "../agent.js";
+import { headCommit } from "../git.js";
+import { repositoryHint } from "../repository.js";
+import { AGENT_SESSION_TRAILER, agentSessionTrailerLine, currentSession, readAgentSessionTrailer, } from "../session.js";
+import { StoreError, readCredentials } from "../store.js";
+import {} from "../wire.js";
+/**
+ * The id that joins what an agent was told to what it then wrote.
+ *
+ * Retrieval happens before the commit exists, so nothing ties the two together
+ * on its own, and without the tie a red check on Tuesday cannot be read back
+ * against what Balladeer had said on Monday. The agent's own working session
+ * spans both: it reads the index under this id and writes the same id into the
+ * commit it produces.
+ *
+ * `balladeer session` prints the id and the exact line to write.
+ * `balladeer session --record` reads that line back out of the commit at HEAD
+ * and tells Balladeer which commit the session wrote. The commit message itself
+ * never leaves this machine: only the pair of a session id and a forty-
+ * character SHA is sent, and the SHA is a fact CI already reports.
+ */
+export async function runSession(options) {
+    const emit = (step) => {
+        if (options.json)
+            options.write(`${JSON.stringify(step)}\n`);
+    };
+    const say = (text) => {
+        if (!options.json)
+            options.write(`${text}\n`);
+    };
+    const fail = (reason, message, exitCode) => {
+        if (options.json)
+            emit({ step: "error", reason, message, changed: false, exitCode });
+        else
+            options.write(`${message}\n`);
+        return exitCode;
+    };
+    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 here = options.repo ?? repositoryHint(options.cwd);
+    const selection = selectAgent(credentials.agents, options.controlPlane, options.repository, here);
+    if (selection.kind === "refused") {
+        const message = selection.missingFor === undefined
+            ? selection.reason
+            : noAgentCredentialSentence(selection.missingFor);
+        return fail("no_agent_credential_on_this_machine", message, 4);
+    }
+    const agent = selection.agent;
+    if (options.record)
+        return recordCommit(options, agent, emit, say, fail);
+    let session;
+    try {
+        session = currentSession({
+            repository: agent.repositoryId,
+            now: options.now ?? new Date().toISOString(),
+            ...(options.fresh ? { forceNew: true } : {}),
+            environment: options.environment,
+        });
+    }
+    catch (error) {
+        return fail(error instanceof StoreError ? error.code : "session_store_unwritable", error instanceof StoreError ? error.message : String(error), 4);
+    }
+    const trailer = agentSessionTrailerLine(session.sessionId);
+    emit({
+        step: "session",
+        sessionId: session.sessionId,
+        startedAt: session.startedAt,
+        minted: session.minted,
+        trailer,
+        changed: session.minted,
+    });
+    say(session.sessionId);
+    say("");
+    say(session.minted
+        ? "This is a new session. Pass it to every promise read you make in this repository."
+        : "This session is already open. Pass it to every promise read you make in this repository, and use --new to start a different one.");
+    say(`Then write this line into the commit or pull-request body you produce:`);
+    say("");
+    say(`    ${trailer}`);
+    say("");
+    say(`and run \`balladeer session --record\` once the commit exists, so a check that goes red on it can be read back against what you were told before you started. Balladeer is sent the session id and the commit SHA, and nothing else.`);
+    return 0;
+}
+async function recordCommit(options, agent, emit, say, fail) {
+    const head = await headCommit(options.cwd);
+    if (head === undefined) {
+        return fail("no_commit_here", "There is no commit to record: this directory is not a git checkout, or it has no commits yet.", 4);
+    }
+    const sessionId = readAgentSessionTrailer(head.message);
+    if (sessionId === undefined) {
+        // Said in full rather than as a code. The likeliest reader of this line is
+        // an agent that forgot the trailer, and the remedy is one line it can add
+        // to the commit it just made.
+        return fail("no_session_trailer", `The commit at HEAD carries no ${AGENT_SESSION_TRAILER} line this release recognises, so there is nothing to record. Add \`${AGENT_SESSION_TRAILER}: <the id balladeer session prints>\` to the commit message and run this again. A commit carrying two different session ids is refused rather than guessed at.`, 4);
+    }
+    const call = await callAgentTool(agent, "record_session_commit", {
+        session: sessionId,
+        commitSha: head.sha,
+    });
+    if (call.kind !== "result") {
+        return fail(call.kind === "tool_refusal" ? "refused" : call.kind, call.kind === "tool_refusal"
+            ? call.text
+            : `Balladeer could not record this commit (${call.kind}). Nothing was recorded, and running this again after the connection is back is safe: the same pair recorded twice is recorded once.`, 5);
+    }
+    emit({
+        step: "session_commit",
+        sessionId,
+        commitSha: head.sha,
+        changed: true,
+    });
+    say(`Recorded ${head.sha.slice(0, 12)} as written by this session.`);
+    return 0;
+}

package/dist/commands/setup.d.ts

@@ -21,6 +21,29 @@ export type SetupOptions = Readonly<{
      * reach the control plane at that moment.
      */
     refresh?: boolean;
+    /**
+     * Set up even though an earlier Balladeer is still installed on this machine.
+     *
+     * The check that stops this run is a warning about two programs claiming one
+     * name, not a safety property, so somebody who has decided to run both says so
+     * and this run carries on exactly as it would have.
+     */
+    force?: boolean;
+    /**
+     * Whether to also connect Claude desktop chat for this repository.
+     *
+     * Three states, because there are three answers and only two of them are a
+     * flag. `true` is `--claude-desktop`: connect it, and say out loud when this
+     * machine has no such app rather than skipping in silence. `false` is
+     * `--no-claude-desktop`: do not touch that file and do not mention it.
+     * Undefined is the ordinary run, which connects it where Claude desktop is
+     * installed and says nothing at all where it is not. Writing it by default is
+     * the same bargain `.mcp.json` already makes: the entry is additive, it
+     * carries no credential, it never replaces anybody else's server, and the
+     * people this is for write their plan in that chat before they open a coding
+     * agent at all.
+     */
+    claudeDesktop?: boolean;
     environment: NodeJS.ProcessEnv;
     cwd: string;
     write: (text: string) => void;