omp-conductor 0.18.2 → 0.19.1

package/src/worker.ts

@@ -108,10 +108,11 @@ function scheduleWallClock(callback: () => void, delayMs: number): () => void {
 
 /**
  * Which ceiling stopped a run. Only ever set alongside `state: "killed"`: the
- * turn counter caught a loop, or the wall clock caught a session that was stuck
- * without spending turns.
+ * turn counter caught a loop, the wall clock caught a session that was stuck
+ * without spending turns, or the run reached the spend allowance admission
+ * reserved for it (#851).
  */
-export type KilledBy = "turns" | "wallclock";
+export type KilledBy = "turns" | "wallclock" | "spend";
 
 export type WorkerPausePhase = "running" | "pausing" | "paused";
 
@@ -171,6 +172,149 @@ export function renderReviewRevisionPrompt(findings: string, round: number): str
   return `${REVIEW_REVISION_PROMPT}\n\nReview round ${round} — blocking findings:\n\n${findings}`;
 }
 
+
+/**
+ * What the review-ceiling adjudicator is told (#877).
+ *
+ * Deliberately NOT a continuation of anything. `REVIEW_REVISION_PROMPT` resumes
+ * the implementation session to change code; this opens a FRESH session, under a
+ * stronger model role, to make one decision about code it did not write. A
+ * relabelled resume of the same session and model is the named silent fake of
+ * #873: a fourth nominal opinion from the author is not an adjudication.
+ *
+ * So the contract is a verdict, not a diff: it may not push, may not edit, and
+ * ends by yielding `cleared` or `rejected` with reasons. One literal so a test
+ * can pin the exact handoff.
+ */
+export const REVIEW_ADJUDICATION_PROMPT =
+  "You are the final adjudicator for a pull request that has exhausted its review rounds. You did not write this " +
+  "code and you are not fixing it: your entire job is one decision. Read the acceptance criteria, the diff, the " +
+  "check state and every prior review finding below, then judge whether THIS head satisfies the issue. " +
+  "Do not edit files, do not push, do not open or close a pull request, and do not ask for another review round — " +
+  "there are none left. Finish by yielding your verdict: `cleared` if this head should merge as it stands, " +
+  "`rejected` if it should not, with the specific reasons that decided it. Judge the code in front of you, not the " +
+  "process that produced it.";
+
+/**
+ * The adjudicator's structured verdict (#877). Permissive like the worker
+ * settlement schema: an invalid or absent yield falls back to the text path
+ * rather than losing the decision, and the daemon settles the durable row from
+ * the parsed object when there is one.
+ */
+export const ADJUDICATION_VERDICT_SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  type: "object",
+  description:
+    "The adjudicator's terminal decision about one exact pull-request head. There is no third option and no " +
+    "further review round: `cleared` sends this head to the ordinary merge path, `rejected` sends it to the " +
+    "conductor's autonomous disposition.",
+  additionalProperties: false,
+  required: ["verdict", "reasons"],
+  properties: {
+    verdict: {
+      type: "string",
+      enum: ["cleared", "rejected"],
+      description: "cleared: this head should merge as it stands. rejected: it should not.",
+    },
+    reasons: {
+      type: "string",
+      description:
+        "Why, specifically: the criteria met or unmet, and the evidence in the diff or checks that decided it.",
+    },
+    headSha: {
+      type: "string",
+      description: "The 40-character head you judged — echoed back so a moved head is detectable.",
+    },
+  },
+} as const;
+
+/** One prior review round as the adjudicator must see it (#877): what was asked
+ *  for, and what became of it. A finding without its outcome reads as an
+ *  outstanding complaint even when the worker fixed it, which is how an
+ *  adjudicator rejects work that was already corrected. */
+export interface AdjudicationRound {
+  round: number;
+  findings: string;
+  /** The revision's settled outcome (`revised`, `failed`, `skipped`, …), or
+   *  absent for a round that never settled. */
+  outcome?: string;
+}
+
+/** Everything the adjudicator is given (#877). Assembled by the caller from
+ *  durable rows and live tracker reads, never from the worker's own claims. */
+export interface AdjudicationEvidence {
+  issue: number;
+  issueTitle?: string;
+  /** The issue body verbatim: the acceptance criteria are the standard being
+   *  judged, so they are never summarised. */
+  issueBody: string;
+  prUrl: string;
+  /** The exact head being judged. */
+  headSha: string;
+  /** The live check verdict at that head, as the tracker reported it. */
+  checks: string;
+  /** The PR's diff at that head. Bounded — see {@link renderAdjudicationBrief}. */
+  diff: string;
+  /** Every prior review round, oldest first. */
+  rounds: readonly AdjudicationRound[];
+  /** The review ceiling that was reached, so the adjudicator knows why it is
+   *  the last word rather than one more opinion. */
+  maxRounds: number;
+}
+
+/** How much of the diff one adjudication brief carries. A decision needs the
+ *  change, not every generated line: a bound keeps one enormous PR from
+ *  crowding out the findings and criteria that follow it, and the marker says
+ *  exactly what was withheld so the adjudicator can ask for it rather than
+ *  assuming it saw everything. */
+export const ADJUDICATION_DIFF_LIMIT = 60_000;
+
+/**
+ * The full opening prompt for one adjudication: the pinned contract plus the
+ * bounded evidence, in the order a decision needs it — what was asked for, what
+ * is on the head now, what previous reviews said, and what happened to it.
+ *
+ * Exported so a test can pin the exact payload without standing up a session,
+ * which is #877's requirement: the brief is the deliverable here, and a test
+ * that only asserts a stored flag would pass on an empty one.
+ */
+export function renderAdjudicationBrief(evidence: AdjudicationEvidence): string {
+  const rounds =
+    evidence.rounds.length === 0
+      ? ["(none recorded — this adjudication was admitted without prior rounds)"]
+      : evidence.rounds.map(
+          (round) =>
+            `Round ${round.round} (${round.outcome ?? "never settled"}):\n${round.findings.trim()}`,
+        );
+  const diff =
+    evidence.diff.length <= ADJUDICATION_DIFF_LIMIT
+      ? evidence.diff
+      : `${evidence.diff.slice(0, ADJUDICATION_DIFF_LIMIT)}\n` +
+        `[diff truncated at ${ADJUDICATION_DIFF_LIMIT} of ${evidence.diff.length} characters — ` +
+        "read the remainder from the pull request if the decision turns on it]";
+  return [
+    REVIEW_ADJUDICATION_PROMPT,
+    "",
+    `Issue #${evidence.issue}${evidence.issueTitle === undefined ? "" : `: ${evidence.issueTitle}`}`,
+    `Pull request: ${evidence.prUrl}`,
+    `Head under adjudication: ${evidence.headSha}`,
+    `Checks at that head: ${evidence.checks}`,
+    `Review rounds exhausted: ${evidence.rounds.length} of ${evidence.maxRounds} allowed`,
+    "",
+    "## Acceptance criteria (the issue, verbatim)",
+    "",
+    evidence.issueBody.trim(),
+    "",
+    "## Prior review findings, and what became of them",
+    "",
+    rounds.join("\n\n"),
+    "",
+    "## The diff at this head",
+    "",
+    diff,
+  ].join("\n");
+}
+
 export interface WorkerOpts {
   brief: string;
   cwd: string;
@@ -217,6 +361,15 @@ export interface WorkerOpts {
   onReleaseBlocked?: (shape: GateShape, context: ReleaseBlockContext) => void;
   /** The child's pid, the instant it exists. See {@link VerbListener.bindPid}. */
   onSpawn?: (pid: number) => void;
+  /**
+   * The worker's Herdr representation (#840): opened from the exact child pid,
+   * released when that child is gone.
+   *
+   * Passed straight through to `createSession`, and deliberately not built here
+   * — a worker run knows its issue and attempt, but which workspace a pane
+   * belongs in, and whether one should exist at all, is the daemon's to decide.
+   */
+  pane?: { open(pid: number): void; release(): void };
   /** Control socket for that child, beside the run's own session directory. */
   socketPath?: string;
   /**
@@ -232,11 +385,27 @@ export interface WorkerOpts {
    * startup cap remains fixed for the run.
    */
   maxTurns?: () => number;
+  /**
+   * Estimated-USD ceiling for this session, from the allowance admission
+   * reserved for the run (#851). Checked as each cost-bearing message lands,
+   * because that is the only moment a response's cost is known — so the
+   * declared overshoot is exactly one completed model response, never zero.
+   * Omitted means the fleet has no spend cap and nothing to enforce.
+   */
+  maxSpendUsd?: number;
   /** Synchronous cap latch; called before the session abort begins. */
   onKilled?: (by: KilledBy) => void;
   onTurn?: (n: number) => void;
   /** Cumulative USD spend, reported as each cost-bearing message finishes. */
   onSpend?: (usd: number) => void;
+  /**
+   * Cumulative output and reasoning tokens for this run (#518).
+   *
+   * Reported alongside the spend it is derived from, so a reader can tell a run
+   * deliberating expensively in wall clock but cheaply in dollars from one that
+   * is idle or stuck — the difference that decides whether to intervene.
+   */
+  onTokens?: (tokens: { output: number; reasoning: number }) => void;
   /**
    * The transcript path, handed over the moment the session opens it rather
    * than at the end with {@link WorkerResult.sessionFile}. Both report the same
@@ -461,6 +630,183 @@ export function structuredSettlement(content: unknown): WorkerSettlement | undef
   return parsed;
 }
 
+/**
+ * The adjudicator's parsed verdict (#877), or `undefined` when it yielded
+ * nothing usable.
+ *
+ * Same shape of parse as {@link structuredSettlement}, and separate from it on
+ * purpose: an adjudication is a decision, not a settlement, and letting the two
+ * share a parser would let a worker-shaped yield read as a verdict.
+ */
+export function structuredVerdict(content: unknown): AdjudicationVerdict | undefined {
+  if (!Array.isArray(content)) return undefined;
+  let parsed: AdjudicationVerdict | undefined;
+  for (const block of content) {
+    if (field(block, "type") !== "toolCall") continue;
+    if (field(block, "name") !== "yield") continue;
+    const args = field(block, "arguments");
+    if (args === null || typeof args !== "object") continue;
+    const result = field(args, "result");
+    if (result === null || typeof result !== "object") continue;
+    const data = field(result, "data");
+    if (data === null || typeof data !== "object" || Array.isArray(data)) continue;
+    const record = data as Record<string, unknown>;
+    const verdict = record.verdict;
+    if (verdict !== "cleared" && verdict !== "rejected") continue;
+    const reasons = record.reasons;
+    if (typeof reasons !== "string" || reasons.trim() === "") continue;
+    const decided: AdjudicationVerdict = { verdict, reasons };
+    const headSha = record.headSha;
+    if (typeof headSha === "string" && headSha !== "") decided.headSha = headSha;
+    parsed = decided;
+  }
+  return parsed;
+}
+
+/** One adjudicator's decision as the daemon receives it (#877). */
+export interface AdjudicationVerdict {
+  verdict: "cleared" | "rejected";
+  reasons: string;
+  /** The head the adjudicator says it judged, when it echoed one back. The
+   *  daemon compares it against the head it dispatched: a mismatch is a
+   *  stale-head settle, never a merge. */
+  headSha?: string;
+}
+
+/** What one adjudication run produced (#877). */
+export interface AdjudicationResult {
+  /** The parsed verdict, absent when the session ended without yielding one —
+   *  which settles the durable row `failed`, never `cleared`. */
+  verdict?: AdjudicationVerdict;
+  /** The session's last words, kept whether or not a verdict parsed: for a
+   *  failed adjudication this text IS the evidence. */
+  report: string;
+  /** What actually ran it, for the durable provenance (#875). */
+  model?: string;
+  provider?: string;
+  turns: number;
+  spendUsd: number;
+}
+
+export interface AdjudicatorOpts {
+  /** The rendered brief from {@link renderAdjudicationBrief}. */
+  brief: string;
+  /** A directory the session may read: everything it needs is in the brief, so
+   *  this is deliberately not a run worktree — an adjudicator has no branch. */
+  cwd: string;
+  /** The model pattern the configured adjudicator role resolved to, in omp's
+   *  model/role syntax. Omitted leaves the harness to choose, which is what an
+   *  unconfigured project gets. */
+  model?: string;
+  sessionDir?: string;
+  ompSettingsFile?: string;
+  socketPath?: string;
+  onSpawn?: (pid: number) => void;
+  onChildLog?: (line: string) => void;
+  maySpawn?: () => boolean;
+  /** Hard turn ceiling for the decision. A verdict is one read and one answer;
+   *  a session still going after this is not deciding. */
+  maxTurns: number;
+}
+
+/**
+ * Run one bounded adjudication (#877).
+ *
+ * A FRESH session under the configured role — never a resume of the
+ * implementation worker, which is the whole point of escalating at the ceiling:
+ * a fourth opinion from the same session and model is not an adjudication.
+ *
+ * Read-only by construction, and that is enforced by what is NOT passed:
+ * no `verbSocketPath`, so the conductor mutation verbs (`conductor_push`,
+ * `conductor_pr_create`, everything downstream) are unreachable from this
+ * session — it cannot push, open, close or merge anything. No release grants
+ * either. Its only output is the verdict it yields.
+ */
+export async function runAdjudicator(
+  o: AdjudicatorOpts,
+  deps: RunWorkerDeps = { createSession },
+): Promise<AdjudicationResult> {
+  let session: AgentSessionLike;
+  try {
+    session = await deps.createSession({
+      cwd: o.cwd,
+      ...(o.sessionDir === undefined ? {} : { sessionDir: o.sessionDir }),
+      ...(o.model === undefined ? {} : { model: o.model }),
+      ...(o.ompSettingsFile === undefined ? {} : { ompSettingsFile: o.ompSettingsFile }),
+      ...(o.socketPath === undefined ? {} : { socketPath: o.socketPath }),
+      ...(o.onSpawn === undefined ? {} : { onSpawn: o.onSpawn }),
+      ...(o.onChildLog === undefined ? {} : { onChildLog: o.onChildLog }),
+      ...(o.maySpawn === undefined ? {} : { maySpawn: o.maySpawn }),
+      // Worker role: structured file tools stay inside `cwd` and no release
+      // grant can reach this session. Deliberately no `verbSocketPath` — see
+      // the doc comment: an adjudicator decides, it never mutates.
+      role: "worker",
+      outputSchema: ADJUDICATION_VERDICT_SCHEMA,
+      outputSchemaMode: "permissive",
+      requireYieldTool: true,
+    });
+  } catch (err) {
+    // The pre-spawn admission gate closed, or the harness could not start. Both
+    // are "no verdict", and the caller settles the durable row accordingly —
+    // never as a clear.
+    return {
+      report: err instanceof Error ? err.message : String(err),
+      turns: 0,
+      spendUsd: 0,
+    };
+  }
+
+  let turns = 0;
+  let spendUsd = 0;
+  let report = "";
+  let verdict: AdjudicationVerdict | undefined;
+  let model: string | undefined;
+  let provider: string | undefined;
+  const finished = Promise.withResolvers<void>();
+  session.on("turn_start", () => {
+    turns += 1;
+    if (turns > o.maxTurns) session.abort();
+  });
+  session.on("message_end", (event) => {
+    const message = field(event, "message");
+    if (field(message, "role") !== "assistant") return;
+    const content = field(message, "content");
+    const parsed = structuredVerdict(content);
+    if (parsed !== undefined) verdict = parsed;
+    const text = reportText(content);
+    if (text !== "") report = text;
+    const usage = field(message, "usage");
+    const cost = usage === null ? null : field(usage, "cost");
+    const total = cost === null ? null : field(cost, "total");
+    if (typeof total === "number") spendUsd += total;
+    const messageModel = field(message, "model");
+    if (typeof messageModel === "string" && messageModel !== "") model = messageModel;
+    const messageProvider = field(message, "provider");
+    if (typeof messageProvider === "string" && messageProvider !== "") provider = messageProvider;
+  });
+  session.on("agent_end", (event) => {
+    // Same rule as the worker path: a non-terminal `agent_end` means the
+    // harness will resume the session, so completing there would read a
+    // mid-flight snapshot as the verdict.
+    if (shouldComplete(event as { isTerminal?: boolean })) finished.resolve();
+  });
+  session.on("session_exit", () => finished.resolve());
+  try {
+    await session.prompt(o.brief);
+    await finished.promise;
+  } finally {
+    await disposeSession(session);
+  }
+  return {
+    ...(verdict === undefined ? {} : { verdict }),
+    report,
+    ...(model === undefined ? {} : { model }),
+    ...(provider === undefined ? {} : { provider }),
+    turns,
+    spendUsd,
+  };
+}
+
 /**
  * Render a parsed {@link WorkerSettlement} as the run's stored report (#540).
  *
@@ -560,6 +906,7 @@ export async function runWorker(
       ...(o.releaseGrants === undefined ? {} : { releaseGrants: o.releaseGrants }),
       ...(o.onReleaseBlocked === undefined ? {} : { onReleaseBlocked: o.onReleaseBlocked }),
       ...(o.onSpawn === undefined ? {} : { onSpawn: o.onSpawn }),
+      ...(o.pane === undefined ? {} : { pane: o.pane }),
       ...(o.socketPath === undefined ? {} : { socketPath: o.socketPath }),
       ...(o.verbSocketPath === undefined ? {} : { verbSocketPath: o.verbSocketPath }),
       ...(o.onChildLog === undefined ? {} : { onChildLog: o.onChildLog }),
@@ -663,6 +1010,11 @@ export async function runWorker(
 
   let turns = 0;
   let spendUsd = 0;
+  // Cumulative output/reasoning tokens (#518), beside the spend they are read
+  // from: the share of one against the other is what makes an expensive-in-time,
+  // cheap-in-dollars run legible instead of looking barely started.
+  let outputTokens = 0;
+  let reasoningTokens = 0;
   let provider429Count = 0;
   let report = "";
   // The newest structured settlement the worker yielded (#540). A terminal
@@ -846,10 +1198,27 @@ export async function runWorker(
     // Real cost lives on assistant messages as `usage.cost.total` (live hermes
     // transcripts, 2026-08-07). The earlier agent_end.telemetry path never
     // fired, so every run recorded $0 and the daily cap was theater (#46).
+    // Tokens ride the same usage block as the cost, so this is one read of a
+    // field already in the transcript (#518) — no new call, no polling.
+    const tokens = outputTokensFromMessage(message);
+    if (tokens !== undefined) {
+      outputTokens += tokens.output;
+      reasoningTokens += tokens.reasoning;
+      o.onTokens?.({ output: outputTokens, reasoning: reasoningTokens });
+    }
+
     const cost = costUsdFromMessage(message);
     if (cost !== undefined) {
       spendUsd += cost;
       o.onSpend?.(spendUsd);
+      // The live half of the spend bound (#851). The daily cap alone stopped
+      // the fleet on the NEXT dispatch pass, so one run could cross it by its
+      // whole cost before anything objected — on 2026-08-21 a single run spent
+      // an estimated $25.16 against a $25.00 daily cap unopposed. A run that
+      // reaches the allowance reserved for it is killed here, through the same
+      // latch the turn and wall-clock ceilings use, so it settles through the
+      // ordinary salvage path with its work preserved.
+      if (o.maxSpendUsd !== undefined && spendUsd >= o.maxSpendUsd) kill("spend");
     }
 
     // Count the provider rate limits the harness retried in-session (#573). A
@@ -1059,6 +1428,37 @@ export function costUsdFromMessage(message: unknown): number | undefined {
   return any ? sum : undefined;
 }
 
+/**
+ * Output and reasoning token counts from one assistant message (#518).
+ *
+ * Both come off the same `usage` block the cost is already read from, so this
+ * adds no provider call and no polling — it reads a field the transcript
+ * already carries. Absent or unparseable counts return `undefined` rather than
+ * zero, because "this provider reported no tokens" and "this turn produced no
+ * output" invite opposite readings, and a zero would make the share arithmetic
+ * quietly wrong.
+ *
+ * `reasoning` is counted as part of `output` by every provider that reports it,
+ * which is what makes the share meaningful: 96% reasoning on run 42f73f52 was
+ * the whole answer to "why has this been working 42 minutes for $0.05", and it
+ * was recorded and unshown.
+ */
+export function outputTokensFromMessage(
+  message: unknown,
+): { output: number; reasoning: number } | undefined {
+  const tokens = field(field(message, "usage"), "tokens");
+  if (tokens === null || typeof tokens !== "object") return undefined;
+  const count = (key: string): number | undefined => {
+    const v = field(tokens, key);
+    return typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : undefined;
+  };
+  const output = count("output");
+  if (output === undefined) return undefined;
+  // A provider that reports no reasoning is reporting zero reasoning, which is
+  // a true share of 0% — distinct from an absent output count above.
+  return { output, reasoning: count("reasoning") ?? 0 };
+}
+
 /**
  * Is this assistant message a provider HTTP 429 the harness recorded mid-run?
  *