omp-conductor 0.15.10 → 0.15.12

package/src/setup.ts

@@ -29,8 +29,10 @@ import {
   POLICY_BRIEF_NAME,
   composeOrchestrator,
   policyPathForRoot,
+  readSharedPolicy,
   refreshComposedBrief,
   renderBriefTemplate,
+  sharedPolicyPath,
 } from "./brief-upgrade.ts";
 import {
   clonePolicy,
@@ -55,6 +57,7 @@ import {
   WEEKDAYS,
   type BaseFreshness,
   type BehindBaseAction,
+  type AuthorityHolder,
   type Caps,
   type ConductorConfig,
   type DigestCadence,
@@ -152,6 +155,14 @@ export interface SetupAnswers {
    * survive an amend of some other area (#369).
    */
   groomBelow?: number;
+  /**
+   * Ordered fallback worker models and the provider-failure threshold that
+   * starts them. The wizard never asks for either — they are hand-edited —
+   * so they exist here only to survive an amend of some other area (#369,
+   * #286).
+   */
+  modelFallbacks?: string[];
+  modelFallbackThreshold?: number;
   telegramChatId?: string;
   /** Forum topic for tier-2 Telegram pages; absent keeps flat-chat 0.13 behaviour. */
   telegramTopicId?: number;
@@ -190,6 +201,13 @@ export interface SetupAnswers {
    * merge provenance gate.
    */
   recoveryMerges?: ProjectConfig["recoveryMerges"];
+  /**
+   * Hand-edited critical-base/safety markers (commit SHAs or refs) carried
+   * through setup unchanged, like {@link recoveryMerges}. The wizard never
+   * invents one; forgetting them during an unrelated amend would drop the
+   * stale-base interlock from a project that relies on it (#428).
+   */
+  criticalBase?: ProjectConfig["criticalBase"];
   /**
    * Whether to render `ORCHESTRATOR.md` into the project's workspace root. Not
    * part of the config — the brief is the operator's file, and the conductor
@@ -411,6 +429,31 @@ export const MERGE_DUTY: { readonly [K in ProjectConfig["authority"]["merge"]]:
     "  one is a hard boundary, not a preference.",
 };
 
+/**
+ * The Promotion paragraph, worded from `authority.promotion`.
+ *
+ * The queue label is a sign-off: adding it to an issue lets a worker claim it
+ * and starts spend. POLICY.md must state who may do that — never a blank the
+ * floor defers into — and an unstated owner reads operator-only, because a
+ * gate nobody claimed must not resolve to the session that wants to use it.
+ *
+ * The paragraph refers to "the queue label" rather than naming it: the label
+ * itself is rendered into the section heading from config, and a second copy
+ * here would be a label that can disagree with the one the daemon reads.
+ */
+export const PROMOTION_DUTIES: { readonly [K in AuthorityHolder]: string } = {
+  human:
+    "**Default: the operator promotes.** Adding the queue label to an issue is promotion, and\n" +
+    "promotion is the operator's: the orchestrator grooms, routes and proposes, but the label\n" +
+    "goes on only when the operator puts it there — it is the sign-off that starts spend. To\n" +
+    "delegate, re-run `omp-conductor setup` or replace this paragraph with one naming the\n" +
+    "orchestrator as promoter.",
+  orchestrator:
+    "**Delegated in setup: the orchestrator promotes.** Adding the queue label to an issue is\n" +
+    "promotion, and the orchestrator may do it after grooming the issue, one at a time. The\n" +
+    "operator can take it back by editing this paragraph.",
+};
+
 export { ORCHESTRATOR_BRIEF_NAME, POLICY_BRIEF_NAME };
 
 /** Shipped floor template — duties, tiers, hard boundaries, Learning loop. */
@@ -427,12 +470,14 @@ const POLICY_TEMPLATE_PATH = join(import.meta.dir, "briefs", "policy.md");
 const REQUIRED_SCOPES = ["repo", "project"] as const;
 
 /** GitHub's own palette, so the tracker reads at a glance: green means queued,
- *  blue means moving, amber means waiting on you, red means it gave up. */
+ *  blue means moving, amber means waiting on you, red means it gave up, and
+ *  purple is routing — the operator's input, the one label the loop never writes. */
 const LABEL_COLOURS = {
   queue: "0e8a16",
   inProgress: "1d76db",
   blocked: "fbca04",
   failed: "b60205",
+  routing: "6f42c1",
 } as const;
 
 interface GhResult {
@@ -514,11 +559,18 @@ export async function checkTokenScopes(): Promise<ScopeCheck> {
 }
 
 /**
- * The four labels the loop reads and writes, and which already exist. Read-only:
- * this is what the operator is shown before being asked to consent to creation.
+ * Every label setup wants on the tracker, before existence is known: the queue
+ * and state labels the loop reads and writes, plus one routing label per routed
+ * repo. Pure — the prefix and the repo keys are already answered at this point
+ * in the interview — which is what lets a test pin the whole set without `gh`.
+ *
+ * Routing labels are provisioned, never applied: `route()` requires exactly one
+ * `<prefix><repo>` label per issue and treats zero or two as unroutable, so a
+ * tracker without them can queue nothing. Creating them queues nothing either —
+ * applying one, with the queue label, stays the operator's sign-off.
  */
-export async function planLabels(trackerRepo: string, a: SetupAnswers): Promise<LabelPlan[]> {
-  const wanted: Omit<LabelPlan, "exists">[] = [
+export function wantedLabels(a: SetupAnswers): Omit<LabelPlan, "exists">[] {
+  return [
     {
       name: a.queueLabel,
       colour: LABEL_COLOURS.queue,
@@ -539,13 +591,28 @@ export async function planLabels(trackerRepo: string, a: SetupAnswers): Promise<
       colour: LABEL_COLOURS.failed,
       description: "The conductor gave up on this issue after its retry budget",
     },
+    ...a.targetRepos.map((r) => ({
+      name: `${a.routingLabelPrefix}${r.name}`,
+      colour: LABEL_COLOURS.routing,
+      description: `Routes this issue to the ${r.name} checkout`,
+    })),
   ];
+}
 
-  const existing = await listLabelNames(trackerRepo);
-
-  // GitHub label names are unique case-insensitively, so an operator who answers
-  // "Ready-For-Agent" against an existing "ready-for-agent" must not be told a
-  // creation is pending that would then fail.
+/**
+ * Turns wanted labels into the plan the operator is shown, deduped
+ * case-insensitively and marked against what already exists.
+ *
+ * GitHub label names are unique case-insensitively, so an operator who answers
+ * "Ready-For-Agent" against an existing "ready-for-agent" must not be told a
+ * creation is pending that would then fail — and a multi-repo project whose
+ * names case-fold onto each other or onto a lifecycle label wants one creation,
+ * not two.
+ */
+export function planAgainstLabels(
+  wanted: readonly Omit<LabelPlan, "exists">[],
+  existing: ReadonlySet<string>,
+): LabelPlan[] {
   const seen = new Set<string>();
   const plan: LabelPlan[] = [];
   for (const w of wanted) {
@@ -557,6 +624,18 @@ export async function planLabels(trackerRepo: string, a: SetupAnswers): Promise<
   return plan;
 }
 
+/**
+ * The labels a tracker needs, and which already exist. Read-only: this is what
+ * the operator is shown before being asked to consent to creation.
+ *
+ * The queue and state labels are the ones the loop reads and writes; the
+ * routing labels (one per repo) are the operator's input that makes an issue
+ * routable, and setup provisions them only so there is something to apply.
+ */
+export async function planLabels(trackerRepo: string, a: SetupAnswers): Promise<LabelPlan[]> {
+  return planAgainstLabels(wantedLabels(a), await listLabelNames(trackerRepo));
+}
+
 /** Lower-cased label names currently on the repo. Throws rather than guessing:
  *  a repo whose labels cannot be listed cannot be serviced either. */
 async function listLabelNames(trackerRepo: string): Promise<Set<string>> {
@@ -772,6 +851,10 @@ export function buildProject(a: SetupAnswers): ProjectConfig {
       : {}),
     // A documented hand-edited key, so an unrelated amend must not delete it.
     ...(a.groomBelow === undefined ? {} : { groomBelow: a.groomBelow }),
+    // The failover chain is hand-edited too: dropping it on an unrelated amend
+    // would pin every run of the project onto a dead provider again (#286).
+    ...(a.modelFallbacks === undefined ? {} : { modelFallbacks: [...a.modelFallbacks] }),
+    ...(a.modelFallbackThreshold === undefined ? {} : { modelFallbackThreshold: a.modelFallbackThreshold }),
     escalation,
     authority: { ...a.authority },
     // Written out in full, never as the legacy string: the file then says which
@@ -783,6 +866,9 @@ export function buildProject(a: SetupAnswers): ProjectConfig {
     ...(a.recoveryMerges === undefined
       ? {}
       : { recoveryMerges: a.recoveryMerges.map((entry) => ({ ...entry })) }),
+    // Hand-edited safety markers carried unchanged on an unrelated amend
+    // (#428): dropping them would silently disarm the stale-base interlock.
+    ...(a.criticalBase === undefined ? {} : { criticalBase: [...a.criticalBase] }),
     // Written out even when it is the default, so an operator amending the
     // volume has a line in the file to point at. Opting into availability makes
     // the schedule explicit and daily; omitting it preserves the preset's
@@ -973,11 +1059,14 @@ export function answersFromProject(p: ProjectConfig): SetupAnswers {
   // what keeps the rewritten config identical to the one that was read.
   if (p.workerModel !== undefined) answers.workerModel = p.workerModel;
   if (p.groomBelow !== undefined) answers.groomBelow = p.groomBelow;
+  if (p.modelFallbacks !== undefined) answers.modelFallbacks = [...p.modelFallbacks];
+  if (p.modelFallbackThreshold !== undefined) answers.modelFallbackThreshold = p.modelFallbackThreshold;
   if (p.escalation.telegramChatId !== undefined) answers.telegramChatId = p.escalation.telegramChatId;
   if (p.escalation.telegramTopicId !== undefined) answers.telegramTopicId = p.escalation.telegramTopicId;
   if (p.recoveryMerges !== undefined) {
     answers.recoveryMerges = p.recoveryMerges.map((entry) => ({ ...entry }));
   }
+  if (p.criticalBase !== undefined) answers.criticalBase = [...p.criticalBase];
   if (p.reporting?.digest.at !== undefined) answers.dailyDigestAt = p.reporting.digest.at;
   if (p.reporting?.digest.timezone !== undefined) {
     answers.reportingTimezone = p.reporting.digest.timezone;
@@ -1023,6 +1112,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],
+    PROMOTION_DUTY: PROMOTION_DUTIES[p.authority.promotion ?? DEFAULT_AUTHORITY.promotion],
     POLICY_SOURCE: policySourceLine(p),
   };
 }
@@ -1073,14 +1163,19 @@ export function renderPolicyForProject(p: ProjectConfig): string {
 }
 
 /**
- * Composed session brief: rendered floor + POLICY scaffold (or a caller's policy).
+ * Composed session brief: rendered floor + shared policy (when present) +
+ * POLICY scaffold (or a caller's policy).
  *
  * Setup writes the policy half to `POLICY.md` and this compose to
- * `ORCHESTRATOR.md`. Later ticks recompose from the live POLICY.md so package
- * floor updates apply without brief-upgrade.
+ * `ORCHESTRATOR.md`. Later ticks recompose from the live POLICY.md and the live
+ * host-wide shared policy, so package floor updates apply without brief-upgrade.
  */
 export function renderBriefForProject(p: ProjectConfig, policyText?: string): string {
-  return composeOrchestrator(renderFloorForProject(p), policyText ?? renderPolicyForProject(p));
+  return composeOrchestrator(
+    renderFloorForProject(p),
+    policyText ?? renderPolicyForProject(p),
+    readSharedPolicy(),
+  );
 }
 
 /** Wizard-time path, via the project the answers describe. */
@@ -1094,7 +1189,7 @@ export function renderOrchestratorBrief(a: SetupAnswers, prose: ProbedProse = {}
   // would write" and "what setup writes" cannot diverge — the preview an operator
   // consents to is the file they get.
   const project = buildProject(a);
-  return composeOrchestrator(renderFloorForProject(project), renderPolicy(a, prose));
+  return composeOrchestrator(renderFloorForProject(project), renderPolicy(a, prose), readSharedPolicy());
 }
 
 /** `POLICY.md` for these answers: the project's own template plus the interview. */
@@ -1149,7 +1244,7 @@ export function writeOrchestratorBrief(a: SetupAnswers, prose: ProbedProse = {})
   mkdirSync(dirname(orchestratorPath), { recursive: true });
   const policy = renderPolicy(a, prose);
   writeFileSync(policyPath, policy);
-  writeFileSync(orchestratorPath, composeOrchestrator(renderFloorForProject(project), policy));
+  writeFileSync(orchestratorPath, composeOrchestrator(renderFloorForProject(project), policy, readSharedPolicy()));
   return orchestratorPath;
 }
 
@@ -1246,7 +1341,8 @@ function releaseLines(j: OperatorJudgment): string[] {
 }
 
 /**
- * Recompose `ORCHESTRATOR.md` from the package floor + live `POLICY.md`.
+ * Recompose `ORCHESTRATOR.md` from the package floor + host-wide shared policy
+ * (when present) + live `POLICY.md`.
  *
  * Returns false when POLICY.md is missing (caller should migrate or set up).
  */
@@ -1255,6 +1351,7 @@ export function refreshComposedBriefForProject(p: ProjectConfig): boolean {
     policyPath: policyPathForProject(p),
     orchestratorPath: briefPathForProject(p),
     floor: renderFloorForProject(p),
+    sharedPolicyPath: sharedPolicyPath(),
   });
 }
 
@@ -1355,6 +1452,15 @@ function describeAvailabilityDays(days: readonly Weekday[]): string {
     : days.join(",");
 }
 
+/**
+ * The caps table's key column. Wide enough that the longest cap key,
+ * `maxConcurrentWorkersPerRepo`, cannot fuse with its value — the very defect
+ * that made #448's consent screen read `maxConcurrentWorkersPerRepo1` while
+ * the daemon ran 3. Exported so tests pin the rendered table against the same
+ * column the renderer uses.
+ */
+export const CAPS_PLAN_KEY_PAD = 28;
+
 /**
  * Everything that would change, as plain text, with no side effects at all.
  *
@@ -1368,11 +1474,15 @@ export function summarisePlan(
   scopes: ScopeCheck,
   labels: LabelPlan[],
   tg: TelegramPresence,
+  defaults: Caps = DEFAULT_CAPS,
 ): string {
   const project = buildProject(a);
-  // Caps are shown against the shipped baseline: the summary describes what
-  // these answers mean on their own, before any hand-edited global block.
-  const effective = resolveCaps(project, DEFAULT_CAPS);
+  // Caps are resolved against the caller's defaults — the loaded config's
+  // global block on a re-run, the shipped baseline on a first run, where the
+  // two are the same object. That is the exact baseline the daemon resolves
+  // against, so the consent screen and runtime cannot disagree (#372/#448).
+  // The shipped baseline itself is never labelled "effective".
+  const effective = resolveCaps(project, defaults);
   const states = Object.values(a.stateLabels).join(", ");
 
   const lines: string[] = [];
@@ -1441,10 +1551,10 @@ export function summarisePlan(
   lines.push("", "caps (effective)");
   for (const [key, value] of Object.entries(effective)) {
     const answered = Object.hasOwn(project.caps, key) ? "  (answered)" : "";
-    lines.push(`  ${key.padEnd(22)}${String(value)}${answered}`);
+    lines.push(`  ${key.padEnd(CAPS_PLAN_KEY_PAD)}${String(value)}${answered}`);
   }
   if (a.workerModel !== undefined && a.workerModel.trim().length > 0) {
-    lines.push(`  ${"worker model".padEnd(22)}${a.workerModel.trim()}  (answered)`);
+    lines.push(`  ${"worker model".padEnd(CAPS_PLAN_KEY_PAD)}${a.workerModel.trim()}  (answered)`);
   }
 
   lines.push("", "escalation");
@@ -1482,7 +1592,7 @@ export function summarisePlan(
   const granted = RELEASE_SHAPES.filter((shape) => a.releaseGrants[shape] === "orchestrator");
   lines.push(
     "",
-    `authority      merge=${a.authority.merge}  release=${a.authority.release}`,
+    `authority      merge=${a.authority.merge}  release=${a.authority.release}  promotion=${a.authority.promotion ?? DEFAULT_AUTHORITY.promotion}`,
     `tool gate      ${
       granted.length === 0
         ? "every release/deploy shape blocked for workers and the orchestrator"
@@ -1602,13 +1712,16 @@ export type AmendAreaId = (typeof AMEND_AREA_IDS)[number];
  * `describe` is the reason the pick-list is worth anything — an operator picking
  * blind from eight nouns cannot tell which one holds the setting they came to
  * change, so every row carries its own current value. It reads only the config,
- * so the whole menu can be rendered and reviewed without a terminal.
+ * so the whole menu can be rendered and reviewed without a terminal. The caps
+ * row resolves inherited values against the defaults the caller is amending —
+ * the loaded config's global block on a re-run — so the menu and the daemon
+ * agree on what a project actually runs (#448).
  */
 export const AMEND_AREAS: {
   readonly [K in AmendAreaId]: {
     readonly name: string;
     readonly asks: string;
-    readonly describe: (p: ProjectConfig) => string;
+    readonly describe: (p: ProjectConfig, defaults?: Caps) => string;
   };
 } = {
   tracker: {
@@ -1636,8 +1749,8 @@ export const AMEND_AREAS: {
     // an area no menu offers is a setting only a full re-interview can reach.
     name: "caps & worker model",
     asks: "concurrency, spend, turn base and extension ceiling, wall clock, failed attempts, continuations — then the worker model",
-    describe: (p) => {
-      const c = resolveCaps(p, DEFAULT_CAPS);
+    describe: (p, defaults = DEFAULT_CAPS) => {
+      const c = resolveCaps(p, defaults);
       const answered = Object.keys(p.caps).length > 0;
       const spend =
         c.dailySpendUsd === null ? "no spend cap" : `$${c.dailySpendUsd}/day`;
@@ -1664,7 +1777,7 @@ export const AMEND_AREAS: {
   },
   authority: {
     name: "authority",
-    asks: "who lands green PRs, who cuts releases, then one question per release/deploy shape",
+    asks: "who lands green PRs, who cuts releases, who promotes, then one question per release/deploy shape",
     describe: (p) => {
       const grants = resolveReleaseGrants(p);
       const granted = RELEASE_SHAPES.filter((shape) => grants[shape] === "orchestrator");
@@ -1673,7 +1786,8 @@ export const AMEND_AREAS: {
       // set that mutates a running environment and the one #122 cost us. The full
       // table is in `status` and in the amend summary.
       return (
-        `merge=${p.authority.merge}, release=${p.authority.release}, tools: ` +
+        `merge=${p.authority.merge}, release=${p.authority.release}, ` +
+        `promote=${p.authority.promotion ?? DEFAULT_AUTHORITY.promotion}, tools: ` +
         `${granted.length === 0 ? "all blocked" : `${granted.length}/${RELEASE_SHAPES.length} granted`}` +
         `, deploy=${grants.deploy}`
       );
@@ -1742,10 +1856,10 @@ const AMEND_LABEL_MAX = 96;
  * its own text alone — and it is the value, not the noun, that tells them
  * whether this is the row they came for.
  */
-export function amendChoices(p: ProjectConfig): { id: AmendAreaId; label: string; description: string }[] {
+export function amendChoices(p: ProjectConfig, defaults: Caps = DEFAULT_CAPS): { id: AmendAreaId; label: string; description: string }[] {
   return AMEND_AREA_IDS.map((id) => {
     const area = AMEND_AREAS[id];
-    const current = area.describe(p);
+    const current = area.describe(p, defaults);
     return {
       id,
       label: `${area.name} — ${current.length > AMEND_LABEL_MAX ? `${current.slice(0, AMEND_LABEL_MAX - 1).trimEnd()}…` : current}`,
@@ -1762,11 +1876,18 @@ export function amendChoices(p: ProjectConfig): { id: AmendAreaId; label: string
  * mutation it authorises — creating labels, writing the config, replacing a
  * brief — and a delta alone names none of them. What this adds is the sentence
  * the operator is actually looking for: one area changed, everything else came
- * back off disk.
+ * back off disk. Inherited caps on both sides of the "was"/"now" compare
+ * against the same `defaults`, so a changed per-repo limit reads as a change
+ * and a carried value reads as no change (#448).
  */
-export function summariseAmend(area: AmendAreaId, before: ProjectConfig, a: SetupAnswers): string {
+export function summariseAmend(
+  area: AmendAreaId,
+  before: ProjectConfig,
+  a: SetupAnswers,
+  defaults: Caps = DEFAULT_CAPS,
+): string {
   const it = AMEND_AREAS[area];
-  const was = it.describe(before);
+  const was = it.describe(before, defaults);
   // The brief is a decision, not a config key, so its "after" is what the wizard
   // is about to do rather than what a rebuilt project would say.
   const now =
@@ -1774,7 +1895,7 @@ export function summariseAmend(area: AmendAreaId, before: ProjectConfig, a: Setu
       ? a.writeOrchestratorBrief
         ? `would ${existsSync(orchestratorBriefPath(a)) ? "OVERWRITE" : "write"} ${orchestratorBriefPath(a)}`
         : "not written — left exactly as it is"
-      : it.describe(buildProject(a));
+      : it.describe(buildProject(a), defaults);
 
   const others = AMEND_AREA_IDS.filter((o) => o !== area).map((o) => AMEND_AREAS[o].name);
   const lines = [`amending       ${it.name}  —  project ${before.name}`];