balladeer 1.0.0 → 1.0.2

package/dist/client.js

@@ -34,7 +34,7 @@ export class RefusalError extends Error {
  *
  * Behind a platform proxy a server can resolve a link against the machine it is
  * running on rather than against the address customers use, and the first
- * production `propose` printed exactly that: `https://localhost:8080/candidates/...`
+ * production `propose` printed exactly that: a review link on `localhost:8080`
  * as the place to go and agree. A command that prints such a link is worse than
  * one that prints none, because the person tries it.
  *
@@ -42,8 +42,39 @@ export class RefusalError extends Error {
  * identifier and this builds the address, which is why there is no parameter
  * here for a server's own link to arrive through.
  */
-export function reviewLink(controlPlane, path) {
-    return new URL(path, ensureTrailing(controlPlane)).toString();
+export function reviewLink(controlPlane, path, workspaceId) {
+    const url = new URL(path, ensureTrailing(controlPlane));
+    if (workspaceId !== undefined)
+        url.searchParams.set("workspaceId", workspaceId);
+    return url.toString();
+}
+/**
+ * The one place this command decides where a person reads a proposal.
+ *
+ * Every review address this command prints, in a receipt, in a discovery run,
+ * or in its JSON, is built here, so the address is one edit rather than a hunt
+ * and a printed link cannot fall behind the page it names. It matches the
+ * server's own `proposal-links` helper: the page is `/proposals`, and
+ * the retired address redirects to it permanently, so a link an older copy of
+ * this command already printed still lands on it.
+ */
+export function proposalReviewLink(controlPlane, proposalId, workspaceId) {
+    return reviewLink(controlPlane, `proposals/${encodeURIComponent(proposalId)}`, workspaceId);
+}
+/** The address the whole waiting inbox is read on. */
+export function proposalInboxLink(controlPlane) {
+    return reviewLink(controlPlane, "proposals");
+}
+/**
+ * One link that opens exactly the proposals named, and nothing else.
+ *
+ * The ids travel in the query string because the batch is exactly these
+ * promises: a link to the whole inbox would also open whatever was already
+ * waiting there, and a filter by repository would open a different set
+ * tomorrow.
+ */
+export function batchProposalReviewLink(controlPlane, proposalIds) {
+    return reviewLink(controlPlane, `proposals/review?ids=${proposalIds.join(",")}`);
 }
 function ensureTrailing(controlPlane) {
     return controlPlane.endsWith("/") ? controlPlane : `${controlPlane}/`;

package/dist/commands/affected.js

@@ -1,6 +1,7 @@
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { TOUCH_MAP_FILE, affectedPaths, readLocalPackages, readTouchMap, verifierDigest, } from "../touch-map.js";
-import {} from "../wire.js";
+import { formatInstant } from "../local-time.js";
+import { CLI_INVOCATION } from "../wire.js";
 import { promiseRoot } from "./touch-map.js";
 /** How many promises one path lists before the report says how many more. */
 const NAMED_LIMIT = 20;
@@ -35,7 +36,7 @@ export async function runAffected(options) {
             options.write(`${text}\n`);
     };
     if (options.paths.length === 0) {
-        const message = "Name at least one path: balladeer affected src/orders/total.ts";
+        const message = `Name at least one path: ${CLI_INVOCATION} affected src/orders/total.ts`;
         if (options.json)
             emit({ step: "error", reason: "usage", message, changed: false, exitCode: 4 });
         else
@@ -54,8 +55,8 @@ export async function runAffected(options) {
     const reading = readTouchMap(root);
     if (reading.kind !== "map") {
         const message = reading.kind === "absent"
-            ? `There is no touch map in this checkout yet. Build one with: balladeer touch-map`
-            : `${TOUCH_MAP_FILE} could not be read as a touch map. Build it again with: balladeer touch-map`;
+            ? `There is no touch map in this checkout yet. Build one with: ${CLI_INVOCATION} touch-map`
+            : `${TOUCH_MAP_FILE} could not be read as a touch map. Build it again with: ${CLI_INVOCATION} touch-map`;
         emit({ step: "affected", mapped: false, paths: [], changed: false });
         say(message);
         // Zero, because having no map is not a fault in the change somebody is
@@ -86,7 +87,7 @@ export async function runAffected(options) {
         changed: false,
     });
     if (touched.length === 0) {
-        say(`No promise in this map ran any of those files. The map was built ${reading.map.generatedAt}; a promise sealed since then is not in it.`);
+        say(`No promise in this map ran any of those files. The map was built ${formatInstant(reading.map.generatedAt)}; a promise sealed since then is not in it.`);
         return 0;
     }
     for (const answer of answers) {
@@ -114,8 +115,8 @@ export async function runAffected(options) {
     say("");
     if (stale > 0) {
         say(stale === 1
-            ? "One answer above is stale. Run balladeer touch-map to measure it again."
-            : `${stale} of those answers are stale. Run balladeer touch-map to measure them again.`);
+            ? `One answer above is stale. Run ${CLI_INVOCATION} touch-map to measure it again.`
+            : `${stale} of those answers are stale. Run ${CLI_INVOCATION} touch-map to measure them again.`);
     }
     say("This came from your own checkout. Balladeer was not asked, and was told nothing.");
     return 0;

package/dist/commands/check-seals.js

@@ -3,7 +3,7 @@ import { dirname, join, resolve } from "node:path";
 import { runCommand } from "../gh.js";
 import { repositoryRoot } from "../git.js";
 import { promiseForPath, sealedPromises } from "../seals.js";
-import {} from "../wire.js";
+import { CLI_INVOCATION } from "../wire.js";
 /**
  * Where the pinned runner sits once setup's instructions have been followed.
  *
@@ -258,17 +258,17 @@ function installPrePushHook(root, options, emit, say) {
     const hookPath = join(root, ".git", "hooks", "pre-push");
     if (existsSync(hookPath)) {
         const message = `${hookPath} already exists, so nothing was written. Add this line to it yourself if you ` +
-            "want the check: balladeer check-seals";
+            `want the check: ${CLI_INVOCATION} check-seals`;
         emit({ step: "error", reason: "hook_exists", message, changed: false, exitCode: 4 });
         say(message);
         return 4;
     }
     const script = [
         "#!/bin/sh",
-        "# Installed by: balladeer check-seals --install-hook",
+        `# Installed by: ${CLI_INVOCATION} check-seals --install-hook`,
         "# It stops a push that would break a promise's seal, and says nothing otherwise.",
         "# Delete this file to remove it.",
-        "balladeer check-seals || exit 1",
+        `${CLI_INVOCATION} check-seals || exit 1`,
         "",
     ].join("\n");
     try {

package/dist/commands/discover.js

@@ -1,10 +1,10 @@
 import { readFileSync } from "node:fs";
-import { callAgentTool, selectAgent, structuredString } from "../agent.js";
-import { reviewLink } from "../client.js";
+import { callAgentTool, reportAgentEnforcementWarning, selectAgent, structuredString, } from "../agent.js";
+import { batchProposalReviewLink, proposalReviewLink } from "../client.js";
 import { commandLine } from "../release.js";
 import { repositoryHint } from "../repository.js";
 import { StoreError, findSession, readCredentials } from "../store.js";
-import {} from "../wire.js";
+import { CLI_INVOCATION } from "../wire.js";
 import { readTeachBackFile } from "./propose.js";
 /**
  * Ten promises at 64 KiB each, which is the per-promise cap `propose` already
@@ -140,7 +140,7 @@ function titleOf(request) {
  * different set tomorrow.
  */
 export function batchReviewLink(controlPlane, candidateIds) {
-    return reviewLink(controlPlane, `candidates/review?ids=${candidateIds.join(",")}`);
+    return batchProposalReviewLink(controlPlane, candidateIds);
 }
 /**
  * Failures of the connection rather than of one promise, which is the
@@ -197,7 +197,7 @@ export async function runDiscover(options) {
         return exitCode;
     };
     if (!options.file) {
-        return fail("usage", "Give a catalog file: balladeer discover --file <path>.", 4);
+        return fail("usage", `Give a catalog file: ${CLI_INVOCATION} discover --file <path>.`, 4);
     }
     let raw;
     try {
@@ -232,6 +232,7 @@ export async function runDiscover(options) {
             `Run \`${commandLine(null, "setup")}\` here again to pair this machine, which records who you are, or name the owner yourself with --owner <membership id> from the members list on the Balladeer MCP server's setup tool.`, 4);
     }
     const setup = await callAgentTool(agent, "get_promise_setup", {});
+    reportAgentEnforcementWarning(setup, options);
     if (setup.kind !== "result") {
         return fail("owner_unverified", `${memberListRefusal(setup.kind, options.controlPlane)} Nothing was sent.`, 5);
     }
@@ -254,7 +255,7 @@ export async function runDiscover(options) {
                 index: index + 1,
                 title,
                 candidateId: outcome.candidateId,
-                reviewUrl: reviewLink(options.controlPlane, `candidates/${outcome.candidateId}`),
+                reviewUrl: proposalReviewLink(options.controlPlane, outcome.candidateId, agent.workspaceId),
             };
             filed.push(entry);
             emit({
@@ -336,6 +337,14 @@ async function proposeOne(agent, request, ownerId) {
         // are not nine equally certain readings, and an owner deciding which to read
         // first is entitled to see which one the agent was least sure of.
         confidence: request.teachBack.confidence,
+        // The gate, on every entry in the file. A discovery run is where an
+        // unfailable promise is easiest to write: nine behaviors read off nine
+        // sources, and any one of them can be a sentence nothing could ever
+        // contradict. The file is refused entry by entry rather than in bulk.
+        wrongOutcome: request.teachBack.wrongOutcome,
+        ...(request.teachBack.leastSure === undefined
+            ? {}
+            : { leastSure: request.teachBack.leastSure }),
     });
     switch (call.kind) {
         case "endpoint_refused":
@@ -387,7 +396,7 @@ async function proposeOne(agent, request, ownerId) {
     if (status !== "pending_review") {
         return {
             ok: false,
-            reason: "candidate_not_pending",
+            reason: "proposal_not_pending",
             message: `Balladeer matched an existing proposal, ${candidateId}, which is ${status ?? "in an unreported state"}. Nothing new was recorded.`,
         };
     }

package/dist/commands/explain.d.ts

@@ -4,7 +4,7 @@
  *
  * The boundary copy describes the product's boundary and is timeless; it names
  * two credentials, a CI workflow, and a check on pull requests. In balladeer
- * 1.0.0 the command reaches none of those, so saying so is the difference
+ * 1.0.1 the command reaches none of those, so saying so is the difference
  * between an explanation and a claim.
  */
 export declare const RELEASE_PREFACE: string;

package/dist/commands/explain.js

@@ -6,7 +6,7 @@ import { CLI_VERSION, DEFAULT_CONTROL_PLANE } from "../wire.js";
  *
  * The boundary copy describes the product's boundary and is timeless; it names
  * two credentials, a CI workflow, and a check on pull requests. In balladeer
- * 1.0.0 the command reaches none of those, so saying so is the difference
+ * 1.0.1 the command reaches none of those, so saying so is the difference
  * between an explanation and a claim.
  */
 export const RELEASE_PREFACE = [

package/dist/commands/invite.js

@@ -1,4 +1,5 @@
 import { ClientTooOldError, RefusalError, TransportError, request } from "../client.js";
+import { formatInstant } from "../local-time.js";
 import { commandLine } from "../release.js";
 import { StoreError, findSession, readCredentials } from "../store.js";
 import {} from "../wire.js";
@@ -127,7 +128,7 @@ async function inviteOne(options, session, email) {
         say(options, `Invited ${answer.email} to ${answer.workspaceName} as ${role}. Balladeer has sent them the email.`);
         say(options, `  They can ${ROLE_MEANINGS[answer.requestedRole]}. They join when they accept, and not before.`);
         if (answer.expiresAt !== null) {
-            say(options, `  The invitation stops working at ${answer.expiresAt}.`);
+            say(options, `  The invitation stops working at ${formatInstant(answer.expiresAt)}.`);
         }
         emit(options, {
             step: "invitation",

package/dist/commands/prepare.d.ts

@@ -0,0 +1,74 @@
+export type PrepareOptions = Readonly<{
+    controlPlane: string;
+    json: boolean;
+    promiseId: string;
+    /** Prepare a replacement, invalidating the packet nobody has spent. */
+    again: 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;
+    write: (text: string) => void;
+}>;
+/**
+ * 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 declare function atThisTerminal(text: string): string;
+/**
+ * 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.
+ */
+declare const METADATA_KEYS: readonly ["schemaVersion", "workspaceLocator", "receiptId", "revisionId", "bindingId", "workflowDigest"];
+type Metadata = Record<(typeof METADATA_KEYS)[number], string>;
+export declare function readQualificationMetadata(structured: unknown): Readonly<{
+    ok: true;
+    value: Metadata;
+}> | Readonly<{
+    ok: false;
+    reason: string;
+}>;
+/**
+ * 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 declare function metadataDestination(cwd: string, metadataPath: string): Readonly<{
+    ok: true;
+    path: string;
+}> | Readonly<{
+    ok: false;
+    reason: 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 declare function runPrepare(options: PrepareOptions): Promise<number>;
+export {};

package/dist/commands/prepare.js

@@ -0,0 +1,218 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { callAgentTool, noAgentCredentialSentence, reportAgentEnforcementWarning, 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,
+    });
+    reportAgentEnforcementWarning(call, options);
+    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,10 +1,10 @@
 import { readFileSync } from "node:fs";
-import { callAgentTool, noAgentCredentialSentence, selectAgent, structuredString, } from "../agent.js";
-import { reviewLink } from "../client.js";
+import { callAgentTool, noAgentCredentialSentence, reportAgentEnforcementWarning, 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";
+import { CLI_INVOCATION } from "../wire.js";
 const MAX_FILE_BYTES = 64 * 1024;
 /**
  * Every field the server's schema requires with no default. It is every
@@ -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 }),
@@ -172,7 +190,7 @@ export async function runPropose(options) {
         return exitCode;
     };
     if (!options.file) {
-        return fail("usage", "Give a proposal file: balladeer propose --file <path>.", 4);
+        return fail("usage", `Give a proposal file: ${CLI_INVOCATION} propose --file <path>.`, 4);
     }
     let raw;
     try {
@@ -217,7 +235,12 @@ 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 }),
     });
+    reportAgentEnforcementWarning(call, options);
     switch (call.kind) {
         case "endpoint_refused":
             return fail("agent_endpoint_unsafe", `${call.reason} Nothing was sent.`, 4);
@@ -246,12 +269,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, agent.workspaceId);
     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/repositories.js

@@ -94,6 +94,7 @@ function report(options, rows, workspaceKnown) {
     say(options, workspaceKnown
         ? "Repositories your GitHub account can see. Ones already in Balladeer are marked."
         : "Repositories your GitHub account can see. Nothing is stored for this Balladeer, so which of them are already added is unknown.");
+    say(options, "These are GitHub repositories, not local directories or git worktrees.");
     say(options, "");
     for (const row of rows) {
         const marks = [