omp-conductor 0.12.0 → 0.14.0

package/src/types.ts

@@ -61,6 +61,9 @@ export interface Caps {
   /** Turn ceiling for one worker — catches loops that are burning tokens
    *  without converging. */
   workerMaxTurns: number;
+  /** Maximum turn budget an operator may assign to one issue's next attempt.
+   * Defaults to twice that issue's effective `workerMaxTurns`. */
+  workerMaxTurnsCeiling: number;
   /** Wall-clock ceiling for one worker (90 min): a session that is merely
    *  stuck spends no turns, so turns alone cannot detect it. */
   workerWallClockMs: number;
@@ -133,8 +136,8 @@ export interface RepoTarget {
  * `escalations` interrupts only for a tier-2 decision. `material` reports every
  * material event as it happens. `decisions` sits between them: a decision the
  * session needs, or a condition that stops the fleet, interrupts immediately;
- * every other material event accumulates and ships with the next tick report —
- * one message on a schedule instead of a ping per merge (#138).
+ * every other material event accumulates and ships with the configured digest
+ * instead of as a ping per merge (#138).
  */
 export const REPORT_SCOPES = ["escalations", "decisions", "material"] as const;
 
@@ -174,6 +177,24 @@ export const INTERRUPT_CATEGORIES = [
 
 export type InterruptCategory = (typeof INTERRUPT_CATEGORIES)[number];
 
+/** Operator-local weekdays used by a weekly availability window. */
+export const WEEKDAYS = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"] as const;
+
+export type Weekday = (typeof WEEKDAYS)[number];
+
+/**
+ * One operator-local interruption window. A day names the day the window
+ * opens; when `start` is later than `end`, it closes on the following day.
+ */
+export interface WeeklyAvailability {
+  timezone: string;
+  days: Weekday[];
+  start: string;
+  end: string;
+  /** Categories that may still interrupt outside the window. */
+  bypass: InterruptCategory[];
+}
+
 /** When the daily/report rollup is due. */
 export const DIGEST_CADENCES = ["none", "per-tick", "daily"] as const;
 
@@ -187,6 +208,8 @@ export type DigestCadence = (typeof DIGEST_CADENCES)[number];
 export interface ReportingPolicy {
   interruptOn: InterruptCategory[];
   digest: { cadence: DigestCadence; at?: string; timezone?: string };
+  /** Absent preserves the legacy 24-hour interruption behaviour. */
+  availability?: WeeklyAvailability;
   /** Set when the policy came from a legacy `scope` preset. */
   scopePreset?: ReportScope;
 }
@@ -358,6 +381,8 @@ export const RELEASE_REQUIREMENTS = [
   "no-open-prs",
   /** Nothing still carries the queue label: the batch is finished, not paused. */
   "queue-drained",
+  /** The newest observed post-merge check for the released repo's base branch is green. */
+  "base-branch-green",
   /** The epic this release closes has no open children left. */
   "epic-children-closed",
 ] as const;
@@ -661,6 +686,8 @@ export type PrState = "merged" | "closed" | "open";
 /** Result of independently checking a worker's claimed green pull request. */
 export interface PrVerification {
   status: "green" | "pending" | "failed";
+  /** Full live head SHA read in the same tracker request as the verdict. */
+  headSha: string;
   reason: string;
 }
 
@@ -703,6 +730,10 @@ export const SETTLEMENT_FLAG_KINDS = [
   "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. */
@@ -711,6 +742,10 @@ export const SETTLEMENT_FLAG_KINDS = [
   "assertions-removed",
   /** A named timeout in a test file went up. */
   "test-timeout-raised",
+  /** A terminal run recovered an OPEN PR by exact issue, repo and branch identity. */
+  "pr-adopted",
+  /** A workflow on the merge commit's base branch failed after settlement. */
+  "base-branch-red",
 ] as const;
 
 export type SettlementFlagKind = (typeof SETTLEMENT_FLAG_KINDS)[number];
@@ -722,7 +757,8 @@ export type SettlementFlagKind = (typeof SETTLEMENT_FLAG_KINDS)[number];
  */
 export interface SettlementFlag {
   kind: SettlementFlagKind;
-  /** Repo-relative path, or `(report)` for a finding about the report itself. */
+  /** Repo-relative path, `(report)` for report evidence, or `(base branch)` for
+   *  a post-merge workflow result. */
   file: string;
   /** 1-based line in the side of the diff the evidence came from: the
    *  post-image for an added line, the pre-image for a removed one. */
@@ -736,24 +772,52 @@ export interface SettlementFlag {
 /** Tracker lifecycle state for an issue. Undefined means the adapter could not tell. */
 export type IssueState = "open" | "closed";
 
+/** Read-after-write issue facts used to validate an eventually-consistent queue candidate. */
+export interface IssueSnapshot {
+  readonly state: IssueState;
+  readonly labels: readonly string[];
+}
+
 /**
  * An OPEN pull request that already closes an issue, as admission sees it.
  *
- * The head branch travels with the URL because admission has two different
- * questions to answer about the same PR, and only one of them the URL can
- * answer. "Is there finished work here" is a URL question. "Is this *our*
- * retained work, resumed" is a branch question, because a run can retain a
- * branch and never produce a PR: on 2026-08-09T00:47Z veltro#324 attempt 1 was
- * killed at the turns cap before its worker opened one, and the PR that later
- * appeared on that exact branch (chad#438) could never be matched by URL
- * equality against a `prUrl` the terminal run never recorded (#50).
+ * The repository travels with the URL because recovery has to prove three
+ * independent identities before adopting a PR onto a terminal run: closing
+ * issue, retained branch, and routed repository (#245). Admission needs only
+ * the URL/branch pair, but weakening the shared answer would make recovery
+ * parse provenance back out of a presentation URL.
+ *
+ * The head branch recognises a continuation the store never saw a PR for: on
+ * 2026-08-09T00:47Z veltro#324 attempt 1 was killed at the turns cap before its
+ * worker opened one, and the PR that later appeared on that exact branch
+ * (chad#438) could never be matched by URL equality against a `prUrl` the
+ * terminal run never recorded (#50).
  */
 export interface OpenCloser {
   url: string;
   /** Head branch of the open PR, for retained-continuation identity. */
   headRefName: string;
+  /** Canonical `owner/repo` identity supplied by the tracker. */
+  repo: string;
+}
+/** The merge identity needed to observe the exact base-branch push it produced. */
+export interface MergedPrInfo {
+  mergeSha: string;
+  baseRef: string;
+}
+
+/** One GitHub Actions workflow run, normalised before it crosses the tracker port. */
+export interface WorkflowRun {
+  id: number;
+  workflowId: number;
+  name: string;
+  status: string;
+  conclusion?: string;
+  url: string;
+  createdAt: string;
 }
 
+
 /**
  * Deliberately narrow so a Gitea or local-file tracker can drop in later.
  * Nothing here is GitHub-shaped; the GitHub adapter owns `gh` entirely.
@@ -786,44 +850,70 @@ export interface Tracker {
    */
   parentOf(issue: number): Promise<number | undefined>;
   /**
-   * The OPEN pull request that already closes `issue`, or undefined when none
-   * does.
+   * The first OPEN pull request that already closes `issue`, or undefined when
+   * none does.
    *
-   * Admission has to ask the tracker because the store cannot answer. The busy
-   * set is built from run rows, so it only knows work *this* database recorded:
-   * a migration onto the daemon, a wiped or relocated state directory, a
-   * restore onto a new host, or simply a database younger than the PRs all
-   * present pushed-and-open work as an untouched queue item. The tracker is the
-   * only party that remembers across all of those.
-   *
-   * Returns {@link OpenCloser} rather than a bare URL because the branch is the
-   * half admission needs to recognise a continuation the store never saw a PR
-   * for; see that type for the veltro#324 case that forced the widening.
+   * Admission asks this any-open question because the store only knows work
+   * recorded in this database. A migrated daemon, restored host, or younger
+   * database can otherwise dispatch duplicate work onto an issue whose PR is
+   * already open.
    */
   openCloserFor(issue: number): Promise<OpenCloser | undefined>;
+  /**
+   * Every OPEN pull request that closes `issue`.
+   *
+   * Salvage recovery must inspect the full answer: an unrelated closer may be
+   * listed before the PR whose branch and repository exactly match the
+   * recovered run. An empty array means no OPEN closer; a thrown lookup remains
+   * fail-closed.
+   */
+  openClosersFor(issue: number): Promise<OpenCloser[]>;
   /**
    * Whether an issue is still open, or undefined when tracker/network state is
    * ambiguous. Cleanup must never interpret undefined as permission to delete.
    */
   issueState(issue: number): Promise<IssueState | undefined>;
+  /**
+   * Direct REST state and labels for final admission validation, or undefined
+   * when either fact cannot be read safely.
+   */
+  issueSnapshot(issue: number): Promise<IssueSnapshot | undefined>;
   /**
    * The state of one specific pull request, or undefined when this adapter
    * could not tell — a network failure, a deleted PR, a URL it cannot parse.
    * Undefined never means "no".
    *
-   * Deliberately separate from {@link Tracker.openCloserFor}, which answers a
-   * different question: that one asks "should this candidate be admitted", and
-   * answers undefined for merged, closed-unmerged, no PR at all and a deleted
-   * PR alike, because admission treats all four the same. This one asks "did
+   * Deliberately separate from {@link Tracker.openCloserFor}, which asks
+   * whether any OPEN closing PR exists and answers undefined for merged,
+   * closed-unmerged, no PR at all and a deleted PR alike. This one asks "did
    * *this* run's PR land", where those answers are opposites. Collapsing them
    * is how a PR a human rejected gets recorded as merged.
    */
   prState(url: string): Promise<PrState | undefined>;
+  /** The merge commit and base ref for a merged pull request. */
+  mergedPrInfo(url: string): Promise<MergedPrInfo | undefined>;
+  /** Workflow runs GitHub associated with one exact commit SHA. */
+  workflowRunsAt(
+    repo: string,
+    sha: string,
+    opts?: { event?: string; branch?: string },
+  ): Promise<WorkflowRun[] | undefined>;
+  /** The live commit at one repository branch, or undefined when unreadable. */
+  branchHead(repo: string, branch: string): Promise<string | undefined>;
+  /** The newest run of this workflow on the base branch before `before`.
+   *  `null` means no earlier run; `undefined` means the history could not be read. */
+  previousWorkflowRun(
+    repo: string,
+    workflowId: number,
+    branch: string,
+    before: string,
+  ): Promise<WorkflowRun | null | undefined>;
   /**
-   * Verify that a worker's pull request is open, ready, still at the reported
-   * head, and has a non-empty terminal-success check rollup.
+   * 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.
    */
-  verifyPr(url: string, expectedHead: string): Promise<PrVerification | undefined>;
+  verifyPr(url: string, expectedHead?: string): 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.
@@ -899,6 +989,9 @@ export const FAILURE_CLASSES = [
   "settlement-stuck",
   "provider-credit",
   "provider-transient",
+  /** A reviewer closed pushed-green or pushed-pending work without merging it:
+   *  a review decision, not a worker failure. */
+  "returned-for-revision",
   "unknown",
 ] as const;
 
@@ -923,11 +1016,34 @@ export const RECOVERY_ACTIONS = [
 
 export type RecoveryAction = (typeof RECOVERY_ACTIONS)[number];
 
+/** What the daemon learned about workflows on a mediated merge's base commit. */
+export const BASE_CHECK_STATES = [
+  "pending",
+  "green",
+  "red",
+  "red-preexisting",
+  "unknown",
+] as const;
+
+export type BaseCheckState = (typeof BASE_CHECK_STATES)[number];
+
+/** Current push-workflow health at a routed repository's live base head. */
+export interface BaseHealth {
+  repo: string;
+  branch: string;
+  headSha: string;
+  verdict: "green" | "red" | "pending" | "unknown";
+  runsCount: number;
+  detail?: string;
+  checkedAt: number;
+}
+
 /**
  * Execution state is separate from the tracker's own labels on purpose: labels
  * are coarse and human-editable, while the loop needs to distinguish "pushed
  * and green, waiting on merge" from "merged" to decide what to do on restart.
  */
+
 export type RunState =
   | "claimed"
   | "running"
@@ -940,6 +1056,9 @@ export type RunState =
   | "blocked"
   | "failed"
   | "killed"
+  /** Terminal operator action. The worker cannot resume and the attempt does
+   *  not consume implementation-failure or continuation budgets. */
+  | "stopped"
   /** In flight when its daemon process died; reconciled at the next startup. */
   | "orphaned";
 
@@ -967,6 +1086,12 @@ export interface RunRecord {
   prUrl?: string;
   /** Pull request head the worker observed after its deterministic CI watcher exited. */
   headSha?: string;
+  /** Merge commit and actual base ref read from the merged pull request. */
+  mergeSha?: string;
+  baseRef?: string;
+  /** Post-merge workflow verdict. Pending is revisited by the tick sweep. */
+  baseCheck?: BaseCheckState;
+  baseCheckAt?: number;
   /** Commit this run's uncommitted work was preserved as before its worktree
    *  was removed, on the run's own branch. Absent means the daemon found
    *  nothing to save, or never looked — see {@link RunRecord.salvageError}. */
@@ -1005,11 +1130,22 @@ export interface RunRecord {
   recoveredAt?: number;
 }
 
+/** A one-shot turn budget waiting for one issue's next claimed attempt. */
+export interface TurnOverride {
+  project: string;
+  issue: number;
+  maxTurns: number;
+  setAt: number;
+}
+
 export type AdmissionHoldReason =
   | "capacity"
   | "issue-active"
   | "failed-attempts"
   | "continuations"
+  | "issue-closed"
+  | "issue-state-lookup-error"
+  | "issue-dequeued"
   | "parent-lookup-error"
   | "sibling-active"
   | "repo-active"
@@ -1049,6 +1185,7 @@ export type FrictionAdmissionReason =
   | "failed-attempts"
   | "continuations"
   | "parent-lookup-error"
+  | "issue-state-lookup-error"
   | "open-pr-lookup-error"
   | "unroutable:no-repo-label"
   | "unroutable:multiple-repo-labels"
@@ -1173,6 +1310,43 @@ export interface ReportEnqueue {
   deduped: boolean;
 }
 
+/** Maximum ledger rows of each kind placed in one digest prompt. Older rows
+ * stay first, so a busy day drains deterministically over later digests. */
+export const DIGEST_BACKLOG_LIMIT = 20;
+
+/** One ordinary material outcome waiting for a rendered digest (#274). */
+export interface MaterialEvent {
+  id: string;
+  project: string;
+  category: string;
+  summary: string;
+  evidence: string;
+  occurredAt: number;
+  recordedAt: number;
+  /** The accepted outbox row that took responsibility for this event. */
+  digestReportId?: string;
+}
+
+/** What the orchestrator records when an outcome happens. */
+export interface MaterialEventDraft {
+  project: string;
+  category: string;
+  summary: string;
+  evidence: string;
+  occurredAt: number;
+  recordedAt: number;
+}
+
+/** Counts and oldest timestamps for the two distinct digest sources. */
+export interface DigestBacklog {
+  materialCount: number;
+  materialOldestAt?: number;
+  heldNoticeCount: number;
+  /** Subset held only for the next availability window. */
+  availabilityHeldNoticeCount?: number;
+  heldNoticeOldestAt?: number;
+}
+
 /**
  * Where one operator decision stands (#136).
  *
@@ -1251,6 +1425,7 @@ export interface LabelOp {
  * the two disagree.
  */
 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;
   getRun(id: string): RunRecord | undefined;
@@ -1263,6 +1438,17 @@ 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[];
+  /** 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. */
+  upsertBaseHealth(project: string, row: BaseHealth): void;
+  /** Current live-head health, ordered by routed repository name. */
+  baseHealth(project: string): BaseHealth[];
+  /** Recently merged routed repository/branch pairs that establish health scope. */
+  mergedRepoBranches(
+    project: string,
+    sinceEpochMs: number,
+  ): { repo: string; baseRef?: string }[];
   /** Newest attempt per issue that preserved work or failed to, so `status`
    *  can name every WIP tip a re-claim would build on and every tree that is
    *  still the only copy. */
@@ -1281,6 +1467,17 @@ 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;
+  /** 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;
+  /** Administrative deletion; claimed runs consume inside `createRun`'s transaction. */
+  clearTurnOverride(project: string, issue: number): void;
+  listTurnOverrides(project: string): TurnOverride[];
+  /** Durable override actions, newest first; consumption never removes these rows. */
+  turnOverrideLedger(
+    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
@@ -1296,12 +1493,26 @@ export interface Store {
   /** The newest `digest:` dedupe key a project has run toward without ending in
    *  failure — what the off-schedule-digest refusal compares against (#229). */
   lastDigestDedupeKey(project: string): string | undefined;
-  /** Hold a tier-2 escalation the interrupt policy deferred to the digest. */
+  /** Hold a tier-2 escalation the interrupt policy or availability window deferred. */
   addHeldNotice(notice: HeldNoticeDraft): void;
-  /** Held notices still owed (not yet re-surfaced by a digest pass). */
-  undigestedNotices(project: string): HeldNotice[];
-  /** Mark every undigested notice for a project as re-surfaced. */
-  markNoticesDigested(project: string, at: number): void;
+  /**
+   * Held notices still owed, oldest first and bounded. `availabilityOnly`
+   * selects notices that may be released at the next configured opening.
+   */
+  undigestedNotices(
+    project: string,
+    limit?: number,
+    availabilityOnly?: boolean,
+    categories?: readonly InterruptCategory[],
+    urgent?: boolean,
+  ): HeldNotice[];
+  /** Persist one ordinary material outcome without sending it. */
+  recordMaterialEvent(event: MaterialEventDraft): MaterialEvent;
+  getMaterialEvent(id: string): MaterialEvent | undefined;
+  /** Ordinary material outcomes still owed, oldest first and bounded. */
+  undigestedMaterialEvents(project: string, limit?: number): MaterialEvent[];
+  /** Count and age source for status and digest prompt bounds. */
+  digestBacklog(project: string): DigestBacklog;
   /** Add one bounded observation to the per-day friction rollup. */
   recordFriction(project: string, observation: FrictionObservation): void;
   /** Repeated signals not surfaced within the supplied cooldown window. */
@@ -1331,7 +1542,35 @@ export interface Store {
    * suppressed without asking the model what it sent yesterday.
    */
   enqueueReport(draft: ReportDraft): ReportEnqueue;
+  /** Atomically hand a digest to the outbox and associate only the named
+   * material events and deferred escalations. A handoff deduplicated by its
+   * optional daily key consumes nothing new. */
+  enqueueDigestReport(
+    draft: ReportDraft,
+    materialEventIds: readonly string[],
+    heldNoticeIds: readonly string[],
+  ): ReportEnqueue;
+  /** Atomically enqueue a working-hours catch-up unless a due digest currently
+   * owns the handoff window. `undefined` leaves every notice unowned. */
+  enqueueAvailabilityReport(
+    draft: ReportDraft,
+    heldNoticeIds: readonly string[],
+  ): ReportEnqueue | undefined;
   getReport(id: string): ReportRecord | undefined;
+  /** Atomically remove an unsent material report from the outbox and preserve
+   * its body as a held notice after policy or availability changes. */
+  deferPendingReportToNotice(id: string, notice: HeldNoticeDraft): boolean;
+  /** Remove a still-pending working-hours catch-up and make its associated
+   * notices digest-eligible again after a live policy change. */
+  releasePendingAvailabilityReport(id: string, project: string, possibleRepeat?: boolean): boolean;
+  /** Give one due digest a bounded, once-per-day lease on availability-held
+   * notices. Pending catch-ups are released inside the same transaction. */
+  reserveAvailabilityDigest(
+    project: string,
+    cycleKey: string,
+    at: number,
+    expiresAt: number,
+  ): boolean;
   /** `pending` rows whose backoff has elapsed, oldest first. */
   dueReports(project: string, now: number, limit: number): ReportRecord[];
   /** Atomically take a due `pending` row into `sending` under `attemptId`, so
@@ -1468,24 +1707,36 @@ export interface Escalation {
    *  escalation pages now or is held for the digest under the project's
    *  `reporting.interruptOn` policy (#229). */
   category?: InterruptCategory;
+  /** Deliver now even when policy would defer this category to the digest.
+   *  Used only when the digest's own orchestrator loop is unavailable. */
+  urgent?: true;
 }
 
-/** A tier-2 escalation the project's interrupt policy deferred to the digest. */
 export interface HeldNotice {
   id: string;
   category: InterruptCategory;
   summary: string;
   detail: string;
   createdAt: number;
+  /**
+   * This notice was otherwise interruptible and was held only by the
+   * availability window. It may be surfaced when the current policy opens.
+   */
+  releaseOnAvailable?: true;
+  /** Urgent recovery may bypass category batching, but never availability. */
+  urgent?: true;
 }
 
-/** What it takes to persist one held notice. */
 export interface HeldNoticeDraft {
+  /** Caller-supplied identity when the handoff must print or deduplicate it. */
+  id?: string;
   project: string;
   category: InterruptCategory;
   summary: string;
   detail: string;
   createdAt: number;
+  releaseOnAvailable?: true;
+  urgent?: true;
 }
 
 /**
@@ -1501,6 +1752,7 @@ export const DEFAULT_CAPS: Caps = {
   // guard silently watches the wrong meter (#110).
   planUsage: null,
   workerMaxTurns: 120,
+  workerMaxTurnsCeiling: 240,
   workerWallClockMs: 90 * 60 * 1000,
   maxAttemptsPerIssue: 2,
   maxContinuationsPerIssue: 2,