omp-conductor 0.17.0 → 0.18.0

package/src/ask.ts

@@ -93,7 +93,11 @@ export interface AskRequest {
   timeoutSeconds?: number;
   /** What is waiting on the answer, for the decision row and the digest. */
   blocks?: string;
-  /** The option applied by `auto-proceed`; required exactly for that outcome. */
+  /**
+   * The option applied by `auto-proceed`; required exactly for that outcome.
+   * When {@link AskRequest.options} are supplied it must name one of their
+   * labels — the label as delivered, never an index.
+   */
   recommended?: string;
   /** The choices shown to the operator, with {@link AskRequest.recommended} named. */
   options?: AskOption[];
@@ -115,6 +119,13 @@ function isInterruptCategory(value: unknown): value is InterruptCategory {
  * {@link MAX_QUESTION_LINES} / {@link MAX_QUESTION_CHARACTERS}, and refuses
  * rather than truncating: a truncated question reads as complete and has lost
  * its options, which is strictly worse than a rejection the caller must fix.
+ *
+ * The refusal is terminal for the call (#741): nothing is recorded or
+ * delivered, and the caller must not resubmit the trimmed question in the same
+ * turn — the rationale belongs in the issue or the event ledger, and a
+ * decision that still needs a human answer is raised as a fresh ask on a later
+ * tick. A re-issued ask therefore always starts from the accepted arguments of
+ * a new call, never from a rewrite of a refused one.
  */
 export function validateQuestionShape(question: string): QuestionShape {
   const lines = question.split("\n").length;
@@ -151,7 +162,13 @@ export function parseAskRequest(raw: unknown): AskParse {
   }
   const shape = validateQuestionShape(question.trim());
   if (!shape.ok) {
-    return { ok: false, problem: `conductor_ask ${shape.problem}` };
+    return {
+      ok: false,
+      problem:
+        `conductor_ask ${shape.problem} Do not re-issue the trimmed question in this turn: if the ` +
+        "decision still needs a human answer, say so in the report and raise it as a fresh ask in a " +
+        "later tick.",
+    };
   }
 
   const onTimeoutRaw = input["on-timeout"];
@@ -225,6 +242,25 @@ export function parseAskRequest(raw: unknown): AskParse {
     options = parsedOptions;
   }
 
+  // A recommendation must name a supplied option. `recommended` is the option
+  // label exactly as the operator reads it — never an index (that is
+  // telegram_ask's convention, not this tool's) and never free text when a
+  // menu exists. Refused at parse time so the incoherent ask leaves no trace:
+  // on `auto-proceed` its text becomes the recorded auto-applied answer, and a
+  // value that named no option would resolve a decision row to something that
+  // was never a choice (#740).
+  if (options !== undefined && recommended !== undefined) {
+    const labels = options.map((option) => option.label);
+    if (!labels.includes(recommended)) {
+      return {
+        ok: false,
+        problem:
+          `conductor_ask recommended "${recommended}" names no option — it must be one of: ${labels.join(", ")}. ` +
+          "It is the option label exactly as delivered to the operator, not an index",
+      };
+    }
+  }
+
   const categoryRaw = input["category"];
   if (categoryRaw !== undefined && !isInterruptCategory(categoryRaw)) {
     return {
@@ -274,7 +310,7 @@ export function askParameterSchema(): Record<string, unknown> {
       recommended: {
         type: "string",
         description:
-          "The option applied on auto-proceed. Required when on-timeout is auto-proceed, because the row must record what was auto-applied.",
+          "The option applied on auto-proceed; required when on-timeout is auto-proceed because the row must record what was auto-applied. When options are supplied this must be one of their labels — the label as delivered to the operator, not an index.",
       },
       blocks: {
         type: "string",

package/src/availability.ts

@@ -91,17 +91,35 @@ export function availabilityDisposition(
   return "availability";
 }
 
+/** A question-kind category. Every ask surface — `message --category
+ *  decision-needed`, a `QUESTION:`-marked message, and `conductor_ask`'s
+ *  default — resolves to this one category, so treating it as
+ *  availability-deferred covers the whole question pathway at once (#596). */
+export const QUESTION_KIND: InterruptCategory = "decision-needed";
+
 /**
  * Decide one tier-2 category. `digest` means the category policy itself defers
  * it; `availability` means it was otherwise interruptible and may be released
  * when the configured window next opens.
+ *
+ * A question is availability-deferred, never digest-deferred (#596): the
+ * category policy decides what may interrupt the operator's phone, but a
+ * question's deferral is literally "the operator is not available" — it waits
+ * for the window and the working-hours catch-up can release it at the next
+ * opening. With no window configured the next opening is now, so a question
+ * delivers rather than being silently bound to the daily digest. The
+ * `interruptOn` list never applies to a question's deferral.
  */
 export function interruptDisposition(
   policy: ReportingPolicy | undefined,
   category: InterruptCategory,
   at: number,
 ): InterruptDisposition {
-  if (policy !== undefined && !policy.interruptOn.includes(category)) return "digest";
+  if (
+    policy !== undefined &&
+    category !== QUESTION_KIND &&
+    !policy.interruptOn.includes(category)
+  ) return "digest";
   return availabilityDisposition(policy?.availability, category, at);
 }
 
@@ -148,6 +166,14 @@ export function formatZonedMinute(at: number, timezone: string): string {
   return `${local.date} ${local.clock} ${timezone} (${new Date(at).toISOString()})`;
 }
 
+/** Compact local timestamp for a one-line future, e.g. "2026-08-24 09:00 UTC":
+ *  the same instant as {@link formatZonedMinute} without the ISO tail, so a
+ *  held-notice line read on a phone says plainly when the window opens. */
+export function formatNextWindowOpening(at: number, timezone: string): string {
+  const local = localMinute(at, timezone);
+  return `${local.date} ${local.clock} ${timezone}`;
+}
+
 /** One prompt sentence; the runtime gate, not this prose, owns the decision. */
 export function availabilityPrompt(policy: ReportingPolicy | undefined, now: number): string {
   const state = availabilityState(policy, now);

package/src/backups.ts

@@ -18,8 +18,8 @@ import {
 import { join } from "node:path";
 
 /** A timestamp stem safe to embed in a file name. */
-export function backupTimestamp(): string {
-  return new Date().toISOString().replace(/[:.]/g, "-");
+export function backupTimestamp(at: number = Date.now()): string {
+  return new Date(at).toISOString().replace(/[:.]/g, "-");
 }
 
 /**

package/src/briefs/orchestrator.md

@@ -66,6 +66,7 @@ For each one, pick exactly one of three outcomes:
   question that unblocks it. Do not guess: a wrong answer costs a worker's whole
   budget and lands a wrong PR, while an unanswered question costs a delay.
 {{MERGE_DUTY}}
+{{REVIEW_DUTY}}
 
 **Then check for orphans.** A worker is a process, and processes die: a daemon
 restart, a host reboot, a kill. The `agent:in-progress` label survives that death

package/src/briefs/worker.md

@@ -47,7 +47,7 @@ files are canonical; your priors are not.
 
 {{ACCEPTANCE_CRITERIA}}
 
-{{ISSUE_COMMENTS}}## How to work
+{{ISSUE_COMMENTS}}{{FILE_LANE}}## How to work
 
 1. **Understand before editing — and ask the graph before you grep.** Your turns
    are mostly spent finding code, not writing it, and running out of turns
@@ -76,6 +76,18 @@ files are canonical; your priors are not.
    genuinely cannot be done small, stop and escalate rather than ballooning.
 5. **Fix the root cause, never the symptom.** Do not suppress a warning, delete an
    assertion, or special-case an input to make a check pass.
+6. **Prefer the structured edit tool for file changes, and the structured
+   search tool over shelling out.** A structured edit is one call: anchored and
+   verified, and a stale anchor fails loudly instead of silently editing the
+   wrong line. The shell equivalent is three or four — compose the script,
+   escape it correctly, run it, then read the file back to confirm it did what
+   was intended — and a mis-escaped `sed -i` pattern silently edits nothing or
+   the wrong line. So do not hand-roll edits through `sed -i`, `python3`
+   heredocs, `node -e` or shell redirection except where no structured tool can
+   express the change (a binary file, a generated artefact). The same holds for
+   finding code: use the structured search tool rather than shelling out to
+   grep, for the same reason the graph line exists — it is cheaper per call and
+   its output is already scoped.
 
 ## Tests — read this carefully
 
@@ -98,6 +110,8 @@ These are the exact gates for `{{REPO}}`:
 
 {{GATES}}
 
+{{SHARED_HOST_NOTICE}}
+
 Run every one of them, from the directory listed, over the **whole tree** — not
 just the directory you edited. Linting only the source dir is how an error in a
 migration, a config file or a script reaches the runners.
@@ -208,24 +222,29 @@ Escalating is a successful outcome. Guessing is not.
 
 ## Your final report
 
-End with exactly these seven lines, evidence only — no narration:
-
+End your run by yielding the settlement through the `yield` tool — one
+structured call, and the schema is the contract: the harness showed it to you
+at session start. The expected shape:
+
+```json
+{
+  "status": "green",
+  "prUrl": "https://github.com/.../pull/N",
+  "headSha": "<the 40-char head you watched go green>",
+  "summary": "What you changed and why — the narrative a reviewer reads.",
+  "proof": ["bun test omp/src/worker.test.ts"]
+}
 ```
-issue:   {{TRACKER_REPO}}#{{ISSUE_NUMBER}}
-pr:      <url or "none">
-head:    <40-character head SHA or "none">
-state:   pushed-green | blocked | failed
-gates:   <exact commands run and their results>
-changed: <the settlement derives this from the PR diff — omit the line>
-next:    <nothing | the specific decision needed>
-```
-
-The `changed:` line is not yours to write from memory: the settlement replaces
-it with the actual file list from the PR's diff. Omit it, or write it wrongly —
-the settled report carries the diff's list either way. The narrative in your
-report (what you changed and why, above these lines) is the part only you can
-write, and it is the part a reviewer reads.
 
-Never report success you have not observed. "Should pass CI" is not a state, and
-`pushed-green` means you watched the checks go green — not that you expect them
+Call it as `yield({ result: { data: <the object> } })` with no `type` — the
+usual terminal yield. `status: "green"` means you pushed and **watched the
+checks go green**, and it requires both `prUrl` and `headSha`. Use `blocked`
+(with `blockers`) when a decision or credential is missing, `failed` when the
+run could not complete. The dispatcher renders your yielded settlement into
+the stored report, so `summary` is what a reviewer reads and `proof` is the
+evidence; the `changed:` file list is derived from the PR's own diff, never
+written by you.
+
+Never report success you have not observed. "Should pass CI" is not a state,
+and `green` means you watched the checks go green — not that you expect them
 to.

package/src/command-help.ts

@@ -168,9 +168,16 @@ export const COMMAND_DETAILS = `  setup    interview, then write config.json, th
            condition the daemon checks for you; a met watch wakes the next tick
            with its note, exactly as a met question does, but it is listed under
            its own heading and never under "Open operator decisions", and it has
-           no seven-day expiry. \`watch list\` shows open watches.
+           no seven-day expiry. \`watch list\` shows open watches; \`watch
+           withdraw <id>\` ends one with a recorded reason — the verb that
+           creates a watch is the verb that ends it (watches are decision rows,
+           so \`decision withdraw <id>\` also works). A watch whose PR condition
+           can no longer be observed — the PR merged or closed before the
+           condition was seen — is withdrawn by the daemon itself with the
+           reason recorded.
              watch add --note TEXT [--blocks TEXT] [--resolves-when COND]
              watch list
+             watch withdraw <id> [--reason TEXT]
   intake   keep a raw idea durably before it becomes anything: record it now
            with \`omp-conductor intake "<text>"\`, list what is still pending,
            dismiss what turned out to be nothing. Backed by the sqlite store,

package/src/command-manifest.ts

@@ -390,24 +390,27 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
   },
   {
     name: "watch",
-    description: "record or list orchestrator-only conditions and carry notes",
+    description: "record, list, or withdraw orchestrator-only conditions and carry notes",
     scope: "project",
     usage: [
       "watch add --note TEXT [--blocks TEXT] [--resolves-when COND] [--project NAME]",
       "watch list [--project NAME] [--json]",
+      "watch withdraw <id> [--reason TEXT] [--project NAME]",
     ],
     subcommands: [
       { name: "add", description: "record a watch" },
       { name: "list", description: "list open watches" },
+      { name: "withdraw", description: "withdraw an obsolete watch" },
     ],
     flags: [
       value("--note", "note carried when the watch resolves"),
       value("--blocks", "what the watch blocks"),
       value("--resolves-when", "automatic resolution condition"),
+      value("--reason", "withdrawal reason"),
       toggle("--json", "print watch list as stable JSON"),
       project(),
     ],
-    positionals: [{ name: "action" }],
+    positionals: [{ name: "action" }, { name: "id" }],
   },
   {
     name: "intake",

package/src/commands/arm.ts

@@ -12,14 +12,17 @@ import { withProgress } from "../ui/progress.ts";
 
 export async function armCommand(ctx: CommandContext): Promise<void> {
 for (const project of ctx.targetProjects()) {
+  // Proof-neutral wording: `claim-only` performs no Telegram send, so the
+  // progress line cannot promise a challenge that never goes out (#613). The
+  // result line names the proof that actually armed it.
   const r = await withProgress(
-    "arm: sending inbound Telegram challenge…",
-    "Inbound Telegram round-trip proved",
+    "arm: verifying the arming proof…",
+    "Arming proof verified",
     () => armTicks(project.name),
     { plainMessage: true },
   );
   process.stdout.write(
-    `ARMED — inbound round-trip proved with owner ${r.owner}; ticks are now live.\n` +
+    `ARMED — ${r.proof === "claim-only" ? "claim-only plumbing verdict proved" : `inbound round-trip proved with owner ${r.owner}`}; ticks are now live.\n` +
       `marker ${r.path}${r.alreadyArmed ? " (replaced previous marker)" : ""}\n`,
   );
 }

package/src/commands/message.ts

@@ -15,10 +15,11 @@
 
 import type { CommandContext } from "./context.ts";
 import { randomUUID } from "node:crypto";
+import { availabilityState, formatNextWindowOpening } from "../availability.ts";
 import { findProject, loadConfig } from "../config.ts";
 import { deliverOperatorMessage, operatorMessageCategory, type OperatorMessageOutcome } from "../reports.ts";
 import { dbPath, openStore } from "../store.ts";
-import { INTERRUPT_CATEGORIES, type DecisionRecord, type InterruptCategory } from "../types.ts";
+import { INTERRUPT_CATEGORIES, type DecisionRecord, type InterruptCategory, type ProjectConfig } from "../types.ts";
 import { validateQuestionShape } from "../ask.ts";
 
 /** The floor's "this needs an answer" marker, as every other classifier reads it. */
@@ -96,8 +97,35 @@ export async function messageCommand(ctx: CommandContext): Promise<void> {
       ? // Not "into the topic": a stale topic degrades to the flat chat with
         // its own warning on stderr, and this line must not contradict it.
         `message delivered to ${project.name}'s configured Telegram target (${outcome.category})\n`
-      : `held notice ${outcome.noticeId} queued for ${project.name} (${outcome.category}; ` +
-          `${outcome.reason === "availability" ? "outside the availability window" : "a digest-only category"})\n` +
-          "nothing was sent; the daemon releases it with the next digest or working-hours catch-up\n",
+      : heldLine(project, outcome),
+  );
+}
+
+/** The held-notice line names the future that releases it, in words an
+ *  operator can act on: the working-hours window opening, or the daily digest.
+ *  The earlier spelling — "the next digest or working-hours catch-up" — read
+ *  the same for both and hid exactly the 23-hour hold that #596 is about. */
+function heldLine(
+  project: ProjectConfig,
+  outcome: Extract<OperatorMessageOutcome, { kind: "held" }>,
+): string {
+  if (outcome.reason === "availability") {
+    const state = availabilityState(project.reporting, Date.now());
+    const opening =
+      state.mode === "quiet" && state.nextTransitionAt !== undefined && state.timezone !== undefined
+        ? ` at ${formatNextWindowOpening(state.nextTransitionAt, state.timezone)}`
+        : "";
+    return (
+      `held notice ${outcome.noticeId} queued for ${project.name} (${outcome.category}; ` +
+      `held until the working-hours window opens${opening})\n` +
+      "nothing was sent; the daemon releases it with the working-hours catch-up when your window opens\n"
+    );
+  }
+  const digestAt = project.reporting?.digest.at;
+  const when = digestAt === undefined ? "the next digest" : `the ${digestAt} digest`;
+  return (
+    `held notice ${outcome.noticeId} queued for ${project.name} (${outcome.category}; ` +
+    `digest-only — held until ${when})\n` +
+    `nothing was sent; the daemon releases it with ${when}\n`
   );
 }

package/src/commands/watch.ts

@@ -10,6 +10,12 @@
  * next tick should read, neither of which ever needs an operator answer. It is
  * distinguished durably by its `kind`, never by whether it carries a
  * condition — a real question may carry one too.
+ *
+ * Watches are decision rows with `kind === "watch"`, so `watch withdraw`
+ * delegates to the same store resolution `decision withdraw` uses rather than
+ * inventing a second mechanism: both verbs write the same durable terminal
+ * state with a recorded reason, and a watch id remains acceptable to `decision
+ * withdraw` for anyone who learned that vocabulary first (#664).
  */
 
 import type { CommandContext } from "./context.ts";
@@ -17,8 +23,25 @@ import { findProject, loadConfig } from "../config.ts";
 import { CONDITION_FORMS, parseCondition } from "../decisions.ts";
 import { dbPath, openStore } from "../store.ts";
 
+const WATCH_USAGE = `omp-conductor watch — set a condition or carry note for the orchestrator itself.
+
+usage:
+  omp-conductor watch add --note TEXT [--blocks TEXT] [--resolves-when COND] [--project NAME]
+  omp-conductor watch list [--project NAME] [--json]
+  omp-conductor watch withdraw <id> [--reason TEXT] [--project NAME]
+
+add records a row the daemon checks for you and the next tick reads, with no
+operator answer needed. list shows open watches, oldest first. withdraw ends
+one with a recorded reason — the verb that creates a watch is the verb that
+ends it. A watch whose PR condition can no longer be observed (the PR merged
+or closed first) is withdrawn by the daemon itself.`;
+
 export async function watchCommand(ctx: CommandContext): Promise<void> {
   const sub = ctx.argv[1];
+  if (sub === "--help" || sub === "-h") {
+    process.stdout.write(WATCH_USAGE);
+    return;
+  }
   const project = findProject(loadConfig(), ctx.projectFlag);
   const store = openStore(dbPath());
   try {
@@ -45,7 +68,9 @@ export async function watchCommand(ctx: CommandContext): Promise<void> {
         at: Date.now(),
       });
       const wake = condition === undefined ? "read by the next tick" : "the daemon wakes the next tick when it is met";
-      process.stdout.write(`watch ${watch.id} added — ${wake} (no operator answer needed)\n`);
+      process.stdout.write(
+        `watch ${watch.id} added — ${wake} (no operator answer needed); end with: omp-conductor watch withdraw ${watch.id}\n`,
+      );
       return;
     }
 
@@ -70,14 +95,48 @@ export async function watchCommand(ctx: CommandContext): Promise<void> {
       for (const watch of watches) {
         process.stdout.write(
           `${watch.id}  ${watch.ageHours}h  blocks:${watch.blocks ?? "-"}  ` +
-            `condition:${watch.condition ?? "-"}  ${watch.note}\n`,
+            `condition:${watch.condition ?? "-"}  ${watch.note}  (end: omp-conductor watch withdraw ${watch.id})\n`,
+        );
+      }
+      return;
+    }
+
+    if (sub === "withdraw") {
+      const id = ctx.argv[2];
+      if (id === undefined || id.startsWith("--")) {
+        process.stderr.write("omp-conductor: watch withdraw needs the watch id\n");
+        process.exit(2);
+      }
+      const row = store.decision(id);
+      if (row !== undefined && row.kind !== "watch") {
+        // The same underlying row, but a question answers to a human: the
+        // watch verb must not silently close an operator decision.
+        process.stderr.write(
+          `omp-conductor: watch withdraw targets watches — ${id} is an operator decision; use decision withdraw\n`,
+        );
+        process.exit(2);
+      }
+      const reason = ctx.flag("reason")?.trim();
+      const ok = store.resolveDecision(
+        id,
+        "withdrawn",
+        reason === undefined || reason.length === 0 ? "withdrawn" : reason,
+        Date.now(),
+      );
+      if (!ok) {
+        // A watch that is not open is a different mistake from an id that
+        // never existed, and the operator can only act on one of them.
+        process.stderr.write(
+          `omp-conductor: no open watch ${id} for ${project.name} — it was already withdrawn, or the id is wrong\n`,
         );
+        process.exit(1);
       }
+      process.stdout.write(`watch ${id} withdrawn\n`);
       return;
     }
 
     process.stderr.write(
-      `omp-conductor: unknown watch subcommand "${sub}" — expected add or list\n`,
+      `omp-conductor: unknown watch subcommand "${sub}" — expected add, list or withdraw\n`,
     );
     process.exit(2);
   } finally {

package/src/config-schema.ts

@@ -22,13 +22,17 @@
 
 import { z } from "zod";
 import {
+  ARM_PROOFS,
   AUTHORITY_HOLDERS,
   BASE_FRESHNESS,
   BEHIND_BASE_ACTIONS,
   CONFIG_VERSION,
+  DEFAULT_ARM_PROOF,
   DEFAULT_AUTHORITY,
   DEFAULT_CAPS,
   DEFAULT_PROJECT_POLICY,
+  DEFAULT_REVIEW_MAX_ROUNDS,
+  DEFAULT_REVIEW_STRICTNESS,
   DRAFT_POLICIES,
   INTERRUPT_CATEGORIES,
   LEGACY_RELEASE_POLICIES,
@@ -37,6 +41,9 @@ import {
   RELEASE_REQUIREMENTS,
   RELEASE_SHAPES,
   REPORT_SCOPES,
+  REVIEW_MAX_ROUNDS_MAX,
+  REVIEW_MAX_ROUNDS_MIN,
+  REVIEW_STRICTNESS,
   WEEKDAYS,
   DIGEST_CADENCES,
 } from "./types.ts";
@@ -63,6 +70,7 @@ const RELEASE_REQUIREMENT_LIST = quoteList(RELEASE_REQUIREMENTS);
 const RELEASE_SHAPE_LIST = quoteList(RELEASE_SHAPES);
 const ORCHESTRATOR_MODE_LIST = quoteList(ORCHESTRATOR_MODES);
 const LEGACY_RELEASE_POLICY_LIST = quoteList(LEGACY_RELEASE_POLICIES);
+const REVIEW_STRICTNESS_LIST = quoteList(REVIEW_STRICTNESS);
 
 // ---------------------------------------------------------------------------
 // Closed vocabularies — every one built from the exported `as const` array in
@@ -81,6 +89,7 @@ const releaseRequirementEnum = z.enum([...RELEASE_REQUIREMENTS]);
 const releaseShapeEnum = z.enum([...RELEASE_SHAPES]);
 const orchestratorModeEnum = z.enum([...ORCHESTRATOR_MODES]);
 const releasePolicyLegacyEnum = z.enum([...LEGACY_RELEASE_POLICIES]);
+const reviewStrictnessEnum = z.enum([...REVIEW_STRICTNESS]);
 
 /** The 24-hour `HH:MM` shape `digest.at` / `availability.start/end` take. */
 const HHMM = /^([01]\d|2[0-3]):[0-5]\d$/;
@@ -239,6 +248,42 @@ const escalationSchema = z
   })
   .strict();
 
+/**
+ * The per-project arming gate (conductor #613): how `arm` proves a human just
+ * approved dispatch. Absent or a legacy config without the key loads as
+ * `challenge` — the authenticated round-trip, which is what existing installs
+ * already run. `claim-only` arms on the shared live-plumbing verdict with no
+ * Telegram send or wait, so an unattended recovery can re-arm a project that
+ * opted in.
+ */
+const armSchema = z
+  .object({
+    proof: z.enum([...ARM_PROOFS]).default(DEFAULT_ARM_PROOF),
+  })
+  .strict()
+  .describe("How `arm` proves a human just approved arming");
+
+/**
+ * The per-project review policy (#678): how strictly green PRs are reviewed
+ * and returned, and the hard ceiling on review rounds per PR lifecycle. Absent
+ * or a legacy config without the key loads as `medium` with
+ * {@link DEFAULT_REVIEW_MAX_ROUNDS} rounds — the recommended default for a new
+ * project, materialised deterministically for every existing one, with the
+ * schema bounds and the runtime defaults read from the same constants.
+ */
+const reviewSchema = z
+  .object({
+    strictness: reviewStrictnessEnum.default(DEFAULT_REVIEW_STRICTNESS),
+    maxRounds: z
+      .number()
+      .int()
+      .min(REVIEW_MAX_ROUNDS_MIN)
+      .max(REVIEW_MAX_ROUNDS_MAX)
+      .default(DEFAULT_REVIEW_MAX_ROUNDS),
+  })
+  .strict()
+  .describe("Review strictness and round ceiling for green PRs");
+
 const releasePolicySchema = z.union([
   releasePolicyLegacyEnum,
   z.record(z.string(), authorityHolderEnum),
@@ -287,6 +332,7 @@ const stateLabelsSchema = z
     inProgress: z.unknown(),
     blocked: z.unknown(),
     failed: z.unknown(),
+    backlog: z.unknown(),
   })
   .partial();
 
@@ -330,6 +376,12 @@ const projectSchema = z
     // overlay); anything else is dropped by the loader, like `workerModel`.
     workerAdvisor: z.unknown().optional(),
     escalation: escalationSchema.optional(),
+    // How `arm` proves a human approved arming (#613); absent loads as
+    // `challenge`, preserving today's authenticated round-trip.
+    arm: armSchema.optional(),
+    // Review strictness and the round ceiling (#678); absent loads as the
+    // documented migration default.
+    review: reviewSchema.optional(),
     authority: authoritySchema.optional(),
     releasePolicy: releasePolicySchema.optional(),
     policy: projectPolicySchema.optional(),
@@ -428,4 +480,5 @@ export {
   RELEASE_SHAPE_LIST,
   ORCHESTRATOR_MODE_LIST,
   LEGACY_RELEASE_POLICY_LIST,
+  REVIEW_STRICTNESS_LIST,
 };