omp-conductor 0.17.0 → 0.18.0

package/src/setup.ts

@@ -8,7 +8,8 @@
  * least tested code in the package.
  *
  * Two functions here mutate something outside the process: `createMissingLabels`
- * and `writeOrchestratorBrief`. Everything else reads, or computes. That is what
+ * (and its rollback compensation half, `deleteCreatedLabels`) and
+ * `writeOrchestratorBrief`. Everything else reads, or computes. That is what
  * lets the plugin show a complete plan before asking for consent, and it is a
  * property worth preserving — check it before adding a function.
  *
@@ -38,11 +39,14 @@ import {
 import {
   clonePolicy,
   configPath,
+  DEFAULT_STATE_LABELS,
   defaultMirrorRoot,
   defaultWorkspaceRoot,
+  resolveArmProof,
   resolveCaps,
   resolvePolicy,
   resolveReleaseGrants,
+  resolveReview,
   SCOPE_PRESETS,
   stateDir,
 } from "./config.ts";
@@ -50,13 +54,17 @@ import { graphProjectPath, graphRepos } from "./graph.ts";
 import { ompSettingsOverlay } from "./omp-settings.ts";
 import {
   CONFIG_VERSION,
+  DEFAULT_ARM_PROOF,
   DEFAULT_AUTHORITY,
   DEFAULT_CAPS,
   DEFAULT_PROJECT_POLICY,
   DEFAULT_REPORT_SCOPE,
+  DEFAULT_REVIEW_POLICY,
   DENIED_RELEASE_GRANTS,
   RELEASE_SHAPES,
+  REVIEW_STRICTNESS,
   WEEKDAYS,
+  type ArmProof,
   type BaseFreshness,
   type BehindBaseAction,
   type AuthorityHolder,
@@ -71,6 +79,8 @@ import {
   type ReleaseRequirement,
   type ReportScopeChoice,
   type ReportingPolicy,
+  type ReviewPolicy,
+  type ReviewStrictness,
   type Weekday,
   type WeeklyAvailability,
   type RepoTarget,
@@ -205,6 +215,19 @@ export interface SetupAnswers {
    * leave one to be defaulted by whichever reader gets there first.
    */
   policy: ProjectPolicy;
+  /**
+   * How `arm` proves a human just approved arming (#613). Always complete:
+   * the wizard asks about it in the policy area, so an answers object can never
+   * leave it to be defaulted by whichever reader gets there first.
+   */
+  armProof: ArmProof;
+  /**
+   * How green PRs are reviewed and returned (#678): the strictness level and
+   * the hard ceiling on review rounds per PR lifecycle. Always complete: the
+   * wizard asks about it in the policy area, so an answers object can never
+   * leave it to be defaulted by whichever reader gets there first.
+   */
+  review: ReviewPolicy;
   /**
    * Hand-edited recovery merge authorizations carried through setup unchanged.
    * The wizard never grants one; forgetting them during an unrelated amend
@@ -304,6 +327,8 @@ export const SETUP_DEFAULTS = {
   releaseGrants: DENIED_RELEASE_GRANTS,
   /** The strictest reading of the prose these conditions replaced (#129). */
   policy: DEFAULT_PROJECT_POLICY,
+  /** The recommended review strictness and its default ceiling (#678). */
+  review: DEFAULT_REVIEW_POLICY,
   /** The daemon runs its own triage session unless an operator already runs one. */
   orchestratorMode: "embedded",
 } as const;
@@ -381,8 +406,52 @@ export const BEHIND_BASE_CHOICES: { readonly [K in BehindBaseAction]: string } =
   escalate: "page a human rather than guess",
 };
 
+/**
+ * What each arming proof means to the operator being asked about it, in their
+ * words rather than the gate's (conductor #613). The `claim-only` consequence
+ * is the one line the issue contract requires the question to state: anything
+ * that can invoke the already-privileged `omp-conductor arm` command can start
+ * dispatch once the live claim and poller pass. Mapped over the closed union
+ * so a third proof fails to compile here instead of reaching a wizard with no
+ * question for it.
+ */
+export const ARM_PROOF_CHOICES: { readonly [K in ArmProof]: string } = {
+  challenge: "an authenticated Telegram challenge proves a human just approved arming",
+  "claim-only": "anyone who can invoke the already-privileged `omp-conductor arm` command can start dispatch once the live claim and poller pass",
+};
+
+/**
+ * What each review strictness blocks, in the operator's words, and the single
+ * canonical phrasing of the three bars (#678).
+ *
+ * Mapped over the closed union for the reason {@link MERGE_DUTY} is: a fourth
+ * level fails to compile here instead of reaching a wizard with no question for
+ * it, an amend row that cannot describe it, and a rendered brief that shows it
+ * blank. Each sentence is self-contained — "Low's bar" would reference prose
+ * the brief may not be rendering — and it is the *same* text the wizard shows
+ * one level at a time and the composed orchestrator brief carries for the
+ * configured level, so the definition an operator chose is the threshold a
+ * session enforces.
+ *
+ * The two consumers read this map rather than their own prose: the setup
+ * dialog explains every level from it, and {@link reviewDuty} renders the
+ * effective one from it. "One canonical implementation, not duplicated prose
+ * branches" is this object.
+ */
+export const REVIEW_STRICTNESS_CHOICES: { readonly [K in ReviewStrictness]: string } = {
+  low: "correctness, security, data-loss or explicit acceptance-criteria failures — anything else stays a review comment",
+  medium:
+    "correctness, security, data-loss or explicit acceptance-criteria failures, plus material maintainability or " +
+    "reliability defects likely to become incidents within six months — anything else stays a review comment",
+  high:
+    "correctness, security, data-loss or explicit acceptance-criteria failures, plus material maintainability or " +
+    "reliability defects likely to become incidents within six months, plus concrete quality defects — never " +
+    "subjective style churn or unbounded refactoring",
+};
+
 export const RELEASE_REQUIREMENT_CHOICES: { readonly [K in ReleaseRequirement]: string } = {
-  "runs-settled": "every run this release covers actually merged, not merely reached a green PR",
+  "runs-settled": "every run of the released repo actually merged, not merely reached a green PR",
+  "fleet-runs-settled": "every run in the project actually merged — suite-wide strictness for shapes that consume several repos",
   "no-open-prs": "no pull request is still open against the branch being released",
   "queue-drained": "nothing still carries the queue label",
   "base-branch-green": "the newest observed post-merge base-branch workflows are green",
@@ -440,6 +509,34 @@ export const MERGE_DUTY: { readonly [K in ProjectConfig["authority"]["merge"]]:
     "  one is a hard boundary, not a preference.",
 };
 
+/**
+ * Duty 1's review-return contract, worded from `project.review` (#678).
+ *
+ * One canonical implementation rather than prose branches in the template: the
+ * configured level's bar is the same {@link REVIEW_STRICTNESS_CHOICES} text
+ * the setup dialog explains each level with, and the ceiling is the configured
+ * number — so the strictness an operator chose in setup and the threshold this
+ * session enforces cannot diverge. The paragraph names `conductor_pr_review`
+ * (the #677 verb) as the only return path and states the three ceiling
+ * behaviours: leave the PR open, record the unresolved findings, escalate once.
+ */
+export function reviewDuty(p: ProjectConfig): string {
+  const { strictness, maxRounds } = resolveReview(p);
+  return (
+    "\n" +
+    "**Review policy:** before you merge (or settle) a green PR, review it at\n" +
+    `this project's strictness. The level is **${strictness}**: ` +
+    `${REVIEW_STRICTNESS_CHOICES[strictness]}. ` +
+    "`conductor_pr_review` is the verb for findings at or above that bar, and\n" +
+    "for nothing else — anything below it stays a review comment on the PR,\n" +
+    "never a return. Every corrected head gets a fresh review, up to a hard\n" +
+    `ceiling of ${maxRounds} ${maxRounds === 1 ? "round" : "rounds"} per PR lifecycle, visible in ` +
+    "`omp-conductor status` as `review-revision N`. At the ceiling\n" +
+    "`conductor_pr_review` refuses: leave the PR open, record the unresolved\n" +
+    "findings, and escalate once — never a further round."
+  );
+}
+
 /**
  * The Promotion paragraph, worded from `authority.promotion`.
  *
@@ -700,11 +797,33 @@ export async function createMissingLabels(trackerRepo: string, plan: LabelPlan[]
       continue;
     }
     if (/already exists/i.test(r.stderr)) continue;
-    throw new Error(`Could not create label "${label.name}" in ${trackerRepo}: ${briefly(r.stderr)}`);
+    // The labels created before this one failed ride on the error: the setup
+    // transaction compensates the tracker exactly, and a throw without the
+    // partial list would orphan them (#652).
+    throw Object.assign(
+      new Error(`Could not create label "${label.name}" in ${trackerRepo}: ${briefly(r.stderr)}`),
+      { created },
+    );
   }
   return created;
 }
 
+/**
+ * Compensation half of {@link createMissingLabels}: deletes exactly the labels
+ * a failed setup apply created, so the tracker returns to its pre-entry state.
+ * Runs only on rollback, where a deletion failure is a reported restoration
+ * failure — the orphaned label is named, never silently left behind (#652).
+ */
+export async function deleteCreatedLabels(trackerRepo: string, created: string[]): Promise<void> {
+  const failures: string[] = [];
+  for (const name of created) {
+    const r = await gh(["label", "delete", name, "--repo", trackerRepo, "--yes"]);
+    if (r.code === 0 || /not found/i.test(r.stderr)) continue;
+    failures.push(`could not delete label "${name}" in ${trackerRepo}: ${briefly(r.stderr)}`);
+  }
+  if (failures.length > 0) throw new Error(failures.join("; "));
+}
+
 const QUIET_INTERRUPT_ON: InterruptCategory[] = [
   "tier2",
   "fleet-stopped",
@@ -854,7 +973,7 @@ export function buildProject(a: SetupAnswers): ProjectConfig {
     name: a.projectName,
     tracker: { kind: "github", repo: a.trackerRepo },
     queueLabel: a.queueLabel,
-    stateLabels: { ...a.stateLabels },
+    stateLabels: { ...a.stateLabels, backlog: DEFAULT_STATE_LABELS.backlog },
     routing: { labelPrefix: a.routingLabelPrefix, repos },
     caps,
     ...(a.workerModel !== undefined && a.workerModel.trim().length > 0
@@ -877,6 +996,14 @@ export function buildProject(a: SetupAnswers): ProjectConfig {
     // Written out in full for the same reason: the file then says what a merge
     // and a release require without anyone having to know a default (#129).
     policy: clonePolicy(a.policy),
+    // Written out even when it is the default, so an operator amending the
+    // policy has a line in the file to point at — and the recovery playbook
+    // can read which proof the project opted into (#613).
+    arm: { proof: a.armProof },
+    // Written out in full for the same reason as `arm`: the file then carries
+    // the strictness and the ceiling an operator chose, without anyone having
+    // to know a migration rule (#678).
+    review: { ...a.review },
     ...(a.recoveryMerges === undefined
       ? {}
       : { recoveryMerges: a.recoveryMerges.map((entry) => ({ ...entry })) }),
@@ -964,6 +1091,13 @@ export function defaultAnswers(projectName: string, opts: { added?: boolean } =
     authority: { ...SETUP_DEFAULTS.authority },
     releaseGrants: { ...SETUP_DEFAULTS.releaseGrants },
     policy: clonePolicy(SETUP_DEFAULTS.policy),
+    // The strict reading, matching the loader's absent-key default: a project
+    // that never answered keeps today's authenticated challenge round-trip.
+    armProof: DEFAULT_ARM_PROOF,
+    // First-run default: the recommended strictness and its ceiling, so a
+    // fresh project opens on the answer the issue recommends — and the loader
+    // materialises the same value for a config that has no key at all.
+    review: { ...SETUP_DEFAULTS.review },
     orchestratorMode: SETUP_DEFAULTS.orchestratorMode,
     reportScope: SETUP_DEFAULT_REPORT_SCOPE,
     writeOrchestratorBrief: false,
@@ -1060,6 +1194,13 @@ export function answersFromProject(p: ProjectConfig): SetupAnswers {
     authority: { ...p.authority },
     releaseGrants: resolveReleaseGrants(p),
     policy: resolvePolicy(p),
+    // The loader materialises `arm` complete, so this is the answer the project
+    // actually has — never a default guessed at the amend prompt.
+    armProof: resolveArmProof(p),
+    // Same reason as `armProof`: the loader materialises `review` complete, so
+    // a re-run preserves the configured strictness and ceiling rather than
+    // opening on a default the operator already answered.
+    review: resolveReview(p),
     orchestratorMode: p.escalation.orchestrator,
     reportScope: reportScopeFromPolicy(p.reporting),
     writeOrchestratorBrief: false,
@@ -1127,6 +1268,7 @@ function briefVarsForProject(p: ProjectConfig): Record<string, string> {
     QUEUE_LABEL: p.queueLabel,
     RELEASES_DEFAULT: RELEASES_DEFAULTS[`${p.authority.merge}/${p.authority.release}`],
     MERGE_DUTY: MERGE_DUTY[p.authority.merge],
+    REVIEW_DUTY: reviewDuty(p),
     PROMOTION_DUTY: PROMOTION_DUTIES[p.authority.promotion ?? DEFAULT_AUTHORITY.promotion],
     POLICY_SOURCE: policySourceLine(p),
   };
@@ -1636,6 +1778,9 @@ export function summarisePlan(
     `  environments ${a.policy.release.environments.join(", ") || "none declared — every deploy target is refused"}`,
   );
 
+  lines.push("", "review", `  strictness     ${a.review.strictness} — ${REVIEW_STRICTNESS_CHOICES[a.review.strictness]}`);
+  lines.push(`  max rounds/PR  ${a.review.maxRounds} — at the ceiling the PR is left open, the findings recorded, and it is escalated once`);
+
   const reporting = project.reporting as ReportingPolicy;
   const briefPath = orchestratorBriefPath(a);
   lines.push(
@@ -1852,16 +1997,18 @@ export const AMEND_AREAS: {
   },
   policy: {
     name: "merge & release preconditions",
-    asks: "the checks, base freshness, draft rule and behind-base action for a merge, then what a release requires and what it ships",
+    asks: "the checks, base freshness, draft rule and behind-base action for a merge, then what a release requires and what it ships — and how green PRs are reviewed, and how many rounds a PR may be returned",
     describe: (p) => {
       const policy = resolvePolicy(p);
+      const review = resolveReview(p);
       // Counted rather than listed: this row is elided at 96 characters, and the
       // full table is in the plan summary the consent screen shows next.
       return (
         `merge: ${policy.merge.requiredChecks.length === 0 ? "every check" : `${policy.merge.requiredChecks.length} check(s)`}, ` +
         `base ${policy.merge.baseFreshness}, drafts ${policy.merge.drafts}, behind → ${policy.merge.whenBehindBase}; ` +
         `release: ${policy.release.requires.length} must-land, ${policy.release.artefacts.length} artefact(s), ` +
-        `${policy.release.environments.length} env(s)`
+        `${policy.release.environments.length} env(s); ` +
+        `review ${review.strictness} ×${review.maxRounds}`
       );
     },
   },

package/src/status-render.ts

@@ -22,7 +22,7 @@ import type { DaemonStop } from "./types.ts";
 import { settlementFlagSummary } from "./diff-flags.ts";
 import type { CodeGraphHealth } from "./graph-health.ts";
 import { formatDigestBacklog, formatOpenReports } from "./reports.ts";
-import { formatOrchestratorDown } from "./orchestrator-down.ts";
+import { formatDownDuration, formatOrchestratorDown } from "./orchestrator-down.ts";
 import { planUsageLine } from "./usage.ts";
 import { SYSTEMD_UNIT, type UnitOwnership } from "./lifecycle.ts";
 import type { WorkerPausePhase } from "./worker.ts";
@@ -32,12 +32,12 @@ import {
   formatDispatchSummary,
   formatFreezes,
   formatReleaseGrants,
-  formatSalvagedRuns,
   isPaused,
   pausedAt,
   pauseProvenance,
   type StatusSnapshot,
 } from "./daemon.ts";
+import { formatQuarantinedRuns, formatSalvagedRuns } from "./settlement.ts";
 
 // layered status
 // ---------------------------------------------------------------------------
@@ -405,6 +405,13 @@ function formatProjectBody(
     `  continuations      ${s.caps.maxContinuationsPerIssue}`,
     "",
     ...formatReleaseGrants(s.releaseGrants),
+    // The effective review policy (#678), read from the same snapshot surface
+    // as the grants: the level is what Duty 1 judges findings against, and the
+    // ceiling is its hard bound — an orchestrator reading `review-revision N`
+    // below has to see both without opening the config.
+    "review",
+    `  strictness       ${s.review.strictness}`,
+    `  max rounds/PR    ${s.review.maxRounds}`,
     "",
     formatDispatchSummary(s.dispatch),
     "",
@@ -415,10 +422,34 @@ function formatProjectBody(
     lines.push("active runs");
     for (const r of s.activeRuns) {
       const phase = workerPhases.get(r.issue);
-      const state = phase === "pausing" || phase === "paused" ? phase : r.state;
+      // A run in a live review round reads `review-revision N`, distinct from
+      // a failure and from an ordinary continuation, with the round number
+      // from the durable revision row (#692). The live pause overlay still
+      // wins: an operator pause is the newer fact about the same session.
+      const paused = phase === "pausing" || phase === "paused";
+      const round = s.reviewRounds?.[r.id];
+      const state = paused
+        ? phase
+        : round !== undefined
+          ? `review-revision ${round}`
+          : r.state;
+      // Turn rate (#730): a stalled run and a fast one used to render
+      // identically as a bare turn count. The rate is the lifetime average
+      // over the elapsed shown — the snapshot carries no checkpoint from
+      // which a recent-interval rate could be derived — so it is labelled
+      // `avg`, and `elapsed` is elapsed since claim, never "remaining wall
+      // clock": a paused worker banks its budget, which the snapshot cannot
+      // know. A paused run gets neither number, because its elapsed includes
+      // banked pause time and its state already says `paused`.
+      const elapsedMs = Math.max(0, now - r.startedAt);
+      const progress = paused
+        ? ""
+        : `  ${formatDownDuration(elapsedMs)} elapsed  ${(
+            (r.turns * 60_000) / Math.max(elapsedMs, 1_000)
+          ).toFixed(1)} turns/min avg`;
       lines.push(
         `  #${r.issue}  ${r.repo}  ${state}  attempt ${r.attempt}  ` +
-          `${r.turns}/${r.maxTurns} turns  ${r.spendUsd.toFixed(2)}  ${r.branch}` +
+          `${r.turns}/${r.maxTurns} turns${progress}  ${r.spendUsd.toFixed(2)}  ${r.branch}` +
           (r.prUrl ? `  ${r.prUrl}` : ""),
       );
       // The orchestrator's Duty 1 reads this command, and a flagged run's
@@ -431,6 +462,7 @@ function formatProjectBody(
   lines.push(...formatBaseHealth(s.baseHealth));
   lines.push(...formatFreezes(s.freezes));
   lines.push(...formatSalvagedRuns(s.salvagedRuns));
+  lines.push(...formatQuarantinedRuns(s.quarantinedRuns));
   lines.push(...formatOpenReports(s.openReports));
   lines.push(...formatDigestBacklog(s.digestBacklog));
   if (s.liveWorkers > 0) {