omp-conductor 0.20.0 → 0.20.2

package/src/types.ts

@@ -90,6 +90,12 @@ export interface Caps {
   /** Wall-clock ceiling for one worker (90 min): a session that is merely
    *  stuck spends no turns, so turns alone cannot detect it. */
   workerWallClockMs: number;
+  /** How long a live worker's transcript may stay unwritten before the
+   *  daemon settles it as a progress stall (#1086). `null` derives it from the
+   *  wall-clock ceiling — one third, so a hung run is caught long before its
+   *  clock runs out. A single turn can legitimately run for minutes on a slow
+   *  provider, so this reads *transcript writes*, never the turn counter. */
+  workerStallSilenceMs: number | null;
   /** Failed implementation/CI attempts allowed before escalation. Operational
    *  continuations do not consume this budget. */
   maxAttemptsPerIssue: number;
@@ -1797,6 +1803,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",
@@ -1823,6 +1837,13 @@ export const FAILURE_CLASSES = [
    *  2026-08-23 failures were this, at 100/180 and 54/180 turns, while a third
    *  run on the same model finished green in the same window. */
   "model-empty-stop",
+  /** A live session stopped writing its transcript for longer than the
+   *  configured silence window, and the daemon settled it (#1086). Not a size
+   *  verdict: the work did not run out of budget, the session simply never
+   *  came back — the evidence names how long it was silent and at which turn.
+   *  When the attempt had already pushed a green PR, the settle path lands the
+   *  row `pushed-green` instead, so landed work is never charged anything. */
+  "progress-stall",
   "unknown",
 ] as const;
 
@@ -1831,21 +1852,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).
  */
@@ -1855,6 +1882,7 @@ export const RECOVERY_ACTIONS = [
   "rerun-checks",
   "settle",
   "escalate",
+  "observe",
   "hold",
   "none",
 ] as const;
@@ -2116,6 +2144,14 @@ export interface RunRecord {
   autoCompactionCount?: number;
   /** omp session transcript, so a human can read what the worker actually did. */
   sessionFile?: string;
+  /**
+   * When the run's transcript was last observed to grow, as epoch ms (#1086).
+   * Recorded by the daemon's progress watch from the file's own mtime — the
+   * write instant, not the observation instant — and read by `status` to show
+   * a silence interval while the row is live. Absent means the pass has not
+   * looked at this run (or it has no transcript yet), never "no progress".
+   */
+  lastProgressAt?: number;
   /**
    * The exact `session-host` pid this run's Herdr representation was reported
    * for, and the pane Herdr knows it as (#842).
@@ -3357,6 +3393,11 @@ export interface Store {
    * predicate pick the window. Read-only.
    */
   recentSpendSamples(project: string, limit: number): { turns: number; spendUsd: number }[];
+  /** The newest runs carrying a usable per-turn latency (#1063): terminal
+   *  rows with turns and elapsed time recorded, newest first. Bounded by
+   *  `limit` rows like `recentSpendSamples` — the caller over-samples and lets
+   *  its own model-attribution filter pick the window. Read-only. */
+  recentLatencySamples(project: string, limit: number): RunRecord[];
   /** Total tracked `gh` calls between two UTC day keys, inclusive (#198). */
   ghCallsBetween(sinceDay: string, untilDay: string): number;
   /** Idempotence guard so a retry loop cannot page a human repeatedly for the
@@ -4019,6 +4060,11 @@ export const DEFAULT_CAPS: Caps = {
   workerMaxTurns: 120,
   workerMaxTurnsCeiling: 240,
   workerWallClockMs: 90 * 60 * 1000,
+  // Derived as a third of the wall-clock ceiling unless an operator names the
+  // window: a hung run is caught with most of its budget unspent, while a
+  // slow-but-writing session (measured fleet latency has reached
+  // 1.5 min/turn) never trips it (#1086).
+  workerStallSilenceMs: null,
   maxAttemptsPerIssue: 2,
   maxContinuationsPerIssue: 2,
 };

package/src/verbs/server.ts

@@ -426,7 +426,8 @@ export function releaseRequirementRefusal(
       const drain =
         ". Settle the fleet with a bounded drain: " +
         `omp-conductor drain start${facts.project === undefined ? "" : ` --project ${facts.project}`} --until <deadline>` +
-        " — claiming pauses while settlement runs, and admission resumes at the deadline on its own.";
+        " — claiming pauses until the deadline even once the fleet goes quiet (an emptied fleet opens" +
+        " the window rather than ending the drain early), and admission resumes at the deadline on its own.";
       return (
         `policy.release.requires includes ${requirement} and ${facts.unsettledRuns} run(s) have not settled` +
         (parts.length === 0 ? "" : ` — ${parts.join("; ")}`) +
@@ -2292,22 +2293,25 @@ async function prUpdateVerb(
  */
 
 /**
- * The run states a review revision may start from (#795).
+ * The run states a review revision may start from (#795, #1101).
  *
  * A revision round resumes the exact run whose row owns the PR, so the
- * revisable states are exactly the terminal runs that pushed one: a settled
- * `pushed-green` row, or a `failed` / `killed` row — a run that capped or
- * failed *after* pushing a green PR. The PR is the durable artefact, the
- * exact-head green verification in the verb is the gate on "green at the
- * reviewed SHA", and a terminal row proves no worker is in flight, so the
- * findings are returned without the close-PR → unblock → continuation dance.
+ * revisable states are exactly the terminal runs that own the named PR: a
+ * settled `pushed-green` row, a `failed` / `killed` row — a run that capped or
+ * failed *after* pushing a green PR — and, since #1101, a `stopped` row that
+ * had already pushed when the operator stopped it. Ownership is proved by the
+ * selection itself (`runsForProjectPr` matches rows that recorded the PR), so
+ * a stopped run that never pushed can never reach this gate. Without the
+ * stopped leg a stopped-with-green-PR run was both unreviewable (this verb)
+ * and unreplaceable (the open-PR dispatch guard) at once — closing the PR by
+ * hand was the only exit, which is exactly what #1096 hit.
  *
  * Closed on purpose: a live row (`running` / `claimed`) is already doing its
  * own work, a `pushed-pending` PR is not green yet, and a `blocked` /
- * `orphaned` / `stopped` / `merged` row is not work returned for revision.
- * The set itself is the shared `REVISABLE_RUN_STATES` in `decisions.ts` —
- * the one definition the review verb and the `pr-review-ready` watch gate on,
- * so the two can never drift (#844).
+ * `orphaned` / `merged` row is not work returned for revision. The set itself
+ * is the shared `REVISABLE_RUN_STATES` in `decisions.ts` — the one definition
+ * the review verb and the `pr-review-ready` watch gate on, so the two can
+ * never drift (#844).
  */
 
 async function prReviewVerb(

package/src/worker.ts

@@ -15,7 +15,7 @@ import { join } from "node:path";
 import { knowledgeSection } from "./knowledge.ts";
 import { createSession, disposeSession, SessionAdmissionClosedError, type AgentSessionLike } from "./omp.ts";
 import type { GateShape, ReleaseBlockContext } from "./release-policy.ts";
-import { TO_SPEC_SCHEMA } from "./to-spec.ts";
+import { gateToSpecPayload, TO_SPEC_SCHEMA, type ToSpecFailure } from "./to-spec.ts";
 import type { Caps, GraphToolsObservation, ResolvedGrants, RunState } from "./types.ts";
 
 /** Structured evidence fields from the worker's final report. */
@@ -1057,7 +1057,18 @@ export async function runAdjudicator(
 }
 
 /**
- * The turn ceiling for one to-spec grooming scout (#1041).
+ * The highest turn count any to-spec pass that finished used, measured across
+ * both projects' grooming ledger on 2026-08-25 (#1064): of the fourteen
+ * groom sessions ever run, the eight that finished verdicts used 10–19 turns
+ * (BLOCKED ×6, PROMOTABLE ×1, NEEDS DECOMPOSITION ×1), while every session
+ * killed at the ceiling was 21+ turns in when the abort fired. The ceiling
+ * and its measurement live here, in one place: the ceiling is the measured
+ * max plus one turn of headroom.
+ */
+const TO_SPEC_MEASURED_FINISHED_MAX_TURNS = 19;
+
+/**
+ * The turn ceiling for one to-spec grooming scout (#1041, #1064).
  *
  * Half the adjudicator's 40, and for the opposite reason: an adjudication is
  * handed its whole evidence in the brief (issue, diff, checks, every prior
@@ -1065,28 +1076,48 @@ export async function runAdjudicator(
  * and must go and READ — the source repo at a ref, the entry points, the
  * existing tests, the later work that may have retired the premise. That is
  * search, and search is where a session bounded only by a worker's budget
- * quietly spends a worker's budget. Twenty read/answer turns is enough for a
- * bounded repo walk plus the structured answer; a scout still going after
- * them has stopped grooming one candidate and started exploring the
- * repository, which is exactly the cost the mechanical selection bounds
- * everywhere else.
+ * quietly spends a worker's budget. One turn above the highest measured
+ * finishing pass is enough for a bounded repo walk plus the structured
+ * answer; a scout still going after them has stopped grooming one candidate
+ * and started exploring the repository, which is exactly the cost the
+ * mechanical selection bounds everywhere else.
  */
-export const TO_SPEC_MAX_TURNS = 20;
+export const TO_SPEC_MAX_TURNS = TO_SPEC_MEASURED_FINISHED_MAX_TURNS + 1;
 
 /** What one to-spec scout produced (#1041). */
 export interface ToSpecScoutResult {
   /**
    * The agent's answer, verbatim and unjudged — the structured payload it
-   * yielded, serialized, or its own last text when it yielded nothing. This
-   * string is `recordToSpecGrooming`'s `input`, and nothing here reads a field
-   * of it: conductor re-validates every result through the strict parser at
-   * persistence time, so a runner that pre-parsed would be a second, weaker
-   * contract. Empty when the session produced neither.
+   * yielded (through the repair round when the first answer failed), or a
+   * fully conforming block recovered from its own text when it never yielded
+   * (#1064). This string is `recordToSpecGrooming`'s `input`, and nothing
+   * here reads a field of it beyond what the repair round must probe:
+   * conductor re-validates every result through the strict parser at
+   * persistence time, so a runner that judged would be a second, weaker
+   * contract. Empty when the session produced no answer at all — the
+   * narration stays in `report`, and the pass records `no-answer`.
    */
   raw: string;
   /** The session's last words, kept whether or not it answered: for a scout
-   *  that produced nothing this text IS the evidence of what went wrong. */
+   *  that produced nothing this text IS the evidence of what went wrong, and
+   *  it is recorded as the refusal's context — never parsed as a verdict
+   *  (#1064). */
   report: string;
+  /**
+   * How `raw` arrived (#1064): through the `yield` tool, or recovered from
+   * the session's text because it never yielded (`"text"` is the record's own
+   * admission that the answer did not come through the contract), or `"none"`
+   * when the pass produced no answer at all. Absent on results written before
+   * #1064; callers read a non-empty `raw` as a yield then.
+   */
+  via?: "yield" | "text" | "none";
+  /** Whether the one bounded repair round produced the carried answer
+   *  (#1064): the first answer parsed but violated the contract, the
+   *  validation error was handed back, and this raw is the re-answer. */
+  repaired?: boolean;
+  /** Whether the turn ceiling aborted the session before it finished — the
+   *  cap-kill shape of the no-answer class (#1064). */
+  killedAtCeiling?: boolean;
   /** What actually ran it, for the durable provenance (#875). */
   model?: string;
   provider?: string;
@@ -1115,7 +1146,7 @@ export interface ToSpecScoutOpts {
 }
 
 /**
- * Run one bounded to-spec grooming pass (#1041).
+ * Run one bounded to-spec grooming pass (#1041, #1064).
  *
  * The adjudicator's twin, and read-only by the same construction: no
  * `verbSocketPath`, so no conductor mutation verb — no label change, no
@@ -1124,14 +1155,31 @@ export interface ToSpecScoutOpts {
  * the scout cannot queue the candidate it is grooming, only describe it. The
  * queue label is added later, by the daemon, and only through the ready gate.
  *
- * Two deliberate differences from {@link runAdjudicator}. It carries
+ * Deliberate differences from {@link runAdjudicator}. It carries
  * {@link TO_SPEC_SCHEMA} with `outputSchemaMode: "strict"` — the to-spec
  * contract has always been invoked strictly (#772), and a permissive schema
  * would let a half-filled result through the harness only for the parser to
  * refuse it as malformed one layer later, spending the batch to learn nothing.
- * And it returns the answer UNPARSED: `recordToSpecGrooming` is the single
- * persistence path and the only validator, so a second decode here would be
- * a second contract to keep in sync.
+ * And the answer is carried UNJUDGED: `recordToSpecGrooming` is the single
+ * persistence path and the only validator. The one exception is the repair
+ * round (#1064): a payload that parses but violates the contract is probed
+ * with the same collector parser (`gateToSpecPayload`), the validation error
+ * is prompted back into the session, and the re-answer is carried instead —
+ * a complete, source-verified verdict must not be discarded over a key name.
+ * A probe that refuses a payload is stale narration, never a verdict.
+ *
+ * What comes back goes beyond a plain string:
+ *
+ *  - `raw` is ONLY the structured answer — the yield payload, or a fully
+ *    conforming block recovered from the session's text when it never
+ *    yielded. The runner never substitutes narration for the answer, so a
+ *    session that produced no payload returns `raw: ""` and the pass records
+ *    `no-answer` rather than grading prose as JSON.
+ *  - `via` says how the answer arrived; a text-recovery carries `"text"` so
+ *    the durable record admits the answer did not come through the yield
+ *    contract even though its verdict may be used.
+ *  - `killedAtCeiling` names the turn-ceiling kill, which is what makes the
+ *    no-answer shape legible instead of a silent failure.
  */
 export async function runToSpecScout(
   o: ToSpecScoutOpts,
@@ -1162,6 +1210,7 @@ export async function runToSpecScout(
     return {
       raw: "",
       report: err instanceof Error ? err.message : String(err),
+      via: "none",
       turns: 0,
       spendUsd: 0,
     };
@@ -1173,10 +1222,16 @@ export async function runToSpecScout(
   let yielded = "";
   let model: string | undefined;
   let provider: string | undefined;
-  const finished = Promise.withResolvers<void>();
+  let killedAtCeiling = false;
+  // Re-armed for the repair round: the completion resolvers serve one prompt
+  // at a time, and the repair prompt completes its own (turn-bounded) window.
+  let finished = Promise.withResolvers<void>();
   session.on("turn_start", () => {
     turns += 1;
-    if (turns > o.maxTurns) session.abort();
+    if (turns > o.maxTurns) {
+      killedAtCeiling = true;
+      session.abort();
+    }
   });
   session.on("message_end", (event) => {
     const message = field(event, "message");
@@ -1202,26 +1257,85 @@ export async function runToSpecScout(
     if (shouldComplete(event as { isTerminal?: boolean })) finished.resolve();
   });
   session.on("session_exit", () => finished.resolve());
+
+  /**
+   * What the session produced after one prompt, and whether that answer is a
+   * single re-answer away from the contract (#1064). The newest yield wins
+   * and is carried unjudged; without a yield, a fully conforming fenced block
+   * from the text is carried as the answer (marked `via: "text"`), a
+   * repairable block is NOT carried but its failure is reported so the repair
+   * round can run, and prose is never carried — narration is context, not an
+   * answer.
+   */
+  const inspect = (): {
+    payload: string;
+    via: "yield" | "text" | "none";
+    failure: ToSpecFailure | undefined;
+  } => {
+    if (yielded !== "") {
+      const gate = gateToSpecPayload(yielded);
+      return {
+        payload: yielded,
+        via: "yield",
+        failure: gate.state === "repairable" ? gate.failure : undefined,
+      };
+    }
+    const gate = gateToSpecPayload(report);
+    if (gate.state === "conforming") return { payload: gate.body, via: "text", failure: undefined };
+    if (gate.state === "repairable") return { payload: "", via: "none", failure: gate.failure };
+    return { payload: "", via: "none", failure: undefined };
+  };
+
+  let repaired = false;
   try {
     await session.prompt(o.brief);
     await finished.promise;
+    let answer = inspect();
+    // One bounded repair round (#1064): a payload that parsed but violated
+    // the contract is handed back once with the validation error before any
+    // refusal is persisted. The same turn ceiling still bounds the session —
+    // a cap kill means the session is gone and there is nothing to prompt.
+    if (answer.failure !== undefined && !killedAtCeiling) {
+      repaired = true;
+      finished = Promise.withResolvers<void>();
+      try {
+        await session.prompt(toSpecRepairPrompt(answer.failure.detail));
+        await finished.promise;
+        answer = inspect();
+      } catch {
+        // The session could not take a repair prompt (it had already
+        // exited). Whatever the first round produced stands, unjudged; the
+        // persistence layer refuses it, with the payload kept in the row.
+      }
+    }
+    return {
+      raw: answer.payload,
+      report,
+      via: answer.via,
+      ...(repaired ? { repaired: true } : {}),
+      ...(killedAtCeiling ? { killedAtCeiling: true } : {}),
+      ...(model === undefined ? {} : { model }),
+      ...(provider === undefined ? {} : { provider }),
+      turns,
+      spendUsd,
+    };
   } finally {
     await disposeSession(session);
   }
-  return {
-    // The yielded payload first: under `requireYieldTool` that IS the answer,
-    // and a scout's prose is usually a sentence about it rather than the
-    // contract. The text stands in when nothing was yielded, so a session
-    // that answered in a fenced JSON block still persists as a verdict and
-    // one that only chatted persists as `blocked(malformed)` — which is the
-    // honest record of a spent pass, not a discard.
-    raw: yielded !== "" ? yielded : report,
-    report,
-    ...(model === undefined ? {} : { model }),
-    ...(provider === undefined ? {} : { provider }),
-    turns,
-    spendUsd,
-  };
+}
+
+/**
+ * The one repair round's prompt (#1064): what failed and which field, plus
+ * the yield contract the corrected answer must come through. Bounded by the
+ * same remaining turn ceiling as the original pass.
+ */
+function toSpecRepairPrompt(detail: string): string {
+  return (
+    "Your grooming verdict was received but failed validation and was NOT recorded.\n\n" +
+    `Validation error: ${detail}\n\n` +
+    "This is your one repair round. Yield the complete, corrected verdict payload through the yield tool — " +
+    "an answer written as plain text is not an answer."
+  );
 }
 
 /**