balladeer 1.0.18 → 1.0.20

package/README.md

@@ -288,3 +288,21 @@ is replaced only after a new pairing starts; all stored agent connections and ot
 remain. `--create-workspace "Team name"` likewise opens fresh pairing instead of silently reusing
 the previous workspace. It pre-fills the name; a human still creates the workspace. An interrupted
 command can resume the same pending choice by running it again with the same flags.
+
+## Push review results
+
+The push reviewer sends each completed review to Balladeer automatically. The app groups issues by
+commitment and labels specific change results Passed, Broken, or Couldn’t verify. This is separate
+from qualified CI evidence and never starts or changes protection. The reviewer currently selects
+agreed promises; recorded intent can still guide agent work under the workspace’s retrieval
+settings.
+
+Only bounded metadata leaves the repository: promise and meaning identities, head and base commit
+SHAs, the reviewed branch when known, verdict, a closed reason code, an optional session and
+reproduction digest, and locally verified ancestry. Notes, reproduction commands, exact setup
+instructions, tests, source and output stay in `.continuity/judge-log/` on the machine.
+
+Unacknowledged results remain in a local queue for retry on a later judge run. A pass can resolve a
+reported break only for the same meaning and branch, on a locally established descendant. A pass on
+a different branch or a changed meaning cannot clear it. The app’s coverage remains Unknown without
+a complete PR inventory.

package/dist/anchoring.js

@@ -348,7 +348,7 @@ export function seedFromMap(map, at) {
             .slice(0, ANCHOR_LIMITS.linkedTests)
             .map((test) => ({ file: test.file })),
     };
-    return checkPromiseAnchors(anchors).ok ? anchors : undefined;
+    return checkPromiseAnchors(anchors, { allowRecordedId: true }).ok ? anchors : undefined;
 }
 /**
  * Which anchors have gone at a commit, read off the graph with no model: an
@@ -468,7 +468,7 @@ export async function anchorWithCall(input) {
             ...picks.symbols.map((symbol) => symbol.file),
         ])),
     };
-    const checked = checkPromiseAnchors(anchors);
+    const checked = checkPromiseAnchors(anchors, { allowRecordedId: true });
     if (!checked.ok)
         return { status: "failed", reason: "its anchors failed the data boundary", tokens };
     return {

package/dist/anchors-schema.d.ts

@@ -80,6 +80,8 @@ export declare function isPromiseAnchorId(value: unknown): value is string;
  * boundary. Problems name the field and the rule, never the value, so a
  * refusal never repeats what it refused.
  */
-export declare function checkPromiseAnchors(value: unknown): AnchorsCheck;
+export declare function checkPromiseAnchors(value: unknown, options?: Readonly<{
+    allowRecordedId?: boolean;
+}>): AnchorsCheck;
 /** The files a promise is selected by: its entry points' and its symbols' files. */
 export declare function anchorFiles(anchors: PromiseAnchors): string[];

package/dist/anchors-schema.js

@@ -28,6 +28,7 @@ export const ANCHOR_LIMITS = {
 // holds the two copies to the same text and the same answers.
 /** `prom_` ids as Balladeer issues them. */
 const PROMISE_ID_RULE = /^prom_[a-z0-9]{8,64}$/;
+const RECORDED_ID_RULE = /^cand_[a-z0-9]{8,64}$/;
 const DIGEST_RULE = /^sha256:[0-9a-f]{64}$/;
 const SHA_RULE = /^[0-9a-f]{40}$/;
 const INSTANT_RULE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
@@ -135,7 +136,7 @@ function hasExactKeys(value, keys) {
  * boundary. Problems name the field and the rule, never the value, so a
  * refusal never repeats what it refused.
  */
-export function checkPromiseAnchors(value) {
+export function checkPromiseAnchors(value, options = {}) {
     const problems = [];
     const fail = (at, rule) => problems.push(`${at} ${rule}`);
     if (!isRecord(value))
@@ -153,8 +154,9 @@ export function checkPromiseAnchors(value) {
         fail("the document", "has fields the contract does not define, or lacks one");
     if (value.schemaVersion !== PROMISE_ANCHORS_SCHEMA_VERSION)
         fail("schemaVersion", `is not ${PROMISE_ANCHORS_SCHEMA_VERSION}`);
-    if (!isPromiseAnchorId(value.promiseId))
-        fail("promiseId", "is not a prom_ id");
+    if (!isPromiseAnchorId(value.promiseId) &&
+        !(options.allowRecordedId && isText(value.promiseId) && RECORDED_ID_RULE.test(value.promiseId)))
+        fail("promiseId", "is not a promise or proposal id");
     if (!isText(value.semanticDigest) || !DIGEST_RULE.test(value.semanticDigest))
         fail("semanticDigest", "is not sha256: and 64 hex characters");
     const anchoredAt = value.anchoredAt;

package/dist/checkout-form.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Whether an install may take the older form out of the checkout it runs in:
+ * only when a person ran setup or install and the user-scope form is fully in
+ * place. The background update a session hook starts leaves the repository's
+ * files alone, because an edit to a file the team commits is a diff nobody
+ * asked for, and the user-scope hook already switches the older hook off from
+ * the laptop side (`retireCheckoutRuntime`), so nothing is lost.
+ */
+export declare function checkoutFormRemovalAllowed(environment: NodeJS.ProcessEnv, writes: readonly {
+    status: string;
+}[]): boolean;
 /**
  * Taking this product's own older, per-repository form out of a checkout once
  * the user-scope form is in place, so one hook speaks per session.

package/dist/checkout-form.js

@@ -2,6 +2,20 @@ import { execFileSync } from "node:child_process";
 import { copyFileSync, existsSync, lstatSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { isOurEntry, writeJsonAtomically } from "./mcp-config.js";
+import { SELF_UPDATE_ENVIRONMENT } from "./self-update.js";
+/**
+ * Whether an install may take the older form out of the checkout it runs in:
+ * only when a person ran setup or install and the user-scope form is fully in
+ * place. The background update a session hook starts leaves the repository's
+ * files alone, because an edit to a file the team commits is a diff nobody
+ * asked for, and the user-scope hook already switches the older hook off from
+ * the laptop side (`retireCheckoutRuntime`), so nothing is lost.
+ */
+export function checkoutFormRemovalAllowed(environment, writes) {
+    return (environment[SELF_UPDATE_ENVIRONMENT] !== "1" &&
+        writes.length > 0 &&
+        !writes.some((w) => w.status === "refused"));
+}
 const PROJECT_OWNER = "Balladeer current guidance (loader 1)";
 const CODEX_BLOCKS = [
     ["# balladeer:guidance:start", "# balladeer:guidance:end"],

package/dist/cli.js

@@ -31,7 +31,7 @@ import { updateNotice } from "./currency.js";
 import { describeEarlier, describeRemoval, findEarlier, removeEarlier } from "./remove-earlier.js";
 import { recordSelfUpdateState, SELF_UPDATE_ENVIRONMENT } from "./self-update.js";
 import { hooksAwaitingTrust } from "./hook-trust.js";
-import { describeCheckoutFormRemoval, findCheckoutForm, removeCheckoutForm, } from "./checkout-form.js";
+import { checkoutFormRemovalAllowed, describeCheckoutFormRemoval, findCheckoutForm, removeCheckoutForm, } from "./checkout-form.js";
 import { StoreError, normalizeControlPlane } from "./store.js";
 import { CLI_INVOCATION, CLI_VERSION, DEFAULT_CONTROL_PLANE } from "./wire.js";
 const USAGE = `balladeer ${CLI_VERSION}
@@ -545,8 +545,9 @@ function installEverything(options) {
     }
     // With the user-scope form in place, the older per-repository form in this
     // checkout only makes the session hear the guidance twice. Out it goes, with
-    // a copy beside any file git does not already keep.
-    if ((writes ?? []).length > 0 && !(writes ?? []).some((w) => w.status === "refused")) {
+    // a copy beside any file git does not already keep, and never from the
+    // background update (see `checkoutFormRemovalAllowed`).
+    if (checkoutFormRemovalAllowed(process.env, writes ?? [])) {
         const checkoutForm = findCheckoutForm({
             cwd: process.cwd(),
             controlPlane: options.controlPlane,

package/dist/commands/guidance.js

@@ -7,6 +7,7 @@ import { repositoryHints } from "../repository.js";
 import { newerVersionPublished } from "../currency.js";
 import { startSelfUpdateIfDue } from "../self-update.js";
 import { noteHookFired } from "../hook-trust.js";
+import { retireCheckoutRuntime } from "../guidance-runtime.js";
 /** A repository-specific setup step for explicit status and empty-catalog responses. */
 export function untrackedLine(remote) {
     const here = remote === "unknown/unknown" ? "This folder" : `This folder (${remote})`;
@@ -158,6 +159,18 @@ export async function runGuidance(options) {
         // trust are the ones this matters to.
         if (options.hook === "codex")
             noteHookFired(options.environment, "codex");
+        // This hook covers this checkout now, so the older per-repository hook
+        // here (releases before 1.0.8) only makes the session hear the guidance
+        // twice. Switch it off from the laptop side, once, before the fetch:
+        // nothing printed, no repository file touched, nobody asked to run a thing.
+        if (!projectScoped && event === "SessionStart")
+            retireCheckoutRuntime({
+                cwd: options.cwd,
+                host: options.hook,
+                repositoryId: agents[0].repositoryId,
+                controlPlane: agents[0].controlPlane,
+                environment: options.environment,
+            });
         const loaded = await loadGuidance({
             agent: agents[0],
             environment: options.environment,
@@ -165,14 +178,16 @@ export async function runGuidance(options) {
             hook: options.hook,
             ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
         });
-        // Behind? Start the install in the background, once a day at most, and
-        // carry on serving this session from the copy that is here.
-        if (event === "SessionStart")
-            startSelfUpdateIfDue(newerVersionPublished(), {
-                environment: options.environment,
-                ...(options.startUpdate ? { run: options.startUpdate } : {}),
-                ...(options.now ? { now: options.now } : {}),
-            });
+        // Behind? Start the install in the background and carry on serving this
+        // session from the copy that is here. Any hook that loaded guidance may
+        // start it, not only a session start: sessions run for days, and a laptop
+        // whose sessions never restart would otherwise never update (Robert's own,
+        // 1 October 2026). The stamp keeps it to once a day per release.
+        startSelfUpdateIfDue(newerVersionPublished(), {
+            environment: options.environment,
+            ...(options.startUpdate ? { run: options.startUpdate } : {}),
+            ...(options.now ? { now: options.now } : {}),
+        });
         const sessionId = identifier(record.session_id);
         const agentId = identifier(record.agent_id);
         recordGuidanceContext({

package/dist/commands/judge.d.ts

@@ -2,7 +2,13 @@ import type { AnchorBudget } from "../anchor-budget.js";
 import type { AnchorsClient } from "../anchors-client.js";
 import { type BehaviorMap } from "../behavior-map-schema.js";
 import { type HeadlessAgentOptions, type HeadlessAgentResult, type HeadlessClient, type LoginCheck } from "../headless-agent.js";
+import { type CodeReview } from "../judge-review.js";
+import type { ReviewSettings } from "../review-settings.js";
+import { type CaseEvidence, type EvidenceReceipt, type FrozenEvidenceFile } from "../judge-evidence.js";
+import { type ReviewsClient } from "../promise-review-client.js";
+import { reviewBackstop } from "../review-backstop.js";
 import { type HookHost, type MergeTarget } from "../judge-hook.js";
+import { type ReviewPayload } from "../review-reporting.js";
 import { type PromiseDocument, type PromiseReader } from "../promise-meaning.js";
 import type { RepositoryGraph } from "../risk/graph-cache.js";
 import { type CarriedFile } from "../scratch-worktree.js";
@@ -98,6 +104,8 @@ export type JudgeVerdict = {
     reproductionRejected: string | null;
     exercisedCases: string[];
     notes: string;
+    /** The model's code assessment. Local only; never part of a server receipt. */
+    review?: CodeReview;
     /**
      * On a could-not-tell the judge itself reached because the tests need
      * something this machine lacks: the one step that would let them run, as
@@ -119,6 +127,17 @@ export type JudgeVerdict = {
         file: string;
         outcome: "pass" | "fail" | "error" | "none";
     };
+    standing?: "recorded" | "agreed";
+    /** Local dependencies and runner identity; never credentials. */
+    environmentDigest?: string;
+    evidenceReceipts?: readonly Omit<EvidenceReceipt, "output">[];
+    independentReview?: Readonly<{
+        accepted: boolean;
+        reason: string;
+        durationMs?: number;
+        inputTokens?: number;
+        outputTokens?: number;
+    }>;
 };
 /** A command's exit, as one run of a reproduction or a linked test. */
 export type CommandRun = Readonly<{
@@ -198,6 +217,8 @@ export declare function keepReproduction(input: Readonly<{
     cwd: string;
     digest: string;
     files: readonly CarriedFile[];
+    /** Exact bytes that the runner executed; the exploratory copy may change later. */
+    frozenFiles?: readonly FrozenEvidenceFile[];
 }>): KeptReproduction | undefined;
 /**
  * How this repository runs one test file, when it can be told from the files
@@ -213,7 +234,10 @@ type JudgeAnswer = Readonly<{
     }>;
     exercisedCases: string[];
     notes: string;
+    review?: CodeReview;
     nextStep?: string;
+    evidenceFiles: readonly string[];
+    caseEvidence: readonly CaseEvidence[];
 }>;
 /** The longest `nextStep` kept from a judge's answer, in characters. */
 export declare const NEXT_STEP_LIMIT = 500;
@@ -261,6 +285,14 @@ export type JudgeArguments = Readonly<{
     json: boolean;
     mode?: "report" | "block";
     wait: boolean;
+    retry?: boolean;
+    /** Verified by a captured local push operation, not guessed from HEAD. */
+    destinationRef?: string;
+    destinationDigest?: string;
+    pushSessionId?: string;
+    operationDeadline?: number;
+    /** Original host for offers when a native push fans out into per-ref reviews. */
+    pushHost?: HookHost;
     hook?: HookHost;
     /** Run by the entry setup writes at the host's user scope, which stands aside where it has nothing to do. */
     userScope?: true;
@@ -274,7 +306,7 @@ export type JudgeArguments = Readonly<{
     repository?: string;
     controlPlane: string;
 }>;
-export declare const JUDGE_USAGE = "  npx -y balladeer@latest judge [--promises <id,id>] [--top <k>] [--base <ref>] [--head <ref>]\n                  [--report-only | --block] [--wait] [--json] [--client auto|claude|codex]\n                  [--from-file <promise.json> [--map <map.json>]]\n                  [--hook claude|codex|git] [--install-hook [claude|codex|git]]\n                  [--push-check on|off]\n      Judge whether this change keeps the promises it could break, one promise\n      at a time, on your own Claude Code or Codex login. A break counts only\n      with a command that fails with the change and passes without it, and\n      this command runs it both ways itself; anything unproven is \"could not\n      tell\". Report mode prints one line per promise and never stops anything;\n      --block exits 2 on a reproduced break, and when judges are still running\n      at the time limit it holds the push rather than letting it through.\n      --wait runs without the time limit. Promises come from --promises, else\n      every agreed promise whose anchored code the change edits, and every\n      promise with a behavior map whose own code or tests it edits (with\n      \"select\": \"ranked\" in .continuity/judge.json, the top of the maps'\n      ranking and a small random sample); plus that file's alwaysJudge. A\n      promise with no anchors yet is anchored first, by one small call on\n      your own login (see `balladeer anchor`), at most 20 a day on this\n      laptop, and a line says what that cost. Verdicts are kept in\n      .continuity/judge-log/, which git ignores. --install-hook adds the push\n      hook to .claude/settings.json and .codex/hooks.json, before and after\n      each shell command: report mode judges after a push has landed, so the\n      push never waits, and block mode judges before it. With git it writes\n      .git/hooks/pre-push, which judges before the push in both modes. With\n      \"offers\": true in .continuity/judge.json, the push hook also reads the\n      change for rules no promise records and offers at most three to\n      whoever is pushing; it records nothing and never holds a push (see\n      `balladeer offers`). Setup also writes the same pair of entries at\n      each host's user scope, running `judge --hook <host> --user-scope`,\n      so the check runs in every connected repository with agreed promises\n      and says nothing anywhere else; a checkout with its own entry keeps\n      the check to that entry. --push-check off turns the user-scope check\n      off on this laptop, and --push-check on turns it back on.\n";
+export declare const JUDGE_USAGE = "  npx -y balladeer@latest judge [--promises <id,id>] [--top <k>] [--base <ref>] [--head <ref>]\n                  [--report-only | --block] [--wait] [--retry] [--json] [--client auto|claude|codex]\n                  [--from-file <promise.json> [--map <map.json>]]\n                  [--hook claude|codex|git] [--install-hook [claude|codex|git]]\n                  [--push-check on|off]\n      Judge whether this change keeps the promises it could break, one promise\n      at a time, on your own Claude Code or Codex login. Recorded meaning is\n      advisory and never blocks. Kept requires executable passing-case evidence\n      and a fresh agent assessment. A break counts only\n      with a command that fails with the change and passes without it, and\n      this command runs it in fresh checkouts and a second local agent checks\n      that its assertion actually expresses the promise; anything unproven is \"could not\n      tell\". Report mode prints one line per promise and never stops anything;\n      --block exits 2 on a reproduced break, and when judges are still running\n      at the time limit it holds the push rather than letting it through.\n      --wait runs without the time limit. Promises come from --promises, else\n      every visible recorded or agreed promise whose anchored code the change edits, and every\n      promise with a behavior map whose own code or tests it edits (with\n      \"select\": \"ranked\" in .continuity/judge.json, the top of the maps'\n      ranking and a small random sample); plus that file's alwaysJudge. A\n      remaining current promise receives a bounded local relevance reading; strong\n      resource, sink and intent signals can add a promise beyond direct files. A\n      promise with no anchors yet is anchored first, by one small call on\n      your own login (see `balladeer anchor`), at most 20 a day on this\n      laptop, and a line says what that cost. Verdicts are kept in\n      .continuity/judge-log/, which git ignores. Coverage and pending work are\n      logged separately; --retry retries an inconclusive result. A known pushed\n      branch also sends a bounded receipt to Balladeer, with no source or logs. --install-hook adds the push\n      hook to .claude/settings.json and .codex/hooks.json, before and after\n      each shell command: report mode judges after a push has landed, so the\n      push never waits, and block mode judges before it. With git it writes\n      .git/hooks/pre-push, which judges before the push in both modes. With\n      \"offers\": true in .continuity/judge.json, the push hook also reads the\n      change for rules no promise records and offers at most three to\n      whoever is pushing; it records nothing and never holds a push (see\n      `balladeer offers`). Setup also writes the same pair of entries at\n      each host's user scope, running `judge --hook <host> --user-scope`,\n      so the check runs in every connected repository with visible promises\n      and says nothing anywhere else; a checkout with its own entry keeps\n      the check to that entry. --push-check off turns the user-scope check\n      off on this laptop, and --push-check on turns it back on.\n";
 export declare function parseJudgeArguments(argv: readonly string[]): JudgeArguments;
 /**
  * The subset of `balladeer-risk/v1` this command reads: enough to order the
@@ -347,7 +379,16 @@ export declare function findLoggedVerdict(root: string, key: Readonly<{
     semanticDigest: string;
     base: string;
     head: string;
+    environmentDigest?: string;
+    retry?: boolean;
 }>, now: Date): JudgeVerdict | undefined;
+/**
+ * A judge's words, shortened to fit one line an agent relays. A cut ends on a
+ * whole sentence, or failing that a whole word, and says where the rest is:
+ * the agent repeats the line as it reads it, so a reason cut mid-word reached
+ * the person mid-word (found 1 October 2026).
+ */
+export declare function sentence(text: string, limit?: number): string;
 /** Said after "fix the behavior": a deliberate change is the person's, and the promise its owner's. */
 export declare const DELIBERATE_CHANGE = "If the person changed this behavior on purpose, do not undo their change: tell them it breaks this promise, whose meaning only its owner can change.";
 export type VerdictLineContext = Readonly<{
@@ -382,6 +423,7 @@ export declare function stillKept(root: string, verdict: JudgeVerdict): JudgeVer
  */
 export declare function verdictLine(verdict: JudgeVerdict, title: string, context?: VerdictLineContext): string;
 export type JudgeDependencies = Readonly<{
+    reportReviews?: ((payload: ReviewPayload) => Promise<number>) | null;
     runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
     resolveLogin?: (requested: HeadlessClient | "auto", prefer?: HeadlessClient) => Promise<LoginCheck | undefined>;
     riskReport?: (root: string, base: string, head: string, 
@@ -391,6 +433,11 @@ export type JudgeDependencies = Readonly<{
     reader?: PromiseReader | null;
     /** The anchors route; `null` means none, without trying to find one. */
     anchors?: AnchorsClient | null;
+    reviews?: ReviewsClient | null;
+    /** Internal operation snapshot, reused across every pushed ref. */
+    reviewSettings?: ReviewSettings;
+    reviewSettingsResolved?: true;
+    backstop?: typeof reviewBackstop;
     /** The anchoring call, when it is not the person's own agent. */
     anchorAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
     /** The repository graph at a commit, when it is not built from this laptop's cache. */
@@ -415,6 +462,8 @@ export declare const PUSH_REPOSITORY_UNKNOWN = "Balladeer judge: this push was n
 /** Said instead of verdicts when every pull request the command opens or merges is in another repository. */
 export declare function pullRequestElsewhereLine(repo: string): string;
 export type JudgeRunOptions = Readonly<{
+    /** Collect a child ref's offers for delivery after the whole operation's verdicts. */
+    deferOffers?: (reading: Promise<readonly string[]>) => void;
     args: JudgeArguments;
     cwd: string;
     environment: NodeJS.ProcessEnv;