omp-conductor 0.20.0 → 0.20.1

package/src/to-spec.ts

@@ -12,8 +12,9 @@
  * The five contract verdicts map onto it — PROMOTABLE → `promotable`;
  * ALREADY DONE and NEEDS DECOMPOSITION → `considered`; BLOCKED and NEEDS
  * PRODUCT DECISION → `blocked` — and a result that cannot be trusted
- * (malformed JSON, a schema violation, no authoritative source, or a stale
- * source) persists as `blocked` and never as `promotable`/`considered`.
+ * (no answer at all, malformed JSON, a schema violation, no authoritative
+ * source, or a stale source) persists as `blocked` and never as
+ * `promotable`/`considered`.
  * Reprocessing the same candidate is deterministic: the same input at the
  * same observation time produces the same row, and malformed output never
  * erases a prior valid (promotable/considered) result. Stale or source-less
@@ -326,9 +327,16 @@ export type ToSpecResult = Omit<z.infer<typeof ToSpecResultSchema>, "source"> &
   source: { name: string; ref: string; freshAt: number };
 };
 
-/** Why a result could not be trusted; each persists as a blocked record. */
+/** Why a result could not be trusted; each persists as a blocked record.
+ *
+ * `no-answer` is the session-level refusal (#1064): the pass produced no
+ * payload at all — the scout was killed at its turn ceiling, or the session
+ * ended without ever yielding. It is a property of the session, never of
+ * output, so it is decided by the pass before anything is parsed and is never
+ * `malformed`. */
 export type ToSpecFailure =
   | { kind: "malformed"; detail: string }
+  | { kind: "no-answer"; detail: string }
   | { kind: "missing-source"; detail: string }
   | { kind: "stale-source"; detail: string };
 
@@ -338,6 +346,20 @@ export type ParseToSpecOutcome = { ok: true; result: ToSpecResult } | { ok: fals
 export interface ToSpecEvidence {
   kind: "to-spec";
   result: ToSpecResult;
+  /**
+   * How the answer arrived (#1064): through the `yield` tool, or recovered
+   * from the session's text because it never yielded. `"text"` is the record's
+   * admission that the verdict did not come through the yield contract — the
+   * answer was complete and valid, so it stands, but a later reader can tell
+   * the two apart. Absent (or `"yield"`) means it came through the contract.
+   */
+  via?: "yield" | "text";
+  /**
+   * Whether the one bounded repair round produced the answer (#1064): the
+   * first answer parsed but violated the contract, the validation error was
+   * handed back, and the re-answer is what this record carries.
+   */
+  repaired?: boolean;
   /**
    * What the ready gate found missing when a valid PROMOTABLE verdict was
    * refused mechanical promotion (#1041). A sibling of `result`, never a
@@ -356,12 +378,21 @@ export interface ToSpecFailureEvidence {
   input: string;
 }
 
-/** How much raw agent output a failure record may carry. */
-export const TO_SPEC_INPUT_SAMPLE_MAX = 2_000;
+/**
+ * How much raw agent output a failure record may carry (#1064).
+ *
+ * Sized for the whole refused payload, not a sample of it: a complete verdict
+ * with a proposed brief and sizing analysis routinely exceeds 2 KB, and a
+ * discarded verdict should be recoverable from the row rather than
+ * re-derived at full session cost. 8 KB holds a full payload with headroom
+ * while still keeping a single refused row bounded.
+ */
+export const TO_SPEC_INPUT_SAMPLE_MAX = 8_000;
 
 /** Refused results always land on the same store surface, named by failure. */
 const FAILURE_REASON: Record<ToSpecFailure["kind"], string> = {
   malformed: "malformed",
+  "no-answer": "no-answer",
   "missing-source": "missing-source",
   "stale-source": "stale-source",
 };
@@ -411,6 +442,59 @@ function extractJson(input: string): string {
   return (fenced?.[1] ?? input).trim();
 }
 
+/**
+ * The three-way gate the scout runner decides a payload against (#1064):
+ * whether a string is a payload at all, and whether that payload already
+ * conforms to the contract or is a single re-answer away from it.
+ *
+ *  - `conforming` — a JSON object that satisfies the strict contract. For
+ *    text-recovered blocks this is the criterion that separates "a complete
+ *    verdict written outside the yield tool" from mere narration.
+ *  - `repairable` — a JSON object that violates the contract (the #1062
+ *    shape: every required field present, one key misnamed). The failure
+ *    carries the first validation issue, which is what the repair round hands
+ *    back to the scout.
+ *  - `not-a-payload` — prose, truncated JSON, a non-object: nothing a
+ *    re-answer can repair, so the pass records no answer rather than grading
+ *    it.
+ *
+ * Same parser as {@link parseToSpecResult}, deliberately: the runner probes
+ * with the one contract so its repair decision can never drift from what the
+ * persistence layer will accept — this is the one validator used twice, not a
+ * second, weaker one.
+ */
+export type ToSpecPayloadGate =
+  | { state: "conforming"; body: string }
+  | { state: "repairable"; body: string; failure: ToSpecFailure }
+  | { state: "not-a-payload" };
+
+export function gateToSpecPayload(payload: string): ToSpecPayloadGate {
+  const body = extractJson(payload);
+  if (body.length === 0) return { state: "not-a-payload" };
+  let raw: unknown;
+  try {
+    raw = JSON.parse(body);
+  } catch {
+    return { state: "not-a-payload" };
+  }
+  if (!isObject(raw)) return { state: "not-a-payload" };
+  const parsed = ToSpecResultSchema.safeParse(raw);
+  if (!parsed.success) {
+    // The field path rides in front of the message: zod says "Required" for a
+    // missing field and "Unrecognized key(s)…" for an extra one, and the
+    // repair round's whole value is that the scout sees WHICH field failed.
+    const first = parsed.error.issues[0];
+    const detail =
+      first === undefined
+        ? "schema violation"
+        : first.path.length === 0
+          ? first.message
+          : `${first.path.join(".")}: ${first.message}`;
+    return { state: "repairable", body, failure: { kind: "malformed", detail } };
+  }
+  return { state: "conforming", body };
+}
+
 /**
  * Parse and validate a groomer's raw output against the to-spec contract.
  * `now` is the settle time, explicit so staleness and determinism are
@@ -487,8 +571,31 @@ export type ToSpecGroomingOutcome =
 export interface ToSpecGroomingRequest {
   project: string;
   issue: number;
-  /** The agent's raw output, exactly as returned. */
+  /** The agent's structured answer, exactly as returned: the yield payload,
+   *  or a conforming block recovered from its text. Empty when the pass
+   *  produced no answer at all — which is its own refusal class, decided here
+   *  before anything is parsed (#1064). */
   input: string;
+  /** How the answer arrived: through the yield tool, or recovered from the
+   *  session's text because it never yielded. `"text"` marks the record so it
+   *  stays visible that the verdict did not come through the yield contract;
+   *  omitted reads as a yield, and an empty `input` with no `via` reads as no
+   *  answer. */
+  via?: "yield" | "text";
+  /** The session's last narration, recorded as the refusal's context when no
+   *  answer arrived — never parsed as a verdict (#1064). */
+  report?: string;
+  /** Whether the one bounded repair round produced the carried answer
+   *  (#1064); recorded on the row so a repaired verdict is distinguishable. */
+  repaired?: boolean;
+  /** Whether the session was killed at its turn ceiling before it answered
+   *  (#1064) — half of the no-answer shape naming. */
+  killedAtCeiling?: boolean;
+  /** The turn ceiling the pass ran under, and the turns it took: the other
+   *  half of the no-answer shape naming (`turns >= maxTurns` reads as a cap
+   *  kill even when the runner did not flag it). */
+  maxTurns?: number;
+  turns?: number;
   /** Observation time for staleness and the recorded row; `Date.now()` when
    *  omitted (tests pass it to keep reprocessing deterministic). */
   now?: number;
@@ -520,24 +627,51 @@ function failureEvidence(failure: ToSpecFailure, input: string): string {
  * it, not anything the agent wrote, becomes the recorded source observation
  * time.
  */
-export function recordToSpecGrooming(store: Store, request: ToSpecGroomingRequest): ToSpecGroomingOutcome {
-  const now = request.now ?? Date.now();
-  const parsed = parseToSpecResult(request.input, now, { launchedAt: request.launchedAt });
-  if (parsed.ok) {
-    const evidence: ToSpecEvidence = { kind: "to-spec", result: parsed.result };
-    store.upsertGrooming({
-      project: request.project,
-      issue: request.issue,
-      verdict: mapStoreVerdict(parsed.result.verdict),
-      reason: mapStoreReason(parsed.result.verdict),
-      evidence: JSON.stringify(evidence),
-      at: now,
-    });
-    return { kind: "persisted", record: store.grooming(request.project, request.issue)! };
+/**
+ * The reason a via-text verdict carries: the groomer's own label with a
+ * visible marker that the answer arrived outside the yield contract (#1064),
+ * so `status` reads `#13 promotable via text` instead of hiding the
+ * distinction in an evidence string. Yielded verdicts keep the bare label.
+ */
+function mapStoreReasonWithVia(verdict: ToSpecVerdict, via: "yield" | "text" | undefined): string {
+  const label = mapStoreReason(verdict);
+  return via === "text" ? `${label} via text` : label;
+}
+
+/**
+ * The no-answer detail names which of the two session shapes produced it
+ * (#1064): a turn-ceiling kill (`killedAtCeiling`, or `turns >= maxTurns`
+ * when the runner did not flag it) or a session that ended without ever
+ * yielding.
+ */
+function noAnswerDetail(request: ToSpecGroomingRequest): string {
+  const killed =
+    request.killedAtCeiling === true ||
+    (request.maxTurns !== undefined && request.turns !== undefined && request.turns >= request.maxTurns);
+  const turns = request.turns === undefined ? "" : ` after ${request.turns} turn(s)`;
+  if (killed) {
+    const ceiling = request.maxTurns === undefined ? "its turn ceiling" : `its ${request.maxTurns}-turn ceiling`;
+    return `the scout was killed at ${ceiling}${turns} and never yielded an answer`;
   }
+  return `the scout session ended${turns} without yielding an answer`;
+}
+
+/**
+ * Persist one refusal, or keep a prior valid verdict when the new pass
+ * produced something no-answer-like or malformed. `input` is what the failure
+ * record carries: the raw payload of the refused pass — or, for a no-answer
+ * pass, the session's narration as context (#1064).
+ */
+function persistGroomingRefusal(
+  store: Store,
+  request: ToSpecGroomingRequest,
+  failure: ToSpecFailure,
+  input: string,
+  now: number,
+): ToSpecGroomingOutcome {
   const prior = store.grooming(request.project, request.issue);
   if (
-    parsed.failure.kind === "malformed" &&
+    (failure.kind === "malformed" || failure.kind === "no-answer") &&
     prior !== undefined &&
     (prior.verdict === "promotable" || prior.verdict === "considered")
   ) {
@@ -547,13 +681,83 @@ export function recordToSpecGrooming(store: Store, request: ToSpecGroomingReques
     project: request.project,
     issue: request.issue,
     verdict: "blocked",
-    reason: FAILURE_REASON[parsed.failure.kind],
-    evidence: failureEvidence(parsed.failure, request.input),
+    reason: FAILURE_REASON[failure.kind],
+    evidence: failureEvidence(failure, input),
     at: now,
   });
   return { kind: "persisted", record: store.grooming(request.project, request.issue)! };
 }
 
+/**
+ * The only way a groomer's output becomes a durable grooming verdict: parse
+ * and validate, then upsert through the existing store — no second store, no
+ * `GroomingRecord` extension. Valid results map to the store's verdict
+ * surface with the full structured result serialized into `evidence`
+ * (`{"kind":"to-spec","result":…}`), which is what survives a restart. A
+ * refused result persists as `blocked` with the failure named in
+ * `evidence` (`to-spec-failure`) — never as promotable/considered — except
+ * when a prior valid result exists: malformed and no-answer reprocessing then
+ * keep that prior row instead of erasing it. Nothing here touches labels or
+ * issues.
+ *
+ * The refusal classes come from the whole pass, not just its output (#1064):
+ *
+ *  - `no-answer` — the session produced no payload at all (no yield, no
+ *    conforming text block): a turn-ceiling kill or a session end without a
+ *    yield, recorded by shape, never as `malformed`. The narration is kept as
+ *    context only. A text-carried block that fails validation is also
+ *    `no-answer` — such a session never yielded, and the block is not an
+ *    answer — except a batch-window staleness, which is a property of the
+ *    pass rather than the answer.
+ *  - `malformed` / `missing-source` — a *yielded* payload (or an unjudged
+ *    one) that violates the contract, with the raw payload persisted so the
+ *    discarded verdict stays recoverable.
+ *  - `stale-source` — the batch window outlived the freshness ceiling.
+ *
+ * `request.launchedAt` is the dispatcher's launch stamp for the batch (#1000);
+ * it, not anything the agent wrote, becomes the recorded source observation
+ * time.
+ */
+export function recordToSpecGrooming(store: Store, request: ToSpecGroomingRequest): ToSpecGroomingOutcome {
+  const now = request.now ?? Date.now();
+  if (request.input === "") {
+    return persistGroomingRefusal(
+      store,
+      request,
+      { kind: "no-answer", detail: noAnswerDetail(request) },
+      request.report ?? "",
+      now,
+    );
+  }
+  const parsed = parseToSpecResult(request.input, now, { launchedAt: request.launchedAt });
+  if (parsed.ok) {
+    const evidence: ToSpecEvidence = {
+      kind: "to-spec",
+      result: parsed.result,
+      ...(request.via === undefined ? {} : { via: request.via }),
+      ...(request.repaired === true ? { repaired: true } : {}),
+    };
+    store.upsertGrooming({
+      project: request.project,
+      issue: request.issue,
+      verdict: mapStoreVerdict(parsed.result.verdict),
+      reason: mapStoreReasonWithVia(parsed.result.verdict, request.via),
+      evidence: JSON.stringify(evidence),
+      at: now,
+    });
+    return { kind: "persisted", record: store.grooming(request.project, request.issue)! };
+  }
+  // A text-carried answer that fails validation was never yielded and does
+  // not conform: that is a no-answer pass, with the block kept as the
+  // failure's context — never malformed (#1064). The one exception is a
+  // batch-window staleness, whose class is about the pass, not the answer.
+  const failure =
+    request.via === "text" && parsed.failure.kind !== "stale-source"
+      ? { kind: "no-answer" as const, detail: noAnswerDetail(request) }
+      : parsed.failure;
+  return persistGroomingRefusal(store, request, failure, request.input, now);
+}
+
 /**
  * Recover the validated result from a record's evidence (the restart
  * round-trip). Returns undefined for anything that is not a `to-spec`
@@ -601,7 +805,12 @@ export function parseToSpecFailureEvidence(evidence: string): ToSpecFailure | un
   if (!isObject(raw) || raw.kind !== "to-spec-failure") return undefined;
   const failure = raw.failure;
   if (!isObject(failure) || typeof failure.detail !== "string") return undefined;
-  if (failure.kind !== "malformed" && failure.kind !== "missing-source" && failure.kind !== "stale-source") {
+  if (
+    failure.kind !== "malformed" &&
+    failure.kind !== "no-answer" &&
+    failure.kind !== "missing-source" &&
+    failure.kind !== "stale-source"
+  ) {
     return undefined;
   }
   return { kind: failure.kind, detail: failure.detail };

package/src/types.ts

@@ -1797,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",
@@ -1831,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).
  */
@@ -1855,6 +1869,7 @@ export const RECOVERY_ACTIONS = [
   "rerun-checks",
   "settle",
   "escalate",
+  "observe",
   "hold",
   "none",
 ] as const;

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."
+  );
 }
 
 /**