omp-conductor 0.19.7 → 0.20.1

package/src/types.ts

@@ -680,6 +680,18 @@ export const REVIEW_ADJUDICATOR_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
  */
 export const DEFAULT_REVIEW_ADJUDICATOR_ROLE = "task";
 
+/**
+ * Which OMP model role the daemon's own to-spec grooming scouts run under
+ * (#1041) when no project names one. Same value and same reasoning as
+ * {@link DEFAULT_REVIEW_ADJUDICATOR_ROLE} — the general session role every
+ * install can launch — but a separate constant because the two are separate
+ * operator choices: grooming judgement and review adjudication are answered
+ * independently in setup, and collapsing them would silently move one when the
+ * other is retuned. Validated with {@link REVIEW_ADJUDICATOR_RE}: one role-name
+ * grammar for every role token conductor stores.
+ */
+export const DEFAULT_GROOM_ROLE = "task";
+
 /**
  * One project's review policy (#678): the strictness its orchestrator applies
  * when deciding whether a green PR is returned to its worker, the hard
@@ -830,15 +842,89 @@ export type ReviewAdjudicationAdmission =
   | { kind: "existing"; record: ReviewAdjudicationRecord }
   | { kind: "refused"; block: "in-flight-different-head"; record: ReviewAdjudicationRecord };
 
+/**
+ * How one review-correction round was launched (#1045, child of #1044).
+ *
+ * `resume-original` is the pre-#1045 behaviour and stays the healthy default
+ * path: the findings are delivered into the *same* implementation transcript,
+ * which is why the round costs no attempt and needs no re-orientation.
+ * `fresh-correction` is the escape hatch #1035 proved necessary — the original
+ * session was exhausted (turn/wall cap, `model-empty-stop`) or the fleet's
+ * worker model changed after the rejected run, so replaying that transcript
+ * spends the round on a session that cannot take another turn or answers from
+ * a model nobody would dispatch today.
+ *
+ * A closed vocabulary rather than a boolean: the two modes read differently in
+ * a digest, and a third mode must be a compile-time change everywhere at once.
+ */
+export type ReviewLaunchMode = "resume-original" | "fresh-correction";
+
+/**
+ * The durable provenance of one review-correction round's launch (#1045): what
+ * the daemon decided, which model it asked for, which model the harness
+ * actually resolved, and the two session lineages involved.
+ *
+ * One definition, shared by the stored row ({@link ReviewRevisionRecord}) and
+ * the status projection ({@link ReviewCorrectionRound}, #1048), so a renderer
+ * and the row it renders cannot drift apart.
+ *
+ * *Every field is optional on purpose.* Rows written before #1045 recorded no
+ * decision at all, and the honest projection of one is "unknown" — never a
+ * fabricated `resume-original`, which would put an invented explanation in the
+ * very audit these fields exist to make truthful. Absent means nobody wrote it
+ * down, and a reader must say so.
+ */
+export interface ReviewCorrectionProvenance {
+  /** The decision, written once per round at dispatch time. */
+  launchMode?: ReviewLaunchMode;
+  /** What the daemon asked the harness for (a role alias, or a concrete
+   *  provider/model), as resolved from escalation/config at dispatch. */
+  requestedModel?: string;
+  /** What the harness actually resolved and ran — the answer to "which model
+   *  wrote this correction", which a role alias alone cannot give. */
+  resolvedModel?: string;
+  /** The implementation session lineage this round was reviewed *from*. Kept
+   *  even for a fresh correction: it is the transcript the findings came out
+   *  of, and losing it is losing the thread of the whole PR. */
+  originSessionRef?: string;
+  /** The fresh correction's own lineage, once the launch reports it. Only a
+   *  `fresh-correction` round has one — a resumed round *is* its origin. */
+  correctionSessionRef?: string;
+}
+
+/**
+ * One review-correction round exactly as the status snapshot carries it
+ * (#1048): the round's position, its lifecycle state, and the #1045 launch
+ * provenance the renderer prints beside it.
+ *
+ * Derived from the same `review_revisions` rows the dispatcher decides on, so
+ * status can never describe a round differently from the way it was launched —
+ * which is precisely the #1035 failure: the fleet showed `review-revision N`
+ * and nothing else while every one of those rounds replayed an exhausted
+ * transcript under a model the fleet had already stopped using.
+ */
+export interface ReviewCorrectionRound extends ReviewCorrectionProvenance {
+  round: number;
+  /** `pending` = enqueued, never dispatched; `dispatched` = live or
+   *  restart-recovered; `settled` = an outcome is recorded. */
+  state: "pending" | "dispatched" | "settled";
+  outcome?: ReviewRevisionOutcome;
+  dispatchedAt?: number;
+}
+
 /**
  * One durable review-revision request (#677): the orchestrator returned a
  * green, run-owned pull request to its worker with blocking findings, and
- * everything the daemon needs to resume the *same* OMP session is recorded
- * here before any worker is woken. The round numbers successive revisions of
- * one run (1, 2, …); the findings text is delivered to the resumed session
- * verbatim.
+ * everything the daemon needs to reach the *same work* is recorded here before
+ * any worker is woken. The round numbers successive revisions of one run
+ * (1, 2, …); the findings text is delivered to the launched session verbatim.
+ *
+ * Since #1045 the row also carries how the round was launched — resumed into
+ * the recorded transcript, or opened as a fresh correction on the same
+ * branch/PR — together with the models and session lineages involved, so a
+ * restart re-reads that decision instead of making it a second time.
  */
-export interface ReviewRevisionRecord {
+export interface ReviewRevisionRecord extends ReviewCorrectionProvenance {
   id: string;
   project: string;
   /** The run whose pushed-green row this revises. The row is reused, never
@@ -866,8 +952,29 @@ export interface ReviewRevisionRecord {
    *  `failed` — and this counter is what bounds that, durably, so an outage
    *  loop cannot retry one round forever. Absent means zero. */
   infraRetries?: number;
+  /** When the launch decision was made (#1045). Stamped by the deciding
+   *  dispatch and never moved afterwards, so a re-affirming retry cannot make
+   *  an old decision look new. Absent on a round nobody has decided yet, and
+   *  on every pre-#1045 row. */
+  launchDecidedAt?: number;
 }
 
+/**
+ * What a caller may hand {@link Store.enqueueReviewRevision} (#1045).
+ *
+ * Deliberately narrower than the record: the launch decision and its
+ * provenance belong to *dispatch*, not to the review that requested the round,
+ * and the enqueue INSERT does not persist them. Accepting them here would let
+ * a caller pass a `launchMode`, read it straight back off the returned record,
+ * and never notice the row does not carry it — the exact silent fake #1045
+ * names. They are written afterwards, once, by
+ * {@link Store.recordReviewRevisionLaunch}.
+ */
+export type ReviewRevisionDraft = Omit<
+  ReviewRevisionRecord,
+  "id" | keyof ReviewCorrectionProvenance | "launchDecidedAt"
+>;
+
 /**
  * The outcome of recording one `conductor_pr_review` finding against a run's
  * review-revision outbox (#786). `created` opened a new revision round for the
@@ -1034,6 +1141,15 @@ export interface ProjectConfig {
    *  every tick (#988). Optional; defaults to {@link DEFAULT_GROOM_BELOW} in
    *  orchestrator-tick.ts. */
   groomBelow?: GroomTrigger;
+  /**
+   * The OMP model role the daemon's own to-spec grooming scouts run under
+   * (#1041): a role token in the same grammar the review adjudicator uses
+   * ({@link REVIEW_ADJUDICATOR_RE}), never a provider/model — OMP owns model
+   * selection. Absent loads as {@link DEFAULT_GROOM_ROLE} (`"task"`), the
+   * general session role every install can launch without pinning a provider,
+   * which is what every project that never answered the question wants.
+   */
+  groomRole?: string;
   /** Labels the dispatcher writes back so the tracker alone shows live state
    *  to a human who never opens the daemon's logs. `backlog` is the
    *  operator's own park gesture (#507) — not dispatcher-written, but read by
@@ -1681,6 +1797,14 @@ export const FAILURE_CLASSES = [
   "dispatch-infra",
   "merge-conflict",
   "question",
+  /** A run that finished its work and stopped because it is waiting on an
+   *  observable condition — its settlement names `blockers:` (a PR whose
+   *  checks were still pending, say) and no question (#1068). Distinct from
+   *  `question` because the remedy is not a human: the recovery is the later
+   *  observation, which the settle sweep performs by re-offering the blocked
+   *  row until its PR resolves (this fleet's #1062 sat `blocked`/`question`
+   *  after its PR merged and its tick kept listing it for Duty 1 triage). */
+  "awaiting-observation",
   "orphan-clean",
   "orphan-dirty",
   "settlement-stuck",
@@ -1715,21 +1839,27 @@ export type FailureClass = (typeof FAILURE_CLASSES)[number];
 /**
  * What the daemon does about a class.
  *
- * Two of these perform nothing, and they are not the same nothing:
+ * Three of these perform nothing, and they are not the same nothing:
  *
+ * - `observe` — recorded and deliberately left alone, because the recovery IS
+ *   the later observation: `awaiting-observation` rows wait on something the
+ *   world will resolve (their PR), and the settle sweep re-offers the blocked
+ *   row until it does, settling it the way it settles `settlement-stuck` when
+ *   the PR merges. Like `hold` it never stamps `recoveredAt` — nothing is
+ *   recovered yet, by design (#1068).
  * - `hold` — recorded and deliberately left alone, because acting would destroy
  *   something. `orphan-dirty` is the case: the tree is the only copy, so
  *   `unblock` refuses rather than re-claiming over it.
  * - `none` — the classifier declining to name a failure at all. Two callers
  *   reach it, and neither is "unclassifiable": `classifyRun` returns it for a
- *   terminal row whose PR is open and fully green, where `classifyAndRecover`
+*   terminal row whose PR is open and fully green, where `classifyAndRecover`
  *   restores `pushed-green` *without* persisting a class (#766); and the settle
  *   sweep persists it beside `returned-for-revision` when a reviewer closes
  *   pushed work without merging, where the remedy is the queue label the sweep
  *   deliberately leaves on.
  *
  * An *unclassifiable* run is `unknown` → `escalate`, and never a silent retry.
- * This comment previously said nothing in the decision table maps to `none`,
+ * This comment previously said nothing in the decision tree maps to `none`,
  * which both callers above contradict; it cost a reading of two modules to
  * discover, which is what a wrong comment costs (#132).
  */
@@ -1739,6 +1869,7 @@ export const RECOVERY_ACTIONS = [
   "rerun-checks",
   "settle",
   "escalate",
+  "observe",
   "hold",
   "none",
 ] as const;
@@ -2036,11 +2167,13 @@ export interface RunRecord {
    */
   outputTokens?: number;
   reasoningTokens?: number;
-  /** The run id of the orphan-clean attempt whose session this row resumes
-   *  (#536, #567). Set only when the dispatch-time resume verdict fired;
-   *  absent means a fresh dispatch, never "resumed from unknown". Readable
-   *  without opening the transcript, so "how often did resume fire and did it
-   *  save turns" is a query, not a file walk. */
+  /** The run id whose session this row resumes: the orphan-clean attempt it
+   *  inherited (#536, #567), or — since the blocked-continuation resume — the
+   *  answered-block run whose transcript this continuation carries on. Set only
+   *  when a dispatch-time resume verdict fired; absent means a fresh dispatch,
+   *  never "resumed from unknown". Readable without opening the transcript, so
+   *  "how often did resume fire and did it save turns" is a query, not a file
+   *  walk. */
   resumedFromRunId?: string;
   prUrl?: string;
   /** Pull request head the worker observed after its deterministic CI watcher exited. */
@@ -2548,6 +2681,14 @@ export interface IntakeItem {
   issueUrl?: string;
   /** When the item was resolved into an issue (#300) or dismissed. */
   groomedAt?: number;
+  /**
+   * Provenance of a machine-filed item (Phase 4 signal mining) — the stable
+   * key of the signal that produced it, e.g.
+   * `mined:settlement-weakening:omp/src/foo.ts`. Absent means an operator
+   * typed this idea themselves, which surfaces matching on it must render as
+   * their own idea rather than as an unattributed machine signal.
+   */
+  source?: string;
 }
 
 /** What a caller hands over. The store owns the id, the state and the timestamps. */
@@ -2555,6 +2696,72 @@ export interface IntakeDraft {
   project: string;
   text: string;
   at: number;
+  /**
+   * Provenance and dedupe key in one (Phase 4). When present, the store
+   * derives the item's id DETERMINISTICALLY from `project` + `source` and
+   * inserts only if that id is new, so an hourly mining pass re-filing a
+   * signal it already filed is a no-op rather than an hourly duplicate.
+   *
+   * The consequence is intended: an item the operator dismissed stays
+   * dismissed instead of reappearing every hour, because the second filing
+   * cannot resurrect the row it collides with. The trap is the same fact from
+   * the other side — a signal genuinely worth re-raising later needs a
+   * DIFFERENT key, which is what a source carrying a bucket (a week, a run
+   * count) is for. A bare `mined:<kind>:<path>` is a once-ever claim.
+   *
+   * Absent for an operator's own idea, which keeps a random id and is
+   * therefore always a new row: two identical thoughts on two days are two
+   * thoughts.
+   */
+  source?: string;
+}
+
+/**
+ * Which daemon-owned session spent this (Phase 4 attribution). Exactly the two
+ * the daemon runs itself: to-spec grooming scouts and review adjudication.
+ *
+ * The orchestrator's own tick turns are deliberately NOT a member. The tick
+ * extension observes no spend or usage events at all — its `message_start`
+ * adapter reads content text — so there is no number to record, and a `0` row
+ * per tick would report the orchestrator as free. Orchestrator spend is
+ * reported as unmetered instead of invented.
+ */
+export const SESSION_SPEND_ROLES = ["groom", "adjudicator"] as const;
+
+export type SessionSpendRole = (typeof SESSION_SPEND_ROLES)[number];
+
+/**
+ * One daemon-owned session's turns and cost (Phase 4 attribution).
+ *
+ * The same shape going in and coming out: the store adds nothing but a rowid,
+ * because every field here is something the caller actually observed.
+ *
+ * `spendUsd` is OPTIONAL, and that is the contract rather than convenience.
+ * In the `runs` table an unmetered request and a genuinely free one are both
+ * `0`, which is why `spend-telemetry.ts` has to infer a subscription verdict
+ * from the share of zeros instead of reading a fact. Here the caller
+ * distinguishes them: omit `spendUsd` when the provider reported no cost for
+ * the session (subscription billing, or a harness that emitted no usage
+ * event), pass it when it reported a number — including a real `0`. A reader
+ * MUST render an absent `spendUsd` as unmetered and never as `$0.00`.
+ */
+export interface SessionSpendRow {
+  project: string;
+  role: SessionSpendRole;
+  /** The issue the session was about, when it was about one. Absent for a
+   *  grooming batch that spanned several. */
+  issue?: number;
+  /** The model the caller asked for. */
+  model?: string;
+  /** The model the harness actually ran, which is the one that was billed and
+   *  the one a per-model breakdown groups on. Absent when unobserved — never
+   *  filled in from `model`, because a requested model is not evidence of a
+   *  resolved one. */
+  resolvedModel?: string;
+  turns: number;
+  /** Absent means the provider reported no cost. See the interface note. */
+  spendUsd?: number;
+  at: number;
 }
 
 /**
@@ -2569,6 +2776,16 @@ export const GROOMING_VERDICTS = ["promotable", "blocked", "considered"] as cons
 
 export type GroomingVerdict = (typeof GROOMING_VERDICTS)[number];
 
+/**
+ * Who acted on a grooming verdict by queueing the issue (#1041). Three actors,
+ * because the promotion audit's whole question is which of them did it: the
+ * daemon promotes unattended once the ready gate passes, an orchestrator tick
+ * promotes as part of its own reasoning, and an operator promotes by hand. A
+ * fourth spelling would mean a fourth promotion path exists, which is exactly
+ * what this closed union is here to prevent.
+ */
+export type PromotedBy = "daemon" | "orchestrator" | "operator";
+
 /**
  * One issue's current grooming verdict, durable across restarts and keyed by
  * project + issue — one row per issue, replaced in place by upsert, never a
@@ -2587,6 +2804,24 @@ export interface GroomingRecord {
    *  or a scout summary. Free text, bounded at the write site. */
   evidence: string;
   recordedAt: number;
+  /**
+   * When this verdict was acted on by queueing the issue (#1041). Absent on
+   * every verdict nobody promoted, which is the honest reading of a row from
+   * before mechanical promotion existed: nothing recorded who queued it, so
+   * nothing may claim to know.
+   *
+   * Set exactly once per verdict, by {@link Store.markGroomingPromoted}, and
+   * cleared by the next `upsertGrooming` — a re-recorded verdict is a new
+   * judgement about the issue, and provenance that outlived the judgement it
+   * describes would audit the wrong decision.
+   */
+  promotedAt?: number;
+  /** Who queued it: the daemon's own ready gate, an orchestrator tick, or an
+   *  operator at the CLI. Stored rather than inferred — the tick's promotion
+   *  audit exists precisely to review what the daemon did unattended, and a
+   *  guess would make that review circular. Always present when
+   *  {@link promotedAt} is, and absent when it is not. */
+  promotedBy?: PromotedBy;
 }
 
 /** What a caller hands over. The store owns the timestamp and the replace-in-
@@ -2600,6 +2835,32 @@ export interface GroomingDraft {
   at: number;
 }
 
+/**
+ * One operator's standing approval of an epic's scope (#1041).
+ *
+ * Deliberately its own durable fact rather than a resolved decision row, for
+ * two reasons that both bite in production. First, approving an epic is an
+ * explicit, revocable act with exactly one meaning — "the children of this
+ * epic may be queued without asking me again" — while a decision row's
+ * `resolution` is free text a human wrote for a human, and no amount of
+ * parsing turns "yes, but do the migration first" into a machine gate. Second,
+ * decision rows expire ({@link DECISION_TTL_MS}) and an approval must not:
+ * scope consent does not lapse after a week just because nobody looked at it.
+ *
+ * Carries no `project` field because it is always read through a
+ * project-scoped accessor — the scoping is the key, not a payload column an
+ * unwary caller could compare against the wrong project.
+ */
+export interface EpicApproval {
+  issue: number;
+  approvedAt: number;
+  /** Who approved it, in the same spelling the report-withdrawal path already
+   *  uses: the session role when one is set, else `orchestrator` inside a
+   *  Herdr pane, else `operator`. Free text on purpose — it is provenance for
+   *  a human reading an audit line, never a gate anything branches on. */
+  approvedBy: string;
+}
+
 /**
  * Where one operator decision stands (#136).
  *
@@ -2781,7 +3042,7 @@ export interface Store {
    *  two concurrent same-head findings cannot both create a row or overwrite
    *  each other (the run row's state is the other half once the revision is
    *  dispatched). */
-  enqueueReviewRevision(draft: Omit<ReviewRevisionRecord, "id">): ReviewRevisionEnqueue;
+  enqueueReviewRevision(draft: ReviewRevisionDraft): ReviewRevisionEnqueue;
   /** The pending revision for one run, if any — the header the verb reads to
    *  tell "this call folds into the in-flight round" from "this call opens a
    *  new round" before the round-ceiling gate applies. */
@@ -2793,6 +3054,51 @@ export interface Store {
   latestReviewRound(project: string, runId: string): number;
   /** Record that a revision was handed to a worker. */
   markReviewRevisionDispatched(id: string, at: number): void;
+  /** Record, once, how this review round is being launched (#1045).
+   *
+   *  Write-once and atomic — one guarded UPDATE, never read-then-write, so two
+   *  dispatch passes cannot each decide. The FIRST decision for a round wins:
+   *
+   *  - no decision yet ⇒ written, `true`;
+   *  - the identical decision again (a dispatch retry, a restart re-deciding
+   *    the same way) ⇒ no-op, `true`, and the original `launchDecidedAt`
+   *    stands;
+   *  - a *contradictory* decision (different mode, requested model or origin
+   *    lineage) ⇒ nothing written, `false`. The caller must re-read the
+   *    recorded decision and honour it rather than launching its own;
+   *  - no such round in this project ⇒ `false`.
+   *
+   *  Touches the decision columns only. The issue, run, attempt/continuation
+   *  charges, round number, branch, PR URL, reviewed head, findings and
+   *  settlement history are the round's identity and are never written here. */
+  recordReviewRevisionLaunch(
+    project: string,
+    id: string,
+    decision: {
+      launchMode: ReviewLaunchMode;
+      requestedModel?: string;
+      originSessionRef?: string;
+      at: number;
+    },
+  ): boolean;
+  /** Attach the fresh correction's own session lineage — and the model the
+   *  harness actually resolved — to a round already decided
+   *  `fresh-correction` (#1045). `false`, writing nothing, on a round decided
+   *  `resume-original`, on an undecided round, or on no such round: a resumed
+   *  round *is* its origin session, so recording a separate correction
+   *  lineage for one would invent a session that never existed.
+   *
+   *  Not write-once, and deliberately so: an infra-killed round relaunches on
+   *  the same decision, and the newest fresh session is then the truth about
+   *  what is running. `resolvedModel` is only ever added, never cleared — a
+   *  later call without one leaves a known resolution in place. */
+  recordReviewCorrectionSession(project: string, id: string, ref: string, resolvedModel?: string): boolean;
+  /** The recorded launch decision and provenance for one round, or `undefined`
+   *  when no such round exists (#1045). Every field is absent on a round
+   *  nobody has decided and on every pre-#1045 row — the explicit unknown a
+   *  claim/retry/restart path must read *before* deciding, and the honest
+   *  projection a renderer must print instead of guessing. */
+  reviewRevisionLaunch(project: string, id: string): ReviewCorrectionProvenance | undefined;
   /** Record how a revision ended. */
   settleReviewRevision(id: string, outcome: ReviewRevisionOutcome, at: number): void;
   /** Every revision row not yet settled — queued (`dispatchedAt` unset) and
@@ -3118,15 +3424,37 @@ 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). */
+  /**
+   * Persist one raw idea, `pending`, for later grooming (#299).
+   *
+   * Idempotent when {@link IntakeDraft.source} is present (Phase 4): the id is
+   * derived from `project` + `source` and the insert is ignored if that id
+   * already exists, so the hourly mining pass is safe to re-run. A collision
+   * returns the EXISTING row untouched — which is how a caller tells a new
+   * filing from a no-op (`item.createdAt !== draft.at`, or a `state` that is
+   * no longer `pending`) — and in particular does NOT reopen an item the
+   * operator dismissed.
+   *
+   * Without a `source` the id is random, so every call is a new row.
+   */
   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;
-  /** Record the current grooming verdict for one issue, replacing any prior
-   *  row — one row per project + issue, never a history (#735). */
+  /**
+   * Record the current grooming verdict for one issue, replacing any prior
+   * row — one row per project + issue, never a history (#735).
+   *
+   * Clears {@link GroomingRecord.promotedAt}/{@link GroomingRecord.promotedBy}
+   * (#1041). A re-recorded verdict is a fresh judgement about the issue, so
+   * carrying the old promotion forward would let the audit attribute a queueing
+   * to a verdict that no longer exists — and, worse, would make a demote-then-
+   * regroom cycle read as though the demoted promotion still stood. A caller
+   * that re-promotes stamps provenance again through
+   * {@link markGroomingPromoted}, which is the only writer of these columns.
+   */
   upsertGrooming(draft: GroomingDraft): void;
   /** The current grooming verdict for one issue, or undefined when none. */
   grooming(project: string, issue: number): GroomingRecord | undefined;
@@ -3142,6 +3470,15 @@ export interface Store {
    * self-heals instead of lingering as a cache someone must invalidate. Runs
    * at the end of every admission pass. Never touches `promotable` or
    * `considered` rows, which belong to #679's scout loop.
+   *
+   * A promoted row (#1041) is likewise inert here, in both directions: it is
+   * neither overwritten with `blocked` nor swept by the self-clearing delete.
+   * Promotion hands the issue to dispatch, and admission's lane/dependency
+   * holds on a queued issue are flow control of the moment, not a re-grooming.
+   * Without this the fleet would lose the audit line within one 5-minute
+   * admission pass — a promoted issue whose lane overlaps an active run would
+   * be rewritten as `blocked` and then deleted — long before the ~30-minute
+   * tick that is supposed to review the promotion ever read it.
    */
   reconcileGrooming(
     project: string,
@@ -3162,6 +3499,48 @@ export interface Store {
    * snapshot here deletes verdicts nobody re-derived.
    */
   retireGroomingNotOpen(project: string, openIssues: readonly number[]): number[];
+  /**
+   * Stamp promotion provenance on one existing verdict (#1041), returning
+   * whether this call is the one that stamped it.
+   *
+   * `false` on both no-op shapes, and the caller must treat them the same way:
+   * there is no such verdict, or it already carries a promotion. That makes the
+   * write the single-flight latch for promotion itself — the daemon enqueues the
+   * queue label and fires the wake only when it wins this call, so a restart
+   * mid-promotion re-reads a stamped row and does not queue the issue twice.
+   * Provenance is therefore stamped BEFORE the label op, never after.
+   */
+  markGroomingPromoted(project: string, issue: number, at: number, by: PromotedBy): boolean;
+  /**
+   * Verdicts promoted at or after `since`, newest promotion first — the tick's
+   * promotion audit (#1041): what was queued unattended while nobody was
+   * looking, with the verdict and evidence that justified it still attached.
+   *
+   * Bounded by the window rather than by a count, because the audit's contract
+   * is "everything since the last tick" — a truncated list would silently
+   * un-audit a promotion.
+   */
+  promotionsSince(project: string, since: number): GroomingRecord[];
+  /**
+   * Record the operator's standing approval of one epic's scope (#1041).
+   *
+   * Idempotent and first-write-wins: re-approving keeps the original
+   * `approvedAt` and `approvedBy`, because the durable fact is when consent was
+   * given, not when it was last restated. A caller that must tell "approved
+   * now" from "already approved" reads {@link epicApproval} first. Refuses a
+   * non-integer or non-positive issue number rather than storing a fact about
+   * an issue that cannot exist.
+   */
+  approveEpic(project: string, issue: number, at: number, by: string): void;
+  /** Withdraw an epic's approval, `false` when there was none to withdraw.
+   *  Approval is revocable by design: scope consent an operator regrets must be
+   *  removable without deleting the epic or its children (#1041). */
+  revokeEpicApproval(project: string, issue: number): boolean;
+  /** One epic's approval, or `undefined` when it has none — which every gate
+   *  must read as "not approved", never as approval whose row is missing. */
+  epicApproval(project: string, issue: number): EpicApproval | undefined;
+  /** Every approved epic in this project, issue-ascending. */
+  epicApprovals(project: string): EpicApproval[];
   /** Count and age source for status and digest prompt bounds. */
   digestBacklog(project: string): DigestBacklog;
   /** Add one bounded observation to the per-day friction rollup. */
@@ -3211,6 +3590,38 @@ export interface Store {
   bumpGhCalls?(day: string, source: string): void;
   /** The tracked call counts for a UTC day, per source. */
   ghCallsToday?(day: string): { source: string; calls: number }[];
+  /**
+   * Record one auto-restart the daemon fired at a wedged orchestrator
+   * (Phase 4). A bare append, like {@link Store.recordGhRefusal}: the cap is
+   * enforced by counting rows in a window, so there is no counter to reset and
+   * a crash cannot leave a high-water mark that either disables the cap or
+   * spends it twice. Rows older than a week are pruned in the same write.
+   */
+  recordOrchestratorRestart(project: string, at: number, reason: string): void;
+  /**
+   * This project's auto-restarts at or after `since`, NEWEST FIRST — the
+   * bounded-restart gate counts them against its per-window cap, and the page
+   * it sends when the cap is reached names the most recent reasons.
+   */
+  orchestratorRestartsSince(project: string, since: number): { at: number; reason: string }[];
+  /**
+   * Record what one daemon-owned session (grooming, adjudication) cost
+   * (Phase 4 attribution). Append-only; these sessions have no lifecycle to
+   * update, they either ran or they did not.
+   *
+   * Deliberately not a `runs` row: `computeStats` walks runs as issue journeys
+   * and a role row in there would invent a journey, corrupt the settled counts
+   * and misattribute grooming spend to a merge it did not produce.
+   *
+   * Omit `spendUsd` when the provider reported no cost — see
+   * {@link SessionSpendRow}.
+   */
+  recordSessionSpend(row: SessionSpendRow): void;
+  /** This project's daemon-owned session spend at or after `since`, newest
+   *  first. Never includes worker runs: those live in `runs` and are already
+   *  counted by {@link Store.statsRuns}, so summing both surfaces gives the
+   *  fleet's whole bill without double-counting either half. */
+  sessionSpendSince(project: string, since: number): SessionSpendRow[];
   /**
    * Persist a rendered report `pending`, before anything is sent — the whole
    * point of #123 is that an undelivered report is a queryable row rather than
@@ -3665,10 +4076,15 @@ export const VERB_NAMES = [
    *  re-enter normal review/merge without a fresh clone. Idempotent: an
    *  already-matching PR is returned, not duplicated. */
   "conductor_pr_recover",
-  /** The one read verb. It answers with the merge gate's own verdict, so
+  /** The first 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. */
   "conductor_pr_status",
+  /** The second read verb (#1043 lane): the decisive log lines of the failing
+   *  jobs at one pull request's head, through the tracker's bounded
+   *  failed-attempt log read. A worker calls it to diagnose a red check it
+   *  must fix, instead of guessing from the check name. */
+  "conductor_ci_logs",
 ] as const;
 
 export type VerbName = (typeof VERB_NAMES)[number];

package/src/verbs/protocol.ts

@@ -484,6 +484,34 @@ export const VERB_SPECS: Readonly<Record<VerbName, VerbSpec>> = {
     },
     roleRefusalText: (role) => `conductor_pr_status is not open to a ${role} session.`,
   },
+  conductor_ci_logs: {
+    name: "conductor_ci_logs",
+    mutating: false,
+    allowedRoles: ["worker", "orchestrator"],
+    description:
+      "Read the failing CI jobs' own log output at one pull request's head. Call this when " +
+      "conductor_pr_status reports a red check you have to fix, INSTEAD of guessing from the check name or " +
+      "re-running the suite locally to see what CI saw. It answers with the failed steps of every failed job " +
+      "across the head's attempts, bounded to the newest evidence and truncated per job when large — so it is " +
+      "cheap in turns but not free in context; read it once and fix from it, do not poll it. Read-only: it " +
+      "changes nothing and is not ledgered. If the logs cannot be read it says so — an unreadable log is never " +
+      "reported as \"no failures\". A worker may omit prUrl and gets its own run's.",
+    args: {
+      prUrl: {
+        type: "string",
+        required: false,
+        description: "Full pull request URL. Omit as a worker to read your own run's.",
+      },
+      headSha: {
+        type: "string",
+        required: false,
+        description:
+          "Optional: the head you believe you are diagnosing. If the branch has moved since, the call is " +
+          "refused naming both shas rather than handing you logs from a superseded commit.",
+      },
+    },
+    roleRefusalText: (role) => `conductor_ci_logs is not open to a ${role} session.`,
+  },
 };
 
 export interface VerbRequest {