omp-conductor 0.3.25 → 0.4.0

package/src/types.ts

@@ -7,6 +7,32 @@
  * is `DEFAULT_CAPS`, which is data, not behaviour.
  */
 
+/**
+ * A threshold on one provider-reported allowance window.
+ *
+ * Both fields exist because of what the real `omp usage --json` payload looks
+ * like. `limits` is a *list* — one Anthropic account reports `anthropic:5h`,
+ * `anthropic:7d` and `anthropic:7d:fable` at once — so the window is named
+ * rather than positional. And `unit` differs per provider (`percent` for
+ * Anthropic, `unknown` with raw counts for `xai-oauth`), so the threshold is a
+ * fraction of the allowance and never a raw count.
+ */
+export interface PlanUsageCap {
+  /**
+   * Which allowance this threshold is about: the fully-qualified limit id
+   * (`"anthropic:7d"`), or a bare window key (`"7d"`) when exactly one
+   * reported allowance carries it. An id nothing reports holds dispatch and
+   * says so — it is never quietly treated as unmetered.
+   */
+  windowId: string;
+  /**
+   * Consumed share, `0`–`1`, at which new claims stop. `0.85` holds at 85% of
+   * the allowance. A fraction rather than a percentage so the config cannot
+   * read `85` and mean "never".
+   */
+  maxUsedFraction: number;
+}
+
 /**
  * Hard limits enforced in code, never by the model. A worker that is asked to
  * respect a budget will eventually talk itself out of it, so the dispatcher
@@ -21,6 +47,13 @@ export interface Caps {
    * still apply). `0` is a hard stop — deliberate, not "unset".
    */
   dailySpendUsd: number | null;
+  /**
+   * Subscription/plan allowance guard, independent of `dailySpendUsd` and
+   * enforced from the provider's own reported usage rather than from a dollar
+   * figure conductor made up (#110). `null` means unmetered: the fleet has no
+   * plan allowance worth guarding, or none this host can read.
+   */
+  planUsage: PlanUsageCap | null;
   /** Turn ceiling for one worker — catches loops that are burning tokens
    *  without converging. */
   workerMaxTurns: number;
@@ -97,16 +130,94 @@ export type ReportScope = (typeof REPORT_SCOPES)[number];
 export const DEFAULT_REPORT_SCOPE: ReportScope = "material";
 
 /**
- * Mechanical permission for release-shaped tool calls. `authority.release`
- * says who owns the decision; this key is the enforcement gate that decides
- * whether an autonomous session may invoke the tools at all.
+ * The irreversible tool-call shapes this package recognises and gates. Data
+ * here rather than in `release-policy.ts` because the config validator, the
+ * setup wizard and the status renderer now all enumerate them (#122): a sixth
+ * shape must fail to compile in each of those places rather than silently
+ * resolve to "not granted" in one of them.
+ *
+ * Deliberately generic. Fleet-specific release topology — a suite pin, a
+ * registry, an IaC stack — belongs in the operator's POLICY.md, not here: a
+ * conductor installed with no npm and no Kubernetes must neither carry those as
+ * dead config nor be asked about them by the wizard.
+ */
+export const RELEASE_SHAPES = [
+  "git-tag",
+  "git-push-tags",
+  "package-publish",
+  "github-release",
+  "deploy",
+] as const;
+
+export type ReleaseShape = (typeof RELEASE_SHAPES)[number];
+
+/**
+ * Mechanical permission per release shape. `authority.release` says who owns
+ * the *decision*; this key is the enforcement gate that decides whether an
+ * autonomous session may invoke the tools at all.
+ *
+ * A map rather than the binary it replaced: under the old `"operator-brief"`
+ * one grant covered cutting a tag and mutating a running environment, and on
+ * 2026-08-09 a stale grant was enough for an orchestrator session to invoke
+ * Komodo `DeployStack` (#122). Producing an artifact and changing what is
+ * running are different acts with different blast radii and different rollback
+ * owners, so they are granted separately or not at all.
+ *
+ * Legacy string forms still parse and are migrated at load; absent keys deny.
+ */
+export type ReleasePolicy = "none" | Partial<Record<ReleaseShape, AuthorityHolder>>;
+
+/** After normalisation: every shape present, absent keys denied as `"human"`. */
+export type ResolvedGrants = Record<ReleaseShape, AuthorityHolder>;
+
+/**
+ * The on-disk spellings from before the grant map. Read and migrated, never
+ * written again — data so the validator's error message and the migration table
+ * cannot come to name different sets.
+ */
+export const LEGACY_RELEASE_POLICIES = ["none", "operator-brief"] as const;
+
+/**
+ * Fail-closed baseline: nothing granted to any session. Written out rather than
+ * derived from {@link RELEASE_SHAPES} so `Record` makes a new shape a compile
+ * error here — a shape this table forgot would read as `undefined` at the gate,
+ * and `undefined !== role` is only accidentally safe.
+ */
+export const DENIED_RELEASE_GRANTS: ResolvedGrants = {
+  "git-tag": "human",
+  "git-push-tags": "human",
+  "package-publish": "human",
+  "github-release": "human",
+  deploy: "human",
+};
+
+/**
+ * What the legacy `"operator-brief"` string migrates to: the safe reading of
+ * what operators believed they were enabling when they opened the binary gate.
+ * `deploy` stays with the human, because that is the grant nobody knowingly
+ * gave — see #122.
  */
-export const RELEASE_POLICIES = ["none", "operator-brief"] as const;
+export const OPERATOR_BRIEF_GRANTS: ResolvedGrants = {
+  "git-tag": "orchestrator",
+  "git-push-tags": "orchestrator",
+  "package-publish": "orchestrator",
+  "github-release": "orchestrator",
+  deploy: "human",
+};
 
-export type ReleasePolicy = (typeof RELEASE_POLICIES)[number];
+/**
+ * What kind of session is asking. Explicit at every gate rather than inferred
+ * from confinement or from which module made the call: a worker's refusal must
+ * not depend on a boolean some future call site forgets to pass.
+ *
+ * Note the two sets: a grant is an {@link AuthorityHolder}, never a
+ * `SessionRole`, so `"worker"` can never equal a grant and a worker is refused
+ * every shape whatever the config says. The type does that enforcing, not a
+ * check some path can miss.
+ */
+export const SESSION_ROLES = ["worker", "orchestrator"] as const;
 
-/** Safe for old and partial configs: release/deploy tools stay closed. */
-export const DEFAULT_RELEASE_POLICY: ReleasePolicy = "none";
+export type SessionRole = (typeof SESSION_ROLES)[number];
 
 /**
  * Who holds an authority the daemon itself never exercises. Declared as data
@@ -125,6 +236,290 @@ export type AuthorityHolder = (typeof AUTHORITY_HOLDERS)[number];
  */
 export const DEFAULT_AUTHORITY: ProjectConfig["authority"] = { merge: "human", release: "human" };
 
+/**
+ * Whether a merge candidate must be up to date with the branch it targets.
+ *
+ * Declared as data for the reason {@link AUTHORITY_HOLDERS} is, and extracted
+ * from POLICY.md prose for a sharper one (#129): until this key existed the
+ * answer was a sentence an operator wrote and a session re-read every tick, so
+ * two ticks could reach two answers and neither left a trace of having decided.
+ * A set-membership check leaves the same trace every time.
+ */
+export const BASE_FRESHNESS = ["up-to-date", "any"] as const;
+
+export type BaseFreshness = (typeof BASE_FRESHNESS)[number];
+
+/**
+ * What a draft pull request is to the merge gate. `block` by default: a draft is
+ * the author's own statement that the work is not finished, and an autonomous
+ * merge that overrides that has read the diff rather than the intent.
+ */
+export const DRAFT_POLICIES = ["block", "allow"] as const;
+
+export type DraftPolicy = (typeof DRAFT_POLICIES)[number];
+
+/**
+ * What to do with an otherwise-mergeable pull request that has fallen behind its
+ * base branch.
+ *
+ * `update-branch` is the package floor's one sanctioned write into a worker's
+ * branch — `gh pr update-branch`, then a wait for the fresh run — and it is the
+ * default because merging promptly is itself what stops the next PR going stale.
+ * `hold` leaves it for whoever refreshes it; `escalate` pages rather than
+ * guessing. Closing it and an admin bypass are absent on purpose: neither was
+ * ever an answer, and a vocabulary that cannot spell them cannot be argued into
+ * one.
+ */
+export const BEHIND_BASE_ACTIONS = ["update-branch", "hold", "escalate"] as const;
+
+export type BehindBaseAction = (typeof BEHIND_BASE_ACTIONS)[number];
+
+/**
+ * What must already have landed before a release may be cut. Each member is
+ * something the daemon can settle against its own store or the tracker — that is
+ * the entry price for being in this list rather than in POLICY.md.
+ */
+export const RELEASE_REQUIREMENTS = [
+  /** Every run this release covers reached `merged`, not merely `pushed-green`. */
+  "runs-settled",
+  /** No pull request is still open against the branch being released. */
+  "no-open-prs",
+  /** Nothing still carries the queue label: the batch is finished, not paused. */
+  "queue-drained",
+  /** The epic this release closes has no open children left. */
+  "epic-children-closed",
+] as const;
+
+export type ReleaseRequirement = (typeof RELEASE_REQUIREMENTS)[number];
+
+/**
+ * What must be true before a pull request may be merged.
+ *
+ * These four were sentences in the shipped POLICY.md until #129, which meant a
+ * verb could honour them only by asking a model to read prose and agree with it.
+ * Typed here, the decision is a pure function of config: the same PR gets the
+ * same answer on Friday as on Tuesday, and a refusal can name the field that
+ * produced it.
+ */
+export interface MergePreconditions {
+  /**
+   * Named checks that must have concluded successfully. Empty means *every*
+   * check the pull request reports — the strict reading, and the one a project
+   * that never answered the question wants.
+   */
+  requiredChecks: string[];
+  /** Whether the head must be up to date with its base. See {@link BASE_FRESHNESS}. */
+  baseFreshness: BaseFreshness;
+  /** What a draft pull request is. See {@link DRAFT_POLICIES}. */
+  drafts: DraftPolicy;
+  /**
+   * What to do when `baseFreshness` is `"up-to-date"` and the head is not.
+   * Consulted only then: under `"any"` there is no behind-base case to answer.
+   */
+  whenBehindBase: BehindBaseAction;
+}
+
+/**
+ * What must be true before a release may be cut: what has landed, what it
+ * produces, and where it may be pushed.
+ *
+ * `artefacts` and `environments` are empty by default, and empty denies. A
+ * project that never named an artefact has not authorised releasing one, and a
+ * project that named no environment has authorised no deploy target — the same
+ * posture as an absent release grant (#122). The config says yes out loud, or it
+ * has not said yes.
+ */
+export interface ReleasePreconditions {
+  /** What must already have landed. See {@link RELEASE_REQUIREMENTS}. */
+  requires: ReleaseRequirement[];
+  /**
+   * Named checks that must be green on the branch being released. Empty means
+   * every check that branch reports.
+   */
+  requiredChecks: string[];
+  /** Packages or images this project releases. Empty denies every artefact. */
+  artefacts: string[];
+  /** Environments a deploy may target. Empty denies every environment. */
+  environments: string[];
+}
+
+/**
+ * The gating conditions #126's verbs read instead of POLICY.md. Optional on disk
+ * and complete after the loader has seen it, so no consumer has to know which of
+ * these fields the operator happened to spell.
+ */
+export interface ProjectPolicy {
+  merge: MergePreconditions;
+  release: ReleasePreconditions;
+}
+
+/**
+ * What a project that never answered the question gets: the strictest reading of
+ * the prose these fields replaced. Every check green, the base fresh, drafts
+ * refused, a behind-base PR refreshed rather than merged, and a release only of
+ * work that actually landed — with no artefact and no environment declared, so a
+ * release verb has nothing to act on until an operator says what this project
+ * ships.
+ */
+export const DEFAULT_PROJECT_POLICY: ProjectPolicy = {
+  merge: {
+    requiredChecks: [],
+    baseFreshness: "up-to-date",
+    drafts: "block",
+    whenBehindBase: "update-branch",
+  },
+  release: {
+    requires: ["runs-settled"],
+    requiredChecks: [],
+    artefacts: [],
+    environments: [],
+  },
+};
+
+/**
+ * Why a merge is being asked for. A closed set rather than free text, for the
+ * reason every other vocabulary here is closed: a `reason` the daemon matches on
+ * is a field that decides, and a decision made out of a model's own wording is
+ * one no two ticks spell the same way.
+ */
+export const MERGE_REASONS = [
+  /** Every condition in {@link MergePreconditions} is satisfied as it stands. */
+  "preconditions-met",
+  /** It was behind its base, was refreshed, and came back green. */
+  "behind-base-refreshed",
+  /** A human in the loop asked for this one specifically. */
+  "operator-instructed",
+  /** It is what a release otherwise ready to cut is waiting on. */
+  "release-blocking",
+] as const;
+
+export type MergeReason = (typeof MERGE_REASONS)[number];
+
+/** Why a release is being cut now. Closed for the reason {@link MERGE_REASONS} is. */
+export const RELEASE_REASONS = [
+  /** The batching unit the operator described in POLICY.md has been reached. */
+  "batch-complete",
+  /** The epic this release closes has no open children left. */
+  "epic-closed",
+  /** A fix that cannot wait for the batch. */
+  "hotfix",
+  /** A human in the loop asked for this one specifically. */
+  "operator-instructed",
+] as const;
+
+export type ReleaseReason = (typeof RELEASE_REASONS)[number];
+
+/**
+ * Why a tracker label is being changed. Closed for the reason
+ * {@link MERGE_REASONS} is, and load-bearing past bookkeeping: the queue label is
+ * the claim gate, so "why did this issue become claimable" has to be answerable
+ * from the ledger rather than from a session transcript nobody kept.
+ */
+export const LABEL_REASONS = [
+  /** Groomed and promoted onto the queue. */
+  "promoted-to-queue",
+  /** Re-briefed after a failed attempt, and put back on the queue. */
+  "re-briefed",
+  /** Parked: it needs a decision only a human can make. */
+  "needs-human",
+  "duplicate",
+  "superseded",
+  "out-of-scope",
+] as const;
+
+export type LabelReason = (typeof LABEL_REASONS)[number];
+
+/**
+ * A model-supplied justification: one value out of a closed set, plus prose that
+ * is written down and read by nothing that decides.
+ *
+ * The split is the whole point. `reason` is matched, so it is an enum the daemon
+ * enumerates. `rationale` is logged verbatim for the human who later asks why,
+ * and nothing branches on it — the moment something does, the vocabulary stops
+ * being the enum above and becomes whatever a model felt like typing.
+ */
+export interface VerbJustification<R extends string> {
+  reason: R;
+  /** Free-form. Logged, never parsed, never matched. */
+  rationale?: string;
+}
+
+export type MergeJustification = VerbJustification<MergeReason>;
+
+export type ReleaseJustification = VerbJustification<ReleaseReason>;
+
+export type LabelJustification = VerbJustification<LabelReason>;
+
+/**
+ * How hard a boundary separates model-executed code from the operator's GitHub
+ * write credential (#125).
+ *
+ * Three values, ordered strongest first, because the difference between them is
+ * a difference in what anyone can honestly claim:
+ *
+ * - `per-run` — every session runs as its own OS principal that cannot read the
+ *   daemon's `gh` config, keychain, `~/.ssh` or `~/.npmrc`, and cannot write a
+ *   sibling run's checkout. Satisfied **only** by the `uid-pool` and
+ *   `sandbox-exec` mechanisms.
+ * - `group-mode` — same uid as the daemon, cross-run separation by group and
+ *   mode only. It bounds accidents and does **not** contain a determined bash
+ *   escape. It exists as a config value rather than as a fallback so that an
+ *   operator who takes it has said the weaker sentence out loud: a `per-run`
+ *   request that quietly resolved to this would let somebody believe they had
+ *   configured the full boundary and shipped the lesser one, which is precisely
+ *   the "never the silent default" failure #125 exists to end.
+ * - `none` — the session runs as the daemon's own user and the env scrubbing in
+ *   `credentials.ts` is *all* that stands between the model and the credential,
+ *   which same-uid code defeats in one line.
+ *
+ * A request is never downgraded. If the host cannot build what was asked for,
+ * dispatch refuses and names the missing mechanism.
+ */
+export const CREDENTIAL_ISOLATIONS = ["per-run", "group-mode", "none"] as const;
+
+export type CredentialIsolation = (typeof CREDENTIAL_ISOLATIONS)[number];
+
+/**
+ * What the host can actually enforce, decided by the startup probe rather than
+ * by config. Kept separate from {@link CREDENTIAL_ISOLATIONS} on purpose: the
+ * operator asks for a boundary, the host says which one it can build, and
+ * `status` reports the difference instead of letting either side guess.
+ *
+ * - `uid-pool` — one unprivileged account per run slot, entered through a
+ *   privilege-dropping launcher. The only mechanism that claims to contain a
+ *   determined bash escape on Linux.
+ * - `group-mode` — same uid as the daemon, cross-run separation by group and
+ *   mode only. Bounds accidents, does **not** contain an escape.
+ * - `sandbox-exec` — the macOS equivalent of `uid-pool` for a dev host.
+ * - `none` — no boundary at all.
+ */
+export const ISOLATION_MECHANISMS = ["uid-pool", "group-mode", "sandbox-exec", "none"] as const;
+
+export type IsolationMechanism = (typeof ISOLATION_MECHANISMS)[number];
+
+/**
+ * The two groups the filesystem model needs, named once so the probe, the
+ * provisioning docs and the adversarial tests cannot drift apart (#125).
+ *
+ * `daemon` holds the daemon account **only** and is what lets it fetch, salvage
+ * and reclaim every run repo. `runs` holds every slot principal and grants
+ * read-only access to the shared mirror. A slot principal in `daemon` would
+ * void the whole cross-run boundary, so the probe asserts the absence.
+ */
+export const CONDUCTOR_GROUPS = { daemon: "conductor-daemon", runs: "conductor-runs" } as const;
+
+/** Per-project credential boundary settings. See {@link CREDENTIAL_ISOLATIONS}. */
+export interface CredentialConfig {
+  isolation: CredentialIsolation;
+  /**
+   * Optional **read-scoped** token handed to sessions so they can look things
+   * up on GitHub. Absent is the default and the safe reading: a worker then
+   * works from its dispatch brief and the daemon's mediated verbs, which is
+   * why the brief must not tell it to run `gh pr view`.
+   */
+  readToken?: string;
+}
+
 /**
  * Where the session that triages escalations lives. `embedded` is the daemon's
  * own child session; `external` means an operator already runs one — a visible
@@ -174,21 +569,55 @@ export interface ProjectConfig {
    */
   authority: { merge: AuthorityHolder; release: AuthorityHolder };
   /**
-   * Tool-call enforcement for releases and deploys. Optional only for configs
-   * written before the tripwire existed; omission resolves fail-closed to
-   * {@link DEFAULT_RELEASE_POLICY}.
+   * Per-shape tool-call enforcement for releases and deploys. Optional only for
+   * configs written before the tripwire existed; both omission and any shape key
+   * this map leaves out resolve fail-closed to `"human"`.
+   *
+   * Never read directly — go through `resolveReleaseGrants`, which is where the
+   * legacy `"none"` / `"operator-brief"` strings are migrated and where the
+   * absent-key denial is spelled once.
    */
   releasePolicy?: ReleasePolicy;
+  /**
+   * The gating conditions a merge or a release must satisfy (#129), extracted
+   * from POLICY.md so a verb decides from typed config rather than from prose it
+   * re-interprets every tick.
+   *
+   * Optional only for configs written before the key existed. The loader always
+   * produces a complete value, so read it through `resolvePolicy` rather than
+   * reaching for `.merge` on a project some test hand-built.
+   */
+  policy?: ProjectPolicy;
   /**
    * How loud the orchestrator is. Optional on disk — a config written before
    * this key existed loads as {@link DEFAULT_REPORT_SCOPE} — so read it through
    * `resolveReportScope` rather than reaching for `.scope` directly.
    */
   reporting?: { scope: ReportScope };
+  /**
+   * The credential boundary this project's sessions run behind (#125).
+   *
+   * Optional only on disk, and only for one release: a config written before
+   * this key existed is migrated to an explicit `{ isolation: "none" }` and
+   * rewritten, so the operator ends up with the answer in the file rather than
+   * inheriting a silent default. Never read directly — go through
+   * `resolveCredentials`, which is where that migration is spelled once.
+   */
+  credentials?: CredentialConfig;
   /** Parent directory for per-run worktrees. */
   workspaceRoot: string;
   /** Cache of bare clones, so N runs share one fetch instead of N. */
   mirrorRoot: string;
+  /**
+   * Extra roots an orchestrator session may *read*, on top of the state
+   * directory and its own briefs. Absolute (or `~`-expandable) paths only,
+   * rejected at load rather than resolved against a cwd nobody can name.
+   *
+   * It cannot widen the gate past the roots #127 exists to close: the denied
+   * list — every worker checkout, the mirror cache, this package's own
+   * install — outranks anything named here.
+   */
+  orchestratorReadPaths?: string[];
 }
 
 /**
@@ -244,6 +673,75 @@ export interface PrVerification {
   reason: string;
 }
 
+/**
+ * One file in a pull request's diff, in git's own terms rather than any
+ * tracker's. The settlement audit (#128) has to tell a deleted test file from a
+ * renamed one, and only the rename header says which — so `status` and
+ * `previousPath` are load-bearing, not decoration.
+ */
+export interface PrDiffFile {
+  path: string;
+  /** Pre-image path, set only for a rename. */
+  previousPath?: string;
+  status: "added" | "modified" | "removed" | "renamed";
+  /** The file's unified-diff hunks verbatim, absent for a binary, mode-only or
+   *  pure-rename change that has none. */
+  hunks?: string;
+}
+
+/** A pull request's diff, as the settlement audit reads it. */
+export interface PrDiff {
+  files: PrDiffFile[];
+  /** True when the adapter had to cut the diff short. The audit's silence is
+   *  then only silence about the part it saw, and it says so. */
+  truncated: boolean;
+}
+
+/**
+ * What the settlement audit can say about a worker's own account of its work.
+ *
+ * Declared as data for the same reason `REPORT_SCOPES` is: the analyser, the
+ * settlement report and the orchestrator brief all enumerate these, and a
+ * 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. */
+  "changed-line-missing",
+  /** `changed:` named a path the PR never touched. The weaker direction. */
+  "unmatched-claim",
+  /** 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. */
+  "test-disabled",
+  /** Assertions were commented out, or more left the file than entered it. */
+  "assertions-removed",
+  /** A named timeout in a test file went up. */
+  "test-timeout-raised",
+] as const;
+
+export type SettlementFlagKind = (typeof SETTLEMENT_FLAG_KINDS)[number];
+
+/**
+ * One advisory finding about a settled run. Advisory is the whole design: a
+ * flag never changes a run's state, because the judgement it invites — "was
+ * deleting that test correct?" — needs context the daemon does not have.
+ */
+export interface SettlementFlag {
+  kind: SettlementFlagKind;
+  /** Repo-relative path, or `(report)` for a finding about the report itself. */
+  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. */
+  line?: number;
+  detail: string;
+  /** True when the dispatching issue never names this file — the "tests you
+   *  didn't write" case, which is what makes a flag loud rather than routine. */
+  unattributed?: boolean;
+}
+
 /** Tracker lifecycle state for an issue. Undefined means the adapter could not tell. */
 export type IssueState = "open" | "closed";
 
@@ -327,6 +825,17 @@ export interface Tracker {
    * head, and has a non-empty terminal-success check rollup.
    */
   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.
+   *
+   * Undefined never means "nothing changed". Its only consumer is the
+   * settlement audit (#128), which is advisory, so a failure here costs one
+   * unaudited settlement and never a run's state. That is also why it does not
+   * retry: unlike {@link Tracker.verifyPr}, nothing downstream is waiting for a
+   * better answer on a later tick.
+   */
+  prDiff(url: string): Promise<PrDiff | undefined>;
 }
 
 /**
@@ -388,6 +897,11 @@ export interface RunRecord {
   endedAt?: number;
   /** Last failure text, surfaced verbatim in escalations. */
   lastError?: string;
+  /** Advisory settlement-audit findings for this attempt (#128). Deliberately
+   *  never consulted by anything that decides `state`: a flagged run settles
+   *  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[];
 }
 
 export type AdmissionHoldReason =
@@ -401,6 +915,12 @@ export type AdmissionHoldReason =
   | "open-pr"
   | "unsalvaged-wip"
   | "daily-spend-cap"
+  | "plan-usage-cap"
+  /** `credentials.isolation: "per-run"` on a host whose probe found no
+   *  mechanism. The operator asked for a boundary this host cannot build, so
+   *  dispatch refuses rather than running unprotected under a config that says
+   *  otherwise (#125). */
+  | "credential-boundary"
   | "unroutable:no-repo-label"
   | "unroutable:multiple-repo-labels"
   | "unroutable:unknown-repo";
@@ -464,6 +984,95 @@ export interface FrictionSignal {
 }
 
 
+/**
+ * What a report is *for*. Both reporting scopes promise exactly one `digest` a
+ * day; a `material` report is one event as it happens. The daemon puts both on
+ * the wire identically — the kind exists so the *ledger* can answer "has
+ * today's digest already been handed over?" without asking the model to
+ * remember, which is the memory #123 found unreliable.
+ *
+ * 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 type ReportKind = (typeof REPORT_KINDS)[number];
+
+/**
+ * Where one report is in the outbox. The two open states are deliberately
+ * distinct because they need different responses from an operator:
+ *
+ * - `pending` — nothing is in flight. Either nothing was ever attempted, or the
+ *   last attempt failed in a way Telegram told us about ({@link
+ *   ReportRecord.lastError} says which). Nobody has this report.
+ * - `sending` — a request left this process and its outcome was never learned:
+ *   the daemon died, or the fetch never came back. It may well have been
+ *   delivered. The Bot API accepts no client-supplied idempotency key, so there
+ *   is nothing to replay against and no bot-readable record to reconcile with —
+ *   delivery is therefore **at-least-once** and a retry may duplicate. A
+ *   duplicate page is acceptable; a silently dropped one is the whole of #123.
+ *
+ * `failed` is the bounded retry budget running out, and is itself news: a
+ * report nobody can deliver escalates as tier 2 in its own right.
+ */
+export const REPORT_DELIVERY_STATES = ["pending", "sending", "delivered", "failed"] as const;
+
+export type ReportDeliveryState = (typeof REPORT_DELIVERY_STATES)[number];
+
+/** One rendered report, and everything the daemon knows about delivering it. */
+export interface ReportRecord {
+  /** Short, stable, and printed inside the message itself. This transport
+   *  offers no reconciliation, so an id an operator can compare by eye is the
+   *  only way to recognise a duplicate as one. */
+  id: string;
+  project: string;
+  kind: ReportKind;
+  /** The model's rendered text, stored verbatim — authorship stays theirs. */
+  body: string;
+  state: ReportDeliveryState;
+  /** Attempts *started*, including one currently in flight. */
+  attempts: number;
+  /** Names the in-flight attempt. Every terminal transition quotes it, so a
+   *  request that returns after its row was reclaimed cannot overwrite a newer
+   *  attempt's outcome — this is what keeps one report from being concurrently
+   *  in flight twice. Absent whenever nothing is in flight. */
+  attemptId?: string;
+  /** True once an attempt's outcome was lost. From then on every message for
+   *  this report says it may be a repeat, because it may be. */
+  ambiguous: boolean;
+  /** At-most-one guard, e.g. `digest:2026-08-09`. Absent for material reports. */
+  dedupeKey?: string;
+  createdAt: number;
+  updatedAt: number;
+  /** Backoff gate: a `pending` row is due only once this has passed. */
+  nextAttemptAt: number;
+  /** Telegram's own id for the delivered message, read out of the response
+   *  body rather than inferred from the HTTP status. */
+  messageId?: number;
+  deliveredAt?: number;
+  /** Bounded text of the last known failure, surfaced verbatim by `status`. */
+  lastError?: string;
+}
+
+/** What a caller hands over. The store owns identity, state and every timestamp. */
+export interface ReportDraft {
+  project: string;
+  kind: ReportKind;
+  body: string;
+  dedupeKey?: string;
+  at: number;
+}
+
+/** Result of handing a report over. `deduped` is how the daily digest is
+ *  suppressed — decided from the ledger, never from the model's memory of the
+ *  last tick — and the caller is told which happened rather than left to guess
+ *  from a row it cannot tell apart from its own. */
+export interface ReportEnqueue {
+  report: ReportRecord;
+  deduped: boolean;
+}
+
 /**
  * Bookkeeping only — GitHub labels remain the source of truth. The store
  * exists to answer cap questions cheaply and to survive a restart; if it is
@@ -515,6 +1124,68 @@ export interface Store {
   /** Start the cooldown only after a tick carrying these signals was sent. */
   markFrictionSurfaced(project: string, kinds: readonly FrictionKind[], at: number): void;
   markNotified(key: string): void;
+  /**
+   * 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
+   * an absence. A draft whose `dedupeKey` is already in the ledger returns that
+   * row untouched and `deduped: true`, which is how the daily digest is
+   * suppressed without asking the model what it sent yesterday.
+   */
+  enqueueReport(draft: ReportDraft): ReportEnqueue;
+  getReport(id: string): ReportRecord | undefined;
+  /** `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
+   *  the row says a request is about to leave *before* one does. `undefined`
+   *  means somebody else claimed it first — the guard against the same report
+   *  being concurrently in flight twice. */
+  claimReport(id: string, attemptId: string, at: number): ReportRecord | undefined;
+  /** Record the message id Telegram returned, and the moment it did. */
+  markReportDelivered(id: string, attemptId: string, messageId: number | undefined, at: number): boolean;
+  /** The attempt ended without an answer: Telegram may hold the message. The
+   *  row *stays* `sending`, because that state means exactly "outcome unknown",
+   *  and is flagged {@link ReportRecord.ambiguous} so the retry that stale
+   *  recovery eventually hands back says it may be a repeat. Deliberately does
+   *  not touch `updatedAt`: the staleness clock started when the request left,
+   *  and restarting it here would make the daemon wait out a second window for
+   *  an attempt already known to be over. */
+  markReportUncertain(id: string, attemptId: string, error: string): boolean;
+  /** Known-failed: back to `pending` behind `nextAttemptAt`, attempt counted. */
+  markReportPending(id: string, attemptId: string, nextAttemptAt: number, error: string, at: number): boolean;
+  /** Retry budget exhausted. Terminal, and worth escalating in its own right. */
+  markReportFailed(id: string, attemptId: string, error: string, at: number): boolean;
+  /** `sending` rows untouched since `staleAt` — what a dead process left behind.
+   *  Returns them to `pending` flagged {@link ReportRecord.ambiguous}, so the
+   *  retry says it may be a repeat instead of pretending it is the first try. */
+  recoverSendingReports(project: string, staleAt: number, at: number): ReportRecord[];
+  /** Everything an operator still has to care about: pending, sending, failed. */
+  openReports(project: string): ReportRecord[];
+  /**
+   * Append one decided verb call to the run-scoped action ledger (#126).
+   * Written for refusals as well as approvals, and written *before* the
+   * privileged half runs is deliberately NOT the contract: the entry carries
+   * the resulting sha, so it is written once the outcome is known.
+   */
+  appendVerbLedger(draft: VerbLedgerDraft): VerbLedgerEntry;
+  /** Newest first. `runId` narrows to one run's own record. */
+  verbLedger(project: string, opts?: { runId?: string; issue?: number; limit?: number }): VerbLedgerEntry[];
+  /**
+   * Claim the project's single merge slot, or `undefined` when another holder
+   * has it. Locks older than `staleAfterMs` are broken first: a daemon killed
+   * mid-merge must not wedge the project forever, and the exact-head recheck
+   * makes a stolen lock safe — the second merge re-reads the live head anyway.
+   */
+  acquireMergeLock(
+    project: string,
+    holder: string,
+    prUrl: string,
+    now: number,
+    staleAfterMs: number,
+  ): MergeLock | undefined;
+  /** Release a lock this holder owns. A lock it does not own is left alone. */
+  releaseMergeLock(project: string, holder: string): void;
+  /** The live lock, for `status` and for tests. */
+  mergeLock(project: string): MergeLock | undefined;
   close(): void;
 }
 
@@ -544,8 +1215,174 @@ export interface Escalation {
 export const DEFAULT_CAPS: Caps = {
   maxConcurrentWorkers: 2,
   dailySpendUsd: 25,
+  // Off unless an operator names a window. A default threshold would need a
+  // default window id, and guessing which allowance a fleet lives on is how a
+  // guard silently watches the wrong meter (#110).
+  planUsage: null,
   workerMaxTurns: 120,
   workerWallClockMs: 90 * 60 * 1000,
   maxAttemptsPerIssue: 2,
   maxContinuationsPerIssue: 2,
 };
+
+/**
+ * The conductor-owned mutation verbs (#126). Data, for the reason every other
+ * vocabulary here is data: the daemon's dispatch table, the ledger renderer and
+ * the table-driven "every verb declares an allowed-caller set" test all
+ * enumerate this list, so a seventh verb cannot be added to one of them alone.
+ */
+export const VERB_NAMES = [
+  "conductor_push",
+  "conductor_pr_create",
+  "conductor_pr_update_branch",
+  "conductor_pr_merge",
+  "conductor_label",
+  "conductor_release",
+  /** The one read verb. A session with no credential cannot otherwise observe
+   *  the pull request it just pushed, and "pushed-green" would go back to being
+   *  a claim a worker makes about itself. */
+  "conductor_pr_status",
+] as const;
+
+export type VerbName = (typeof VERB_NAMES)[number];
+
+/**
+ * Field names a verb request may never carry.
+ *
+ * Identity is derived from *which socket the connection arrived on* plus the
+ * verified peer uid, so a payload that spells any of these is either a buggy
+ * client or one probing for a daemon that trusts them — `turnLimitResponse`
+ * trusting a body-supplied `project` on the unauthenticated HTTP port is the
+ * failure mode this list exists to keep off the socket. Refused outright and
+ * named in the refusal rather than ignored, because a client that is silently
+ * stripped keeps sending them and nobody ever learns.
+ */
+export const RESERVED_VERB_FIELDS = [
+  "project",
+  "run",
+  "runId",
+  "issue",
+  "role",
+  "uid",
+  "caller",
+] as const;
+
+export type ReservedVerbField = (typeof RESERVED_VERB_FIELDS)[number];
+
+/**
+ * Why a verb call ended the way it did. Closed, and matched by the ledger
+ * renderer and by tests: a refusal an operator cannot name is a refusal nobody
+ * can audit, and free-text reasons drift one wording per call site.
+ */
+export const VERB_REFUSALS = [
+  /** The socket's role is not in the verb's allowed-caller set. */
+  "role-not-allowed",
+  /** The caller's role is not the holder configured in `authority`. */
+  "authority-holder",
+  /** Claiming, ticks, or the fleet as a whole is stopped. */
+  "fleet-paused",
+  /** The run row this socket belongs to is no longer live. */
+  "run-not-live",
+  /** The request carried a {@link RESERVED_VERB_FIELDS} field. */
+  "identity-in-payload",
+  /** An argument this verb does not declare — closed by default, never ignored. */
+  "unknown-argument",
+  /** A declared argument was missing or the wrong type. */
+  "malformed-argument",
+  /** `reason` was not a member of the verb's closed enum (#129). */
+  "reason-not-in-enum",
+  /** A ref other than the run's own branch. */
+  "ref-not-run-branch",
+  /** The base branch is not the repo's configured `defaultBranch`. */
+  "base-not-default-branch",
+  /** An open pull request already closes this issue (#25's guard). */
+  "open-pr-exists",
+  /** The tracker could not say whether one does. Fail closed. */
+  "open-pr-lookup-error",
+  /** The named pull request is not this run's, or not this project's. */
+  "pr-not-this-run",
+  /** The run has no pull request to act on. */
+  "pr-missing",
+  /**
+   * The pull request is closed, merged, or its state could not be read.
+   * Distinct from {@link VERB_REFUSALS} `checks-not-green` on purpose: "you
+   * cannot update a merged PR" and "this PR is red" invite different next
+   * moves, and a ledger that spelled both the same way would lose that.
+   */
+  "pr-not-open",
+  /** `headSha` does not equal the live head at execution time. */
+  "head-stale",
+  /** The live head could not be read at all. Fail closed. */
+  "head-unresolvable",
+  /** Required checks are pending or red at the live head, or the PR is not open. */
+  "checks-not-green",
+  /** Another merge is in flight for this project. */
+  "merge-in-flight",
+  /** The label is not in this project's own vocabulary. */
+  "label-not-in-vocabulary",
+  /** The label is a lifecycle label; those transitions stay the daemon's (#26). */
+  "label-is-lifecycle",
+  /** The release grant does not permit this shape for this caller. */
+  "release-not-granted",
+  /** The artefact or environment is not one this project declared (#129). */
+  "release-target-not-declared",
+  /** A shape the daemon holds no credential for and will not pretend to cut. */
+  "release-shape-not-executable",
+  /** Config unreadable, project unknown, repo unrouted. Fail closed. */
+  "config-unreadable",
+  /** The privileged half ran and the underlying command failed. */
+  "action-failed",
+] as const;
+
+export type VerbRefusal = (typeof VERB_REFUSALS)[number];
+
+/** How a verb call was decided. `allowed` means the privileged half then ran. */
+export const VERB_DECISIONS = ["allowed", "refused"] as const;
+
+export type VerbDecision = (typeof VERB_DECISIONS)[number];
+
+/**
+ * One line of the run-scoped action ledger (#126): what was asked, by whom,
+ * what the daemon decided, and what came back.
+ *
+ * Written for refusals as well as approvals — a ledger that records only what
+ * happened cannot answer "what did it try", which is the question an escalation
+ * actually asks.
+ */
+export interface VerbLedgerEntry {
+  id: string;
+  project: string;
+  /** The run whose socket carried the call. Absent for the orchestrator's. */
+  runId?: string;
+  /** The issue that run is servicing, or the one a verb targeted. */
+  issue?: number;
+  verb: VerbName;
+  /** Resolved from the channel, never from the payload. */
+  role: SessionRole;
+  /** The arguments as received, redacted of nothing: this is the audit record. */
+  args: Record<string, unknown>;
+  decision: VerbDecision;
+  /** Present exactly when `decision` is `"refused"`. */
+  refusal?: VerbRefusal;
+  /** What the caller was told, verbatim. */
+  detail: string;
+  /** The commit, tag or merge sha the approved call produced, if any. */
+  sha?: string;
+  at: number;
+}
+
+/** What a caller hands the ledger. The store owns `id` and `at`. */
+export type VerbLedgerDraft = Omit<VerbLedgerEntry, "id" | "at">;
+
+/**
+ * The single-flight merge claim for one project, held in the store because the
+ * CLI, the daemon and every session are separate processes: an in-memory mutex
+ * would serialise one process against itself and nothing else (#126).
+ */
+export interface MergeLock {
+  project: string;
+  /** Opaque holder id — the run id, or the orchestrator channel's id. */
+  holder: string;
+  prUrl: string;
+  at: number;
+}