omp-conductor 0.15.9 → 0.15.11

package/src/types.ts

@@ -250,6 +250,14 @@ export const RELEASE_SHAPES = [
   "package-publish",
   "github-release",
   "deploy",
+  /**
+   * Replace the running conductor itself: the Bun-global CLI, the omp plugin
+   * and the Herdr plugin, pinned to one published release and executed
+   * detached. This is the "nobody patches the running conductor" boundary
+   * moved deliberately, not worked around — a session that may cut a release
+   * still cannot install one until an operator grants this shape too.
+   */
+  "install",
 ] as const;
 
 export type ReleaseShape = (typeof RELEASE_SHAPES)[number];
@@ -293,6 +301,7 @@ export const DENIED_RELEASE_GRANTS: ResolvedGrants = {
   "package-publish": "human",
   "github-release": "human",
   deploy: "human",
+  install: "human",
 };
 
 /**
@@ -308,6 +317,9 @@ export const OPERATOR_BRIEF_GRANTS: ResolvedGrants = {
   "package-publish": "orchestrator",
   "github-release": "orchestrator",
   deploy: "human",
+  // Nobody expected a legacy "operator-brief" grant to cover patching the
+  // running conductor; like `deploy` it stays with the human.
+  install: "human",
 };
 
 /**
@@ -335,11 +347,16 @@ export const AUTHORITY_HOLDERS = ["human", "orchestrator"] as const;
 export type AuthorityHolder = (typeof AUTHORITY_HOLDERS)[number];
 
 /**
- * What a project that never answered the question gets: humans keep both. A
- * default that delegated merging would hand a fresh fleet write access to its
- * own main branch on the strength of an unread config file.
+ * What a project that never answered the question gets: humans keep all three.
+ * A default that delegated merging would hand a fresh fleet write access to
+ * its own main branch on the strength of an unread config file, and a default
+ * that delegated promotion would let the orchestrator start spend unasked.
  */
-export const DEFAULT_AUTHORITY: ProjectConfig["authority"] = { merge: "human", release: "human" };
+export const DEFAULT_AUTHORITY: ProjectConfig["authority"] & { promotion: AuthorityHolder } = {
+  merge: "human",
+  release: "human",
+  promotion: "human",
+};
 
 /**
  * Whether a merge candidate must be up to date with the branch it targets.
@@ -621,12 +638,17 @@ export interface ProjectConfig {
    */
   escalation: { telegramChatId?: string; telegramTopicId?: number; fallbackToIssueComment: boolean; orchestrator: OrchestratorMode };
   /**
-   * Who lands green PRs and who cuts releases. The daemon never acts on this
-   * itself — it words the orchestrator's standing orders and the rendered brief
-   * scaffold with it, so config and prompt can never disagree about which of
-   * them is holding the merge button.
+   * Who lands green PRs, who cuts releases and who promotes. The daemon never
+   * acts on this itself — it words the orchestrator's standing orders and the
+   * rendered brief scaffold with it, so config and prompt can never disagree
+   * about which of them is holding the merge button.
+   *
+   * `promotion` is the queue-label sign-off: adding the label to an issue lets
+   * a worker claim it and starts spend, so POLICY.md must state its owner and
+   * a config that never answered defaults to the human — a gate whose owner is
+   * unstated must never resolve to the orchestrator.
    */
-  authority: { merge: AuthorityHolder; release: AuthorityHolder };
+  authority: { merge: AuthorityHolder; release: AuthorityHolder; promotion?: AuthorityHolder };
   /**
    * Per-shape tool-call enforcement for releases and deploys. Optional only for
    * configs written before the tripwire existed; both omission and any shape key
@@ -755,17 +777,10 @@ export interface PrDiff {
  * vocabulary that lives in three places drifts in three directions.
  */
 export const SETTLEMENT_FLAG_KINDS = [
-  /** The PR touched a file the report's `changed:` line never mentioned — the
-   *  direction that matters, an undisclosed edit. */
-  "undisclosed-file",
-  /** The report carried no usable `changed:` line, so nothing was disclosed. */
+  /** The settlement could not read the PR's diff, so no `changed:` file list
+   *  could be derived — the one disclosure fault that survives, because a
+   *  tree no one can read has nothing to disclose. */
   "changed-line-missing",
-  /** `changed:` named a path the PR never touched. The weaker direction. */
-  "unmatched-claim",
-  /** The same file appears as both claimed-but-untouched and
-   *  touched-but-unclaimed — the `changed:` line's format defeated the parser;
-   *  read the diff directly. */
-  "report-format-unparsed",
   /** A test file left the tree and no rename in the PR accounts for it. */
   "test-file-deleted",
   /** A skip/only/focus marker appears on a line the PR added. */
@@ -944,8 +959,13 @@ export interface Tracker {
    * Verify that a pull request is open, ready, and has a non-empty
    * terminal-success check rollup. When `expectedHead` is supplied, also
    * require the live head to match it.
+   *
+   * `opts.read` switches from the merge gate's "may this merge" to the read
+   * surface's "what is this PR's state": a merged or closed PR is then a
+   * reported fact rather than an `expected OPEN` refusal. Mutating verbs never
+   * pass `read`, so their open-PR gate is unchanged.
    */
-  verifyPr(url: string, expectedHead?: string): Promise<PrVerification | undefined>;
+  verifyPr(url: string, expectedHead?: string, opts?: { read?: boolean }): Promise<PrVerification | undefined>;
   /**
    * The pull request's diff, or undefined when this adapter could not produce
    * one — an unparseable URL, a deleted PR, a flaky network.
@@ -1010,6 +1030,8 @@ export const FAILURE_CLASSES = [
   "env-start-failure",
   "turn-cap-progress",
   "turn-cap-spinning",
+  "wall-clock-cap-progress",
+  "wall-clock-cap-spinning",
   "admin-kill",
   "ci-infra",
   "ci-deterministic",
@@ -1144,10 +1166,10 @@ export interface RunRecord {
    *  exactly as an unflagged one does, and the flags are evidence for whoever
    *  reviews the PR. Absent means the audit found nothing, or never ran. */
   settlementFlags?: SettlementFlag[];
-  /** The worker's settlement report text for this attempt, verbatim. Persisted
-   *  on every terminal update so the next attempt can pool its disclosures
-   *  (#199). Absent means the run predates the column, or was killed before the
-   *  worker returned a report. */
+  /** The worker's settlement report text for this attempt: the worker's own
+   *  narrative, with the `changed:` file list rewritten at settlement from
+   *  the PR's actual diff (#488). Absent means the run predates the column, or
+   *  was killed before the worker returned a report. */
   report?: string;
   /**
    * Why this run ended badly, and what the daemon did about it (#132). Absent
@@ -1162,6 +1184,15 @@ export interface RunRecord {
   recoveredAt?: number;
 }
 
+/**
+ * A partial patch for {@link updateRun}. Every key is optional; an absent key
+ * and an explicitly-`undefined` value both leave the column alone, while an
+ * explicit `null` clears it (#468). `null` exists only for the columns a
+ * caller may legitimately empty — a settle can never widen into a column it
+ * did not mean to write.
+ */
+export type RunPatch = { [K in keyof RunRecord]?: RunRecord[K] | null };
+
 /** A one-shot turn budget waiting for one issue's next claimed attempt. */
 export interface TurnOverride {
   project: string;
@@ -1211,6 +1242,13 @@ export interface DispatchSummary {
   /** True only for system/API failures, never ordinary policy holds. */
   degraded: boolean;
   holds: AdmissionHoldSummary[];
+  /** Runs the pass settled while it ran — merged PRs terminalised by the settle
+   *  sweep and by classification recovery. Optional: persisted old rows lack
+   *  it, so readers use `?? 0`. (#497) */
+  settled?: number;
+  /** True for a held pass's own record (#497): the queue was never routed, so
+   *  ready/routed/claimed are absent queue facts, not an empty queue. */
+  paused?: boolean;
 }
 
 /** Admission holds that indicate repairable friction rather than normal flow control. */
@@ -1261,11 +1299,22 @@ export interface FrictionSignal {
  * today's digest already been handed over?" without asking the model to
  * remember, which is the memory #123 found unreliable.
  *
+ * The remaining values are the interrupt categories themselves. Handing a
+ * report over as `fleet-stopped` or `tier2` (or `decision-needed`,
+ * `confirmed-failure`) is the escalation handoff: the project's reporting
+ * policy decides between sending now and holding, exactly as it does for a
+ * daemon escalation of that category, and an identical retry is refused only
+ * while the earlier handoff is still undelivered (#453).
+ *
  * Declared as data for the same reason as {@link REPORT_SCOPES}: the CLI verb
  * that accepts a kind and the outbox that renders one enumerate the same list,
  * so a third kind cannot be added while either still knows only two.
  */
-export const REPORT_KINDS = ["material", "digest"] as const;
+export const REPORT_KINDS = [
+  "material",
+  "digest",
+  ...INTERRUPT_CATEGORIES.filter((category) => category !== "material"),
+] as const;
 
 export type ReportKind = (typeof REPORT_KINDS)[number];
 
@@ -1377,7 +1426,41 @@ export interface DigestBacklog {
   heldNoticeCount: number;
   /** Subset held only for the next availability window. */
   availabilityHeldNoticeCount?: number;
+  /** Oldest held notice across both held groups. */
   heldNoticeOldestAt?: number;
+  /** Oldest held notice that is digest-bound (`releaseOnAvailable` false). */
+  digestHeldNoticeOldestAt?: number;
+  /** Oldest held notice waiting only for the availability window. */
+  availabilityHeldNoticeOldestAt?: number;
+}
+
+/** Where one captured raw idea is in its lifecycle (#298). `pending` is a raw
+ *  idea awaiting grooming; `groomed` became an issue (#300, which records the
+ *  issue URL); `dismissed` was dropped without becoming anything. */
+export const INTAKE_STATES = ["pending", "groomed", "dismissed"] as const;
+
+export type IntakeState = (typeof INTAKE_STATES)[number];
+
+/** One raw idea captured by `omp-conductor intake`, durable in the store so an
+ *  idea from 02:00 is still there after a restart (#299). */
+export interface IntakeItem {
+  id: string;
+  project: string;
+  /** The idea text verbatim, as captured. */
+  text: string;
+  createdAt: number;
+  state: IntakeState;
+  /** The issue this idea became, once #300 grooms it. */
+  issueUrl?: string;
+  /** When the item was resolved into an issue (#300) or dismissed. */
+  groomedAt?: number;
+}
+
+/** What a caller hands over. The store owns the id, the state and the timestamps. */
+export interface IntakeDraft {
+  project: string;
+  text: string;
+  at: number;
 }
 
 /**
@@ -1460,7 +1543,8 @@ export interface LabelOp {
 export interface Store {
   /** A claimed run atomically consumes and applies its issue's pending turn override. */
   createRun(r: Omit<RunRecord, "id">): RunRecord;
-  updateRun(id: string, patch: Partial<RunRecord>): void;
+  /** Partial patch; an explicit `null` clears a column, `undefined`/absence leaves it alone (#468). */
+  updateRun(id: string, patch: RunPatch): void;
   getRun(id: string): RunRecord | undefined;
   /** Runs whose issue is occupied: a live worker, or a green PR awaiting merge. */
   activeRuns(project: string): RunRecord[];
@@ -1471,6 +1555,11 @@ export interface Store {
   /** Newest attempt per issue for the live board. Non-merged work remains
    * visible; merged rows are bounded by the supplied recent-history cutoff. */
   recentRuns(project: string, mergedSinceEpochMs: number): RunRecord[];
+  /** Every attempt that recorded one PR URL, newest first. Mediated PR verbs
+   *  resolve ownership through this, not through `recentRuns`' newest-attempt-
+   *  per-issue view — a requeued continuation must never hide the PR its
+   *  predecessor opened. Merged rows keep the same recent-history bound. */
+  runsForProjectPr(project: string, prUrl: string, mergedSinceEpochMs: number): RunRecord[];
   /** Merged rows whose post-merge workflow verdict is still pending, oldest first. */
   runsNeedingBaseCheck(project: string, limit?: number): RunRecord[];
   /** Replace the current live-head health row for one routed repository. */
@@ -1500,6 +1589,9 @@ export interface Store {
    *  tail` resolves an issue number to a transcript through this; the number is
    *  what an operator has, the run id is not. */
   latestRun(project: string, issue: number): RunRecord | undefined;
+  /** Every attempt for one issue, oldest first, so an escalation can group the
+   *  continuation budget by failure class (#439). */
+  runsForIssue(project: string, issue: number): RunRecord[];
   /** Persist a one-shot ceiling and append the operator action to its audit ledger. */
   setTurnOverride(project: string, issue: number, maxTurns: number, setAt?: number): void;
   turnOverride(project: string, issue: number): number | undefined;
@@ -1511,16 +1603,24 @@ export interface Store {
     project: string,
     opts?: { issue?: number; limit?: number },
   ): TurnOverride[];
-  /** Every attempt of one issue that settled with a report, in attempt order.
-   *  The settlement audit pools these as prior disclosures when a later
-   *  attempt is reconciled (#199). Rows with no report (pre-#199, or killed
-   *  before the worker returned) are skipped. */
-  attemptReports(project: string, issue: number): { attempt: number; report: string }[];
   runsStartedSince(project: string, sinceEpochMs: number): number;
   spendSince(project: string, sinceEpochMs: number): number;
+  /** The rows one stats window needs (#282): every run settling at or after
+   *  `sinceEpochMs`, plus the full attempt chain of each issue whose merge
+   *  settled there (so continuation chains collapse into one journey), ordered
+   *  by issue then startedAt. Read-only. */
+  statsRuns(project: string, sinceEpochMs: number): RunRecord[];
+  /** Total tracked `gh` calls between two UTC day keys, inclusive (#198). */
+  ghCallsBetween(sinceDay: string, untilDay: string): number;
   /** Idempotence guard so a retry loop cannot page a human repeatedly for the
    *  same event. */
   wasNotified(key: string): boolean;
+  /** Whether an escalation handoff with this project, category and folded text
+   *  is still owed: a same-text report still in the outbox, or a same-text
+   *  held notice not yet digested. The CLI report surface refuses an identical
+   *  retry only while this is true (#453) — once the first handoff lands, the
+   *  same text is a new occurrence, not a double-send. */
+  hasOpenEscalationHandoff(project: string, category: InterruptCategory, body: string): boolean;
   recordDispatch(project: string, summary: DispatchSummary): void;
   latestDispatch(project: string): DispatchSummary | undefined;
   /** The newest `digest:` dedupe key a project has run toward without ending in
@@ -1544,6 +1644,13 @@ export interface Store {
   getMaterialEvent(id: string): MaterialEvent | undefined;
   /** Ordinary material outcomes still owed, oldest first and bounded. */
   undigestedMaterialEvents(project: string, limit?: number): MaterialEvent[];
+  /** Persist one raw idea, `pending`, for later grooming (#299). */
+  recordIntake(draft: IntakeDraft): IntakeItem;
+  /** Ideas still `pending`, oldest first — what `intake list` and `status` read. */
+  pendingIntake(project: string): IntakeItem[];
+  /** Resolve one idea to `groomed` (recording the issue URL #300 chose) or
+   *  `dismissed`. `false` when the id is unknown. */
+  resolveIntake(id: string, state: "groomed" | "dismissed", issueUrl?: string): boolean;
   /** Count and age source for status and digest prompt bounds. */
   digestBacklog(project: string): DigestBacklog;
   /** Add one bounded observation to the per-day friction rollup. */
@@ -1655,6 +1762,8 @@ export interface Store {
   createDecision(draft: DecisionDraft): DecisionRecord;
   /** Everything still owed an answer, oldest first — what a tick digest reads. */
   openDecisions(project: string): DecisionRecord[];
+  /** One row by id, whatever its state — what a bounded ask polls while waiting. */
+  decision(id: string): DecisionRecord | undefined;
   /** Answer or withdraw one. `false` when the id is unknown or already closed,
    *  so a double-resolve cannot overwrite the first answer. */
   resolveDecision(id: string, state: "answered" | "withdrawn", resolution: string, at: number): boolean;
@@ -1805,6 +1914,10 @@ export const VERB_NAMES = [
   "conductor_pr_merge",
   "conductor_label",
   "conductor_release",
+  /** Request the fleet upgrade itself to a published conductor release. The
+   *  install shape gates it like a release shape; execution detaches from this
+   *  session and the daemon, and the first tick after the restart verifies. */
+  "conductor_install",
   /** The one read verb. It answers with the merge gate's own verdict, so
    *  "pushed-green" is the dispatcher's reading of the PR rather than a claim the
    *  worker makes about itself from whatever it happened to run. */

package/src/unblock.ts

@@ -35,6 +35,7 @@
  * failed-attempt budget.
  */
 
+import { hasContinuationBudget, hasFailedAttemptBudget } from "./daemon.ts";
 import { projectLabels } from "./label-projection.ts";
 import { LIVE_STATES } from "./store.ts";
 import type { Caps, ProjectConfig, RunRecord, Store, Tracker } from "./types.ts";
@@ -64,11 +65,18 @@ export interface UnblockOutcome {
   /** Set when `--force` recorded an operator's acceptance of that loss. */
   forced?: true;
   /** Set when the queue label was re-added (the default); absent on
-   *  --no-requeue, on the refusal path, and when a live worker (claimed or
-   *  running) is still on the issue. A pushed-green/pushed-pending occupancy
+   *  --no-requeue, on the refusal path, when a live worker (claimed or
+   *  running) is still on the issue, and when a spent budget withheld the
+   *  re-queue (requeueWithheld). A pushed-green/pushed-pending occupancy
    *  is worker-free, so the label is still restored there (#175 bypasses it;
    *  `isEligible` needs the label once the PR resolves). */
   requeued?: true;
+  /** Set when the re-queue was withheld because the issue's failed-attempt or
+   *  continuation budget is spent — the same admission gate the dispatcher
+   *  holds on (failed-attempts / continuations), so the queue label would
+   *  manufacture a candidate that can never be admitted (#348). The lifecycle
+   *  clears still happened; only the add was skipped. */
+  requeueWithheld?: true;
   /** Set when `--no-requeue` skipped the queue-label re-add. */
   requeueSkipped?: true;
   /** Set when the tracker refused one or more of this verb's label ops, so
@@ -121,6 +129,7 @@ export async function unblockIssue(
   store: Store,
   issue: number,
   opts: { force?: boolean; requeue?: boolean } = {},
+  caps: Caps,
 ): Promise<UnblockOutcome> {
   const requeue = opts.requeue !== false;
   // Read before any label is touched: terminality is the whole of the argument
@@ -145,6 +154,16 @@ export async function unblockIssue(
     active,
   };
 
+  // The dispatcher's own admission gates, as daemon.ts computes them (#348):
+  // every failed-implementation slot spent, or the continuation budget
+  // exceeded, and the issue is held (`failed-attempts` / `continuations`) on
+  // every subsequent tick forever. A re-queued issue in that state is exactly
+  // the permanent admission hold this verb must not manufacture, so the
+  // re-queue half below is decided on the same predicates that decide the hold.
+  const budgetSpent =
+    !hasFailedAttemptBudget(counts.failuresUsed, caps.maxAttemptsPerIssue) ||
+    !hasContinuationBudget(counts.continuationsUsed, caps.maxContinuationsPerIssue);
+
   // The one case where this verb refuses. Clearing the labels here re-queues an
   // issue whose next claim starts by force-removing the worktree that holds the
   // only copy of the last attempt's work (#118) — and unlike every other state
@@ -185,14 +204,22 @@ export async function unblockIssue(
   // its PR is live but no process writes to its branch — so a pushed
   // continuation still gets the label: the dispatcher bypasses worker-free
   // pushed-green rows (#175), and `isEligible` requires the queue label once
-  // the PR resolves closed-unmerged.
+  // the PR resolves closed-unmerged. And never when the failed-attempt or
+  // continuation budget is spent (#348): the dispatcher holds such an issue
+  // forever, so the label would claim a candidacy the next admission cannot
+  // deliver — the clears still happen, the add is withheld.
   let requeued: true | undefined;
+  let requeueWithheld: true | undefined;
   let requeueSkipped: true | undefined;
   let labelSyncQueued: number | undefined;
   if (!live) {
     if (requeue) {
-      ops.push({ issue, op: "add", label: project.queueLabel });
-      requeued = true;
+      if (budgetSpent) {
+        requeueWithheld = true;
+      } else {
+        ops.push({ issue, op: "add", label: project.queueLabel });
+        requeued = true;
+      }
     } else {
       requeueSkipped = true;
     }
@@ -222,6 +249,7 @@ export async function unblockIssue(
     ...(latest === undefined ? {} : { latest }),
     ...(held === undefined ? {} : { forced: true as const }),
     ...(requeued === undefined ? {} : { requeued }),
+    ...(requeueWithheld === undefined ? {} : { requeueWithheld }),
     ...(requeueSkipped === undefined ? {} : { requeueSkipped }),
     ...(labelSyncQueued === undefined ? {} : { labelSyncQueued }),
   };
@@ -231,10 +259,14 @@ export async function unblockIssue(
  * What the operator reads back. It promises a re-claim only when one can
  * actually happen, because a promise made blindly sends someone away believing
  * work had resumed and they find out by waiting for it. Three things withhold
- * it: a live run still owns the issue through `agent:in-progress`, a spent
- * attempt budget makes the next tick escalate rather than dispatch, and — since
- * the in-progress label is only released for a terminal run — an issue with no
- * run row at all, where that label may still be sitting there unread. #18 was
+ * the re-claim promise: a live run still owns the issue through
+ * `agent:in-progress`, a spent attempt budget makes the next tick escalate
+ * rather than dispatch, and — since the in-progress label is only released for
+ * a terminal run — an issue with no run row at all, where that label may still
+ * be sitting there unread. A spent budget also withholds the queue label
+ * itself, on the same predicate the dispatcher holds on (#348): re-adding it
+ * would manufacture a candidate the next tick can never admit, and the report
+ * says so instead of claiming a restore that did not happen. #18 was
  * filed against this function saying `next tick eligible again` in a case where
  * it was not, so the wording is a contract rather than prose.
  *
@@ -297,16 +329,28 @@ export function formatUnblock(
         `"${project.stateLabels.inProgress}" until it ends — nothing is re-claimed before then`,
       `  queue      "${project.queueLabel}" not restored — a run is still active; re-run unblock once it settles`,
     );
-  } else if (o.failuresUsed >= caps.maxAttemptsPerIssue) {
+  } else if (!hasFailedAttemptBudget(o.failuresUsed, caps.maxAttemptsPerIssue)) {
     lines.push(
       `  next tick  not eligible: all ${caps.maxAttemptsPerIssue} failed attempts are spent. ` +
         "Rewrite the issue or raise maxAttemptsPerIssue.",
     );
-  } else if (o.continuationsUsed > caps.maxContinuationsPerIssue) {
+    if (o.requeueWithheld === true) {
+      lines.push(
+        `  queue      "${project.queueLabel}" withheld — re-adding it would manufacture a candidate the ` +
+          "dispatcher holds as failed-attempts forever; rewrite the issue or raise maxAttemptsPerIssue before re-queueing",
+      );
+    }
+  } else if (!hasContinuationBudget(o.continuationsUsed, caps.maxContinuationsPerIssue)) {
     lines.push(
       `  next tick  not eligible: the ${caps.maxContinuationsPerIssue}-continuation budget was exceeded. ` +
         "Inspect progress or raise maxContinuationsPerIssue.",
     );
+    if (o.requeueWithheld === true) {
+      lines.push(
+        `  queue      "${project.queueLabel}" withheld — re-adding it would manufacture a candidate the ` +
+          "dispatcher holds as continuations forever; inspect progress or raise maxContinuationsPerIssue before re-queueing",
+      );
+    }
   } else if (latest === undefined) {
     lines.push(
       `  next tick  eligible once the issue carries "${project.queueLabel}" and no state label — with no ` +