omp-conductor 0.18.0 → 0.18.2

package/src/orchestrator-tick.ts

@@ -46,7 +46,7 @@
 
 import { createHash, randomUUID } from "node:crypto";
 import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { availabilityPrompt, interruptDisposition } from "./availability.ts";
 import { findProject, loadConfig, resolveReleaseGrants, stateDir } from "./config.ts";
@@ -82,32 +82,51 @@ import {
   type DispatchSummary,
   type DigestBacklog,
   type FrictionSignal,
+  type GroomingRecord,
   type HeldNotice,
   type InterruptCategory,
   type IntakeItem,
+  type IssueState,
   type MaterialEvent,
+  type ProjectConfig,
+  type ReadyIssue,
   type ReportScopeChoice,
   type ReportingPolicy,
   type ResolvedGrants,
   type Store,
 } from "./types.ts";
+import { repoSlugFor } from "./gitops.ts";
+import { makeTracker } from "./tracker/github.ts";
 import { formatDecisionDigest } from "./decisions.ts";
 import {
   ASK_TOOL,
+  askAnswerRowWrite,
   askParameterSchema,
   DEFAULT_ASK_TIMEOUT_SECONDS,
   MAX_ASK_TIMEOUT_SECONDS,
   MIN_ASK_TIMEOUT_SECONDS,
+  parseAskAnswerEnvelope,
   parseAskRequest,
   performAsk,
+  renderInteractiveAsk,
+  type AskAnswerEnvelope,
+  type AskInteractiveDelivery,
   type AskResult,
 } from "./ask.ts";
 import { deliverOperatorMessage } from "./reports.ts";
-import type { FailureClass, ProjectConfig, RecoveryAction, RunRecord } from "./types.ts";
+import { effectiveLabels } from "./routing.ts";
+import { readTelegramToken, resolveProjectTopicId, telegramStateDir } from "./escalate.ts";
+import type { FailureClass, RecoveryAction, RunRecord } from "./types.ts";
 import { dbPath, openStore } from "./store.ts";
 import { digestDue, localDayKey } from "./digest-schedule.ts";
+import {
+  parseToSpecEvidence,
+  recordToSpecGrooming,
+  TO_SPEC_MAX_SOURCE_AGE_MS,
+  TO_SPEC_SCHEMA,
+} from "./to-spec.ts";
 import { heldNoticeId } from "./notices.ts";
-import { isActiveArmProof } from "./arm-challenge.ts";
+import { acknowledgeArmReply } from "./arm-challenge.ts";
 
 /** The activation file. Absent means "this is not an orchestrator session". */
 export const TICK_CONFIG_FILE = ".conductor-tick.json";
@@ -603,20 +622,88 @@ export function recoveryDigestLine(
   return lines.join("\n");
 }
 
+/** Per-reason counts for a verdict slice — "file-lane 2, depends-on 1". */
+function groomingGroupCounts(records: readonly GroomingRecord[]): string {
+  const counts = new Map<string, number>();
+  for (const record of records) {
+    counts.set(record.reason, (counts.get(record.reason) ?? 0) + 1);
+  }
+  return [...counts.entries()].map(([reason, count]) => `${reason} ${count}`).join(", ");
+}
+
+/** Per-verdict counts for a slice — "promotable 1, considered 1". */
+function groomingVerdictCounts(records: readonly GroomingRecord[]): string {
+  const counts = new Map<string, number>();
+  for (const record of records) {
+    counts.set(record.verdict, (counts.get(record.verdict) ?? 0) + 1);
+  }
+  return [...counts.entries()].map(([verdict, count]) => `${verdict} ${count}`).join(", ");
+}
+
+/**
+ * The queue-label inventory read fresh from the tracker on one tick, with the
+ * pending label ops applied exactly as the dispatch pass judges eligibility
+ * (#848). Queue verdicts in the present tense ("empty", "running low") are
+ * only ever drawn from this observation; a dispatch summary alone is dated
+ * history and must never be rendered as the live queue.
+ */
+export interface QueueObservation {
+  /** Open issues carrying the queue label under the *effective* label set —
+   *  the count dispatch would route against on its next pass. */
+  queued: number;
+  /** The instant the tracker observation was made, epoch ms. */
+  observedAt: number;
+}
+
 /**
  * One line telling the orchestrator the routable queue is running dry (#181),
  * or `undefined` when healthy — no dispatch recorded yet, or the routable count
- * is at/above the grooming trigger.
+ * is at/above the grooming trigger. `grooming` is the durable per-issue verdict
+ * table (#735): `blocked` rows are admission's lane/dependency holds, so the
+ * line tells claimable candidates apart from a runway that cannot move —
+ * instead of inviting Duty 2 to groom work whose last pass held it, which is
+ * exactly the re-derivation this store exists to stop. A to-spec launch row
+ * (#777) carries the same `blocked` verdict as its durable in-flight marker,
+ * so it is told apart from the mechanical holds: it says "a batch is running",
+ * not "the lane cannot move", and counts neither as claimable nor as
+ * known-blocked.
+ *
+ * `queue` is the tracker observation the caller made THIS tick (#848). When
+ * present, the queue verdict reads in the present tense from that inventory,
+ * and dispatch-derived counts are only ever dated context. When absent the
+ * tracker could not be read, and this never asserts that the queue is empty:
+ * the dispatch row is rendered explicitly as-of instead.
  */
 export function queueDigestLine(
   summary: DispatchSummary | undefined,
   queueLabel: string,
   labelPrefix: string,
   groomBelow: number,
+  grooming: readonly GroomingRecord[] = [],
+  queue: QueueObservation | undefined = undefined,
 ): string | undefined {
   if (summary === undefined) return undefined;
+  if (queue !== undefined) {
+    return liveQueueDigestLine(summary, queue, queueLabel, labelPrefix, groomBelow, grooming);
+  }
+  return datedQueueDigestLine(summary, queueLabel, labelPrefix, groomBelow, grooming);
+}
+
+/** The dated rendering: the last dispatch row is the only evidence, so every
+ *  count carries its snapshot date and nothing is asserted as current. */
+function datedQueueDigestLine(
+  summary: DispatchSummary,
+  queueLabel: string,
+  labelPrefix: string,
+  groomBelow: number,
+  grooming: readonly GroomingRecord[],
+): string | undefined {
+  const dated = new Date(summary.completedAt).toISOString();
   if (summary.ready === 0) {
-    return `Queue: empty — nothing carries "${queueLabel}". Groom the backlog (Duty 2): promote or file the next issues, or say in this tick's report why there is nothing to do.`;
+    if (summary.paused === true) {
+      return `Queue: unchecked — the last pass (${dated}) was a hold that counted no queue and admitted nothing; the tracker could not be re-read this tick, so the live queue is NOT claimed empty. Groom only after a fresh read.`;
+    }
+    return `Queue: empty (as of the last dispatch, ${dated}) — nobody carried "${queueLabel}" on that count, and the live tracker was not re-read this tick, so this is a snapshot, not a present-tense claim. Groom the backlog (Duty 2) once a fresh read confirms it.`;
   }
   if (summary.routed === 0) {
     // `ready` counts claimed (in-flight) issues too; route() drops those with a
@@ -633,7 +720,7 @@ export function queueDigestLine(
     const staleLifecycle = summary.holds
       .filter((h) => h.reason === "stale-lifecycle")
       .reduce((n, h) => n + h.count, 0);
-    let line = `Queue: ${summary.ready} ready, 0 spare — ${claimed} in flight`;
+    let line = `As of the last dispatch (${dated}): Queue: ${summary.ready} ready, 0 spare — ${claimed} in flight`;
     if (unroutable > 0) {
       line += `, ${unroutable} unroutable (each unroutable issue needs exactly one "${labelPrefix}<repo>" label)`;
     }
@@ -648,7 +735,128 @@ export function queueDigestLine(
     return line;
   }
   if (summary.routed >= groomBelow) return undefined;
-  let line = `Queue: running low — ${summary.routed} routable candidate(s), below the grooming trigger of ${groomBelow}.`;
+  return lowQueueTail(summary, groomBelow, grooming, `As of the last dispatch (${dated}): Queue: `);
+}
+
+/** The live rendering: the tracker observation is the queue label inventory,
+ *  the dispatch summary supplies the claimability reading, and the shared
+ *  low-queue diagnostics are composed underneath (#848 review 2). The raw
+ *  carrier count appears only as a present-tense inventory fact — never as
+ *  the grooming threshold, which must be claimability (`summary.routed`, the
+ *  same count the to-spec offer gates on), or parked/in-flight/state-labelled
+ *  carriers would silence a queue that dispatch cannot move. */
+function liveQueueDigestLine(
+  summary: DispatchSummary,
+  queue: QueueObservation,
+  queueLabel: string,
+  labelPrefix: string,
+  groomBelow: number,
+  grooming: readonly GroomingRecord[],
+): string | undefined {
+  const queued = queue.queued;
+  const observed = new Date(queue.observedAt).toISOString();
+  // The present-tense empty verdict is the tracker's own word: nothing open
+  // carries the queue label right now. No dispatch snapshot may produce a
+  // live "empty" claim — that is the whole defect (#848).
+  if (queued === 0) {
+    return (
+      `Queue: empty — nothing open carries "${queueLabel}" right now (tracker ${observed}). ` +
+      "Groom the backlog (Duty 2): promote or file the next issues, or say in this tick's report " +
+      "why there is nothing to do."
+    );
+  }
+  // The grooming threshold is claimability — summary.routed — never raw
+  // carrier volume. Four in-flight/parked/unroutable carriers must not
+  // suppress the low-claimable signal, because the to-spec offer gates on
+  // the very same routed count and the two would split.
+  if (summary.routed >= groomBelow) return undefined;
+  const dated = new Date(summary.completedAt).toISOString();
+  const inventory = `Queue: ${queued} open issue${queued === 1 ? "" : "s"} carry "${queueLabel}" right now (tracker ${observed}); `;
+  if (summary.routed === 0) {
+    // Dispatch's own claimability read: `ready` counts claimed (in-flight)
+    // issues too, so "0 routable" must not blanket-blame missing `repo:`
+    // labels (#228), and a residual lifecycle label is Duty 1 reconciliation
+    // work, not spare depth (#611).
+    if (summary.paused === true) {
+      return (
+        inventory +
+        `the last dispatch (${dated}) was a hold that admitted nothing — the queued issues above are the work that resumes when claiming reopens.`
+      );
+    }
+    const claimed = summary.claimed ?? 0;
+    let line = inventory + `at the last dispatch (${dated}) ${summary.ready} ready, 0 spare — ${claimed} in flight`;
+    const unroutable = summary.holds
+      .filter((h) => h.reason.startsWith("unroutable:"))
+      .reduce((n, h) => n + h.count, 0);
+    const staleLifecycle = summary.holds
+      .filter((h) => h.reason === "stale-lifecycle")
+      .reduce((n, h) => n + h.count, 0);
+    if (unroutable > 0) {
+      line += `, ${unroutable} unroutable (each unroutable issue needs exactly one "${labelPrefix}<repo>" label)`;
+    }
+    if (staleLifecycle > 0) {
+      line += `, ${staleLifecycle} with a residual lifecycle label (Duty 1: newest run terminal — reconcile the stale agent:in-progress/blocked/failed state)`;
+    }
+    if (unroutable === 0 && staleLifecycle === 0) {
+      line += `. Spare depth is what dispatch can actually claim: groom the backlog (Duty 2) before the live runs settle.`;
+    } else {
+      line += ".";
+    }
+    return line;
+  }
+  // routed > 0 below the trigger: the live inventory leads, then the same
+  // low-queue diagnostics the dated path ships — the claimable/known-blocked
+  // split, in-flight to-spec batches, the considered backlog and this pass's
+  // holds (#735, #777, #679) — so a tracker read never hides them.
+  return inventory + lowQueueTail(summary, groomBelow, grooming, "");
+}
+
+/** The shared low-queue diagnostic tail (#735/#777/#679): the routable-count →
+ *  claimable/known-blocked split, in-flight to-spec batches, the considered
+ *  backlog and this pass's holds. `lead` is the sentence opener the caller
+ *  chooses — the dated path opens with the dispatch timestamp and "Queue:",
+ *  the live path with its tracker inventory (#848 review 2). Sharing one tail
+ *  means a tracker read can never hide these distinctions. */
+function lowQueueTail(
+  summary: DispatchSummary,
+  groomBelow: number,
+  grooming: readonly GroomingRecord[],
+  lead: string,
+): string {
+  // The durable per-issue verdicts, not this pass's one-shot hold groups: a
+  // lane-blocked runway must read as "cannot move" even after a restart, and
+  // the orchestrator's own prior verdicts (#679) must not be re-derived.
+  //
+  // An in-flight to-spec launch (#777) is backlog inventory, not a routed
+  // ready candidate, a durable hold, or a verdict. Name it separately without
+  // subtracting it from the routed queue or printing lane/dependency guidance.
+  const inFlight = grooming.filter((g) => g.reason === TO_SPEC_IN_FLIGHT_REASON);
+  const knownBlocked = grooming.filter(
+    (g) => g.verdict === "blocked" && (g.reason === "file-lane" || g.reason === "depends-on"),
+  );
+  const considered = grooming.filter((g) => g.verdict === "promotable" || g.verdict === "considered");
+  const claimable = Math.max(0, summary.routed - knownBlocked.length);
+  const inFlightNames = inFlight.map((r) => `#${r.issue}`).join(", ");
+  const busy = inFlight.length === 0 ? "" : `, ${inFlight.length} in a to-spec batch (${inFlightNames})`;
+  let tail: string;
+  if (knownBlocked.length > 0 && claimable === 0) {
+    tail =
+      `${lead}running low — ${summary.routed} routable candidate(s), all known-blocked ` +
+      `(${groomingGroupCounts(knownBlocked)})${busy} — no grooming moves them; the holds clear by themselves` +
+      `${inFlight.length === 0 ? "" : " and the to-spec batch's results land when it settles"}.`;
+  } else if (knownBlocked.length > 0 || inFlight.length > 0) {
+    tail =
+      `${lead}running low — ${summary.routed} routable candidate(s), below the grooming trigger of ${groomBelow}: ` +
+      `${claimable} claimable, ${knownBlocked.length} known-blocked (${groomingGroupCounts(knownBlocked)})` +
+      `${busy} — groom only the claimable.`;
+  } else {
+    tail = `${lead}running low — ${summary.routed} routable candidate(s), below the grooming trigger of ${groomBelow}.`;
+  }
+  if (considered.length > 0) {
+    tail +=
+      ` Backlog already-considered: ${considered.length} (${groomingVerdictCounts(considered)}) — ` +
+      `promote the promotable or groom new issues, never re-groom these.`;
+  }
   if (summary.admitted === 0 && summary.holds.length > 0) {
     const held = summary.holds
       .map((h) => {
@@ -656,9 +864,524 @@ export function queueDigestLine(
         return `${h.reason} ${h.count}${first === undefined ? "" : ` (${first})`}`;
       })
       .join(", ");
-    line += ` All held: ${held}.`;
+    tail += ` All held: ${held}.`;
   }
-  return line;
+  return tail;
+}
+
+// ================================================================ to-spec
+// launch lifecycle (#777). #772 shipped the strict to-spec contract
+// (`TO_SPEC_SCHEMA` + `recordToSpecGrooming`); this section is the launch
+// half: the mechanical candidate selection, the bounded prompt block that
+// authorizes exactly one native `task` batch per low-queue tick, the
+// tool-call gate that stamps the contract and records in-flight rows, and
+// the result capture that routes every item's exact output through
+// `recordToSpecGrooming` independently.
+//
+// Where each fact lives decides who enforces it — and every exclusion is
+// enforced mechanically from authoritative data, never by prose:
+//
+//  - Tracker facts — the open-issue pool, the park label, the parent/epic
+//    probe — are read ONCE, at launch composition time, through the existing
+//    Tracker adapter (`listOpenIssues`/`childrenOf`). The tick turns that
+//    snapshot into the mechanically selected batch: `offerToSpecLaunch`
+//    streams the snapshot through the store-side exclusions and the parent
+//    probe, and the returned block names the selected candidates as the ONLY
+//    batch this tick may launch. If the snapshot cannot be read, no batch is
+//    offered at all — the launch fails closed rather than trusting the model
+//    to self-filter.
+//  - Store facts — durable grooming rows (#735), admission's lane/dependency
+//    holds, active runs, in-flight launches — are enforced mechanically at
+//    composition time (the exclusion lines the block names) and again at
+//    `tool_call` time (the gate refuses an item the store contradicts).
+//  - The live source ref for each item cannot be known synchronously without
+//    a fresh per-repo read, so the model fetches it and declares it in the
+//    item's second contract line; the strict parser's 24h freshness ceiling
+//    re-vets the claim at persistence time, which is the boundary #772 set.
+//  - The gate additionally enforces the allowlist: a marker-bearing `task`
+//    call is refused unless every item's issue number AND routing repo match
+//    the batch this tick's token authorized. A parked or parent/epic
+//    candidate therefore cannot be stamped in-flight even if the model
+//    invents one — it was never on the list, and the list is the only thing
+//    the gate lets through.
+//
+// The pure selector (`selectToSpecBatch`) remains the single shared rule set:
+// the offer feeds it the tracker-vetted pool and the gate runs the same
+// exclusion on every item at call time, so a candidate excluded in the prompt
+// is excluded in the gate for the same reason.
+
+/** The `to-spec` agent every batch item runs under (shipped in
+ *  `omp/agents/to-spec.md`, discovered through OMP's native task-agent
+ *  discovery — never a custom process runtime). */
+export const TO_SPEC_AGENT = "to-spec";
+
+/** The maximum number of candidates one tick's batch may carry (#679's
+ *  "small per-tick candidate limit"; the session-scoped task semaphore
+ *  bounds concurrency underneath). */
+export const TO_SPEC_BATCH_MAX = 3;
+
+/**
+ * The `context` marker that identifies a conductor grooming batch to the
+ * `tool_call` gate. The launch block instructs the orchestrator to put
+ * `{@link TO_SPEC_BATCH_MARKER}: <token>` as the first line of the batch's
+ * shared `context`; the gate matches the marker and the exact token this tick
+ * issued, stamps the per-item contract (agent, strict schema), and persists
+ * the in-flight rows. A `task` call without this marker is the orchestrator's
+ * own and passes untouched.
+ */
+export const TO_SPEC_BATCH_MARKER = "conductor-to-spec-batch";
+
+/** The grooming-table verdict row a launched-but-unfinished batch leaves behind
+ *  (reason, on a `blocked` verdict): the durable in-flight marker that stops
+ *  the next tick — or a restarted session — from re-launching the same item.
+ *  `blocked` is deliberate: `recordToSpecGrooming` replaces the row when the
+ *  result lands, and refusing-to-parse output must *not* be swallowed by the
+ *  kept-prior path that protects prior `promotable`/`considered` verdicts. */
+export const TO_SPEC_IN_FLIGHT_REASON = "in-flight";
+
+/**
+ * How long a launch row may sit before it is treated as a dead batch and the
+ * candidate becomes eligible again. A batch that dies with the process (a
+ * daemon stop between `tool_call` and delivery) must not park a candidate
+ * forever; the 24h ceiling matches the source-freshness ceiling, so a
+ * relaunched pass always reads new source evidence anyway.
+ */
+export const TO_SPEC_IN_FLIGHT_TTL_MS = 24 * 60 * 60 * 1_000;
+
+/** The first line of every batch item's `task`, in the shape the gate parses:
+ *  `to-spec candidate: <owner/repo>#<issue> — <title>`. */
+export const TO_SPEC_ITEM_PREFIX = "to-spec candidate:";
+
+/** The second line of every batch item's `task`, naming the authoritative
+ *  source and the exact ref the item was groomed against:
+ *  `to-spec source: <owner/repo>@<ref>`. `ref` is whatever the launch block
+ *  told the orchestrator to fetch as the repo's current default-branch head. */
+export const TO_SPEC_ITEM_SOURCE_PREFIX = "to-spec source:";
+
+/** The tool the orchestrator calls to persist one completed item's exact raw
+ *  output when the batch ran in the background (#777). Registered by this
+ *  extension; subagents never see it — the `to-spec` agent's tool list is
+ *  read-only and explicit. */
+export const TO_SPEC_RESULT_TOOL = "conductor_to_spec_result";
+
+/** One backlog candidate the mechanical gate can judge. The tracker facts
+ *  (labels, epics) are read from the authoritative open-issue snapshot at
+ *  launch composition time; they travel in this view so the selector stays
+ *  deterministic and testable. */
+export interface ToSpecCandidateView {
+  issue: number;
+  title: string;
+  /** The routing target — a routed `owner/repo` (from the issue's one
+   *  `routing.labelPrefix<key>` label, resolved through `routing.repos`). */
+  routing: string;
+  /** Operator-parked (`project.stateLabels.backlog`); read from tracker labels. */
+  parked?: boolean;
+  /** A parent/epic with no independently runnable slice; read from the
+   *  tracker's sub-issue probe. */
+  parent?: boolean;
+}
+
+/** One candidate the tick's token authorizes. The gate admits a batch item
+ *  only when its issue number AND routing both match an entry here. */
+export interface ToSpecLaunchItem {
+  issue: number;
+  /** The `owner/repo` the item's first contract line must name. */
+  routing: string;
+  /** The candidate title, as it appears in the item's first contract line. */
+  title: string;
+}
+
+/** The machine-readable item contract a batch item must satisfy. */
+export interface ToSpecBatchItem {
+  issue: number;
+  /** The `owner/repo` named by the item's first contract line. */
+  routing: string;
+  /** The `owner/repo@ref` named by the item's second contract line. */
+  sourceRef: string;
+  /** The item's full task text (the rendered brief plus the contract lines). */
+  task: string;
+}
+
+/**
+ * Parse the two contract lines a batch item must start with
+ * (`to-spec candidate: <repo>#<n> — <title>` / `to-spec source: <name>@<ref>`).
+ * Anything else is not a conductor grooming item. Built from the shared
+ * {@link TO_SPEC_ITEM_PREFIX}/{@link TO_SPEC_ITEM_SOURCE_PREFIX} constants so
+ * the launch block's wording and the gate's parsing cannot drift apart.
+ */
+export function parseToSpecItem(task: unknown): ToSpecBatchItem | undefined {
+  if (typeof task !== "string") return undefined;
+  const lines = task.split("\n");
+  const head = new RegExp(`^${TO_SPEC_ITEM_PREFIX}\\s+([\\w.-]+\\/[\\w.-]+)#(\\d+)(?:\\s+—\\s+.*)?$`).exec(
+    lines[0]?.trim() ?? "",
+  );
+  const source = new RegExp(`^${TO_SPEC_ITEM_SOURCE_PREFIX}\\s+([\\w.-]+\\/[\\w.-]+)@(\\S+)$`).exec(
+    lines[1]?.trim() ?? "",
+  );
+  if (head === null || source === null) return undefined;
+  return { issue: Number(head[2]), routing: head[1]!, sourceRef: source[2]!, task };
+}
+
+/**
+ * Why one candidate is not eligible for a batch right now, or undefined when
+ * it is. The single rule source for the prompt-time exclusion list, the
+ * `tool_call` gate, and the selection helper — one rule, three readers, so a
+ * candidate excluded in prose is excluded in the gate for the same reason.
+ *
+ *  - `in-flight`: a launch row recorded within the TTL (a dead batch's row
+ *    expires and the candidate becomes eligible again);
+ *  - `file-lane` / `depends-on`: admission's durable mechanical holds (#735);
+ *  - a fresh valid `to-spec` result in the grooming table: the candidate was
+ *    already groomed at an observed source within the freshness ceiling, so
+ *    re-running it would recompute a verdict that is still valid. New source
+ *    evidence reconsiders it: once the recorded `freshAt` crosses the ceiling
+ *    the row no longer reads as groomed, and a fresh pass overrides it;
+ *  - `active`: a run is in flight on the issue right now.
+ */
+export function toSpecCandidateExclusion(
+  candidate: { issue: number },
+  facts: { grooming: GroomingRecord | undefined; active: boolean },
+  now: number,
+): string | undefined {
+  const row = facts.grooming;
+  if (row !== undefined) {
+    if (row.reason === TO_SPEC_IN_FLIGHT_REASON) {
+      if (now - row.recordedAt <= TO_SPEC_IN_FLIGHT_TTL_MS) {
+        return `#${candidate.issue} is already in a to-spec batch (launched ${new Date(row.recordedAt).toISOString()})`;
+      }
+    } else if (row.reason === "file-lane" || row.reason === "depends-on") {
+      return `#${candidate.issue} is mechanically blocked (${row.reason}) — the hold clears by itself`;
+    } else {
+      const result = parseToSpecEvidence(row.evidence);
+      if (result !== undefined && now - result.source.freshAt <= TO_SPEC_MAX_SOURCE_AGE_MS) {
+        return (
+          `#${candidate.issue} was already groomed ${result.verdict} (source ${result.source.name}@` +
+          `${result.source.ref}, observed ${new Date(result.source.freshAt).toISOString()}) — re-groom only ` +
+          "with new source evidence"
+        );
+      }
+    }
+  }
+  if (facts.active) return `#${candidate.issue} has a dispatched run in flight`;
+  return undefined;
+}
+
+/**
+ * The mechanical half of Duty 2's launch: deterministic, bounded selection of
+ * the eligible candidates, smallest issue numbers first, never more than
+ * {@link TO_SPEC_BATCH_MAX} per batch, nothing at/above the grooming trigger,
+ * nothing before the first dispatch summary exists (queue health unknown —
+ * the same gate the queue digest uses). Parked and parent views are honored
+ * when the caller supplies them.
+ *
+ * Production reaches this selector through {@link offerToSpecLaunch}, which
+ * fills the views from the authoritative tracker snapshot (park label from
+ * the open-issue labels, parent/epic from the sub-issue probe) and streams
+ * the store-side exclusions before the selector runs — so parked and parent
+ * exclusions are enforced on the live path, not only on test inputs.
+ */
+export function selectToSpecBatch(input: {
+  candidates: readonly ToSpecCandidateView[];
+  summary: DispatchSummary | undefined;
+  groomBelow: number;
+  grooming: readonly GroomingRecord[];
+  active: readonly { issue: number }[];
+  now: number;
+}): ToSpecCandidateView[] {
+  if (input.summary === undefined) return [];
+  if (input.summary.routed >= input.groomBelow) return [];
+  const groomingByIssue = new Map(input.grooming.map((row) => [row.issue, row]));
+  const activeIssues = new Set(input.active.map((run) => run.issue));
+  const selected: ToSpecCandidateView[] = [];
+  for (const candidate of [...input.candidates].sort((a, b) => a.issue - b.issue)) {
+    if (candidate.parked) continue;
+    if (candidate.parent) continue;
+    if (
+      toSpecCandidateExclusion(
+        { issue: candidate.issue },
+        { grooming: groomingByIssue.get(candidate.issue), active: activeIssues.has(candidate.issue) },
+        input.now,
+      ) !== undefined
+    ) {
+      continue;
+    }
+    selected.push(candidate);
+    if (selected.length >= TO_SPEC_BATCH_MAX) break;
+  }
+  return selected;
+}
+
+/**
+ * One tick's launch authorization: the token, the block text it carries, and
+ * the mechanically selected batch the token authorizes. The gate admits a
+ * marker-bearing `task` call only when every item matches an entry of
+ * {@link ToSpecLaunchBlock.items} — the list is produced from the tracker
+ * snapshot, never from model-supplied fields.
+ */
+export interface ToSpecLaunchBlock {
+  /** The per-launch token the batch must echo in its `context` first line. */
+  token: string;
+  block: string;
+  /** The mechanically selected candidates — the ONLY batch this token may
+   *  carry (issue number AND routing must both match). */
+  items: ToSpecLaunchItem[];
+}
+
+/** Why candidates sit out, as one compact line each, for the launch block. */
+export interface ToSpecLaunchExclusions {
+  /** Candidates with a fresh, valid to-spec verdict already on the grooming table. */
+  groomed: string[];
+  /** Candidates with an active to-spec batch. */
+  inFlight: string[];
+  /** Candidates under admission's durable lane/dependency holds. */
+  mechanicallyBlocked: string[];
+  /** Candidates with a dispatched run live right now. */
+  dispatched: string[];
+}
+
+/**
+ * The authoritative tracker surface the launch selection is built from
+ * (#777): the two reads through the existing Tracker adapter that answer
+ * "which open backlog issues are actually eligible right now". Production
+ * implements this with `makeTracker(...).listOpenIssues()` /
+ * `.childrenOf(...)`; tests inject deterministic fakes. `listOpenIssues` is
+ * the one open-issue snapshot with labels (#203) — it answers the park
+ * label and the routing label mechanically — and `childrenOf` answers
+ * whether a candidate is a parent/epic (its sub-issues exist, so it has no
+ * independently runnable slice of its own). Both fail closed: an unreadable
+ * snapshot means no batch is offered, while an unreadable parent probe skips
+ * that candidate because eligibility was not mechanically established.
+ */
+export interface ToSpecTrackerSeam {
+  /** Every open issue in the tracker repo, labels included
+   *  (`Tracker.listOpenIssues`). Throws when the tracker cannot be read. */
+  listOpenIssues(project: ProjectConfig): Promise<ReadyIssue[]>;
+  /** Sub-issues of one issue (`Tracker.childrenOf`). */
+  childrenOf(project: ProjectConfig, issue: number): Promise<{ number: number; state: IssueState }[]>;
+}
+
+/**
+ * The tracker half of the candidate views: map one open-issue snapshot onto
+ * the pool the selector can judge. Issues still carrying the queue label are
+ * already queued — not backlog — and leave the pool; issues with zero or
+ * several `routing.labelPrefix` labels (or a label mapping to no configured
+ * repo) cannot name an authoritative source to read and leave the pool,
+ * exactly like admission's unroutable partition. The park label lands on the
+ * view for the selector to drop; the parent/epic probe is separate (one
+ * tracker read per candidate) and stays with the offer, which runs it only
+ * for candidates the store-side exclusions did not already reject.
+ */
+function toSpecPoolFromSnapshot(
+  issues: readonly ReadyIssue[],
+  project: ProjectConfig,
+): ToSpecCandidateView[] {
+  const queueLabel = project.queueLabel;
+  const parkLabel = project.stateLabels.backlog;
+  const { labelPrefix, repos } = project.routing;
+  const views: ToSpecCandidateView[] = [];
+  for (const issue of issues) {
+    if (issue.labels.includes(queueLabel)) continue;
+    const matched = [...new Set(issue.labels.filter((l) => l.startsWith(labelPrefix)))];
+    if (matched.length !== 1) continue;
+    const key = matched[0]!.slice(labelPrefix.length);
+    const target = Object.hasOwn(repos, key) ? repos[key]! : undefined;
+    if (target === undefined) continue;
+    views.push({
+      issue: issue.number,
+      title: issue.title,
+      routing: repoSlugFor(target),
+      parked: issue.labels.includes(parkLabel) ? true : undefined,
+    });
+  }
+  views.sort((a, b) => a.issue - b.issue);
+  return views;
+}
+
+/**
+ * The production launch offer for one tick: the complete mechanical
+ * selection, from the authoritative tracker snapshot through every
+ * exclusion, ending in the token + block + allowlist, or `undefined` when no
+ * batch may launch. All of the following yield `undefined`:
+ *
+ *  - no dispatch row yet, or the routable queue is at/above the grooming
+ *    trigger (the same gate the queue digest uses);
+ *  - no tracker seam (the snapshot is unavailable);
+ *  - the snapshot cannot be read — the launch fails closed rather than
+ *    trusting the model to self-filter parked/parent/epic candidates;
+ *  - nothing survives the exclusions (parked, parent/epic, already groomed,
+ *    in-flight, lane/dependency holds, dispatched runs) — there is then no
+ *    batch to authorize, and a marker-bearing `task` call stays refused.
+ *
+ * The parent/epic probe runs only for candidates the store-side exclusions
+ * have not already rejected, in issue order, and stops as soon as
+ * {@link TO_SPEC_BATCH_MAX} candidates are selected — a bounded set of
+ * tracker reads per low-queue tick, never one per open issue.
+ */
+export async function offerToSpecLaunch(input: {
+  summary: DispatchSummary | undefined;
+  groomBelow: number;
+  grooming: readonly GroomingRecord[];
+  active: readonly { issue: number }[];
+  project: ProjectConfig;
+  trackerSeam: ToSpecTrackerSeam | undefined;
+  /** An open-issue snapshot this tick already read from the tracker. Shared
+   *  with the queue digest so one tick cannot describe two queues (#848);
+   *  absent when that read failed, in which case the launch retries its own
+   *  read and fails closed on the same terms as before. */
+  issues?: readonly ReadyIssue[];
+  now: number;
+}): Promise<ToSpecLaunchBlock | undefined> {
+  if (input.summary === undefined) return undefined;
+  if (input.summary.routed >= input.groomBelow) return undefined;
+  const seam = input.trackerSeam;
+  if (seam === undefined) return undefined;
+  let issues = input.issues;
+  if (issues === undefined) {
+    try {
+      issues = await seam.listOpenIssues(input.project);
+    } catch {
+      // No authoritative snapshot, no launch: a batch offered without one would
+      // make the model the selector, which is exactly the defect this slice
+      // removes. The queue digest still names the grooming duty; the next tick
+      // retries the read.
+      return undefined;
+    }
+  }
+  const views = toSpecPoolFromSnapshot(issues, input.project);
+  const groomingByIssue = new Map(input.grooming.map((row) => [row.issue, row]));
+  const activeIssues = new Set(input.active.map((run) => run.issue));
+  const pool: ToSpecCandidateView[] = [];
+  for (const view of views) {
+    if (view.parked) continue;
+    if (
+      toSpecCandidateExclusion(
+        { issue: view.issue },
+        { grooming: groomingByIssue.get(view.issue), active: activeIssues.has(view.issue) },
+        input.now,
+      ) !== undefined
+    ) {
+      continue;
+    }
+    let children: { number: number; state: IssueState }[];
+    try {
+      children = await seam.childrenOf(input.project, view.issue);
+    } catch {
+      continue;
+    }
+    if (children.length > 0) continue; // parent/epic with sub-issues: no runnable slice
+    pool.push(view);
+    if (pool.length >= TO_SPEC_BATCH_MAX) break;
+  }
+  // The one shared rule set re-runs on the tracker-vetted pool, so the pure
+  // selector — not a prose instruction — answers what the block authorizes.
+  const selected = selectToSpecBatch({
+    candidates: pool,
+    summary: input.summary,
+    groomBelow: input.groomBelow,
+    grooming: input.grooming,
+    active: input.active,
+    now: input.now,
+  });
+  if (selected.length === 0) return undefined;
+  return toSpecLaunchBlock({
+    summary: input.summary,
+    groomBelow: input.groomBelow,
+    grooming: input.grooming,
+    active: input.active,
+    tracker: input.project.tracker.repo,
+    queueLabel: input.project.queueLabel,
+    labelPrefix: input.project.routing.labelPrefix,
+    parkLabel: input.project.stateLabels.backlog,
+    selected,
+    now: input.now,
+  });
+}
+
+/**
+ * The per-tick launch block. Present exactly when a batch may be launched:
+ * the queue is below the grooming trigger (`summary.routed < groomBelow`),
+ * a dispatch row exists, and the mechanical selection produced at least one
+ * candidate. The block names the selected candidates as the ONLY batch this
+ * tick authorizes and lists every store-proven exclusion the selection
+ * already applied; the `tool_call` gate refuses any item outside the list.
+ */
+export function toSpecLaunchBlock(input: {
+  summary: DispatchSummary | undefined;
+  groomBelow: number;
+  grooming: readonly GroomingRecord[];
+  active: readonly { issue: number }[];
+  tracker: string;
+  queueLabel: string;
+  labelPrefix: string;
+  parkLabel: string;
+  /** The mechanically selected candidates the block renders and authorizes. */
+  selected: readonly ToSpecCandidateView[];
+  now: number;
+}): ToSpecLaunchBlock | undefined {
+  if (input.summary === undefined) return undefined;
+  if (input.summary.routed >= input.groomBelow) return undefined;
+  if (input.selected.length === 0) return undefined;
+  const exclusions: ToSpecLaunchExclusions = { groomed: [], inFlight: [], mechanicallyBlocked: [], dispatched: [] };
+  for (const row of input.grooming) {
+    if (row.reason === TO_SPEC_IN_FLIGHT_REASON) {
+      if (input.now - row.recordedAt <= TO_SPEC_IN_FLIGHT_TTL_MS) exclusions.inFlight.push(`#${row.issue}`);
+    } else if (row.reason === "file-lane" || row.reason === "depends-on") {
+      exclusions.mechanicallyBlocked.push(`#${row.issue} (${row.reason})`);
+    } else {
+      const result = parseToSpecEvidence(row.evidence);
+      if (result !== undefined && input.now - result.source.freshAt <= TO_SPEC_MAX_SOURCE_AGE_MS) {
+        exclusions.groomed.push(
+          `#${row.issue} (${result.verdict} @ ${result.source.ref}, observed ${new Date(result.source.freshAt).toISOString()})`,
+        );
+      }
+    }
+  }
+  for (const run of input.active) exclusions.dispatched.push(`#${run.issue}`);
+  const token = randomUUID();
+  const items: ToSpecLaunchItem[] = input.selected.map((candidate) => ({
+    issue: candidate.issue,
+    routing: candidate.routing,
+    title: candidate.title,
+  }));
+  const candidates = items.map((item) => `- #${item.issue} (${item.routing}) — ${item.title}`).join("\n");
+  const lines = [
+    `## Bounded to-spec grooming batch (${TO_SPEC_BATCH_MARKER}, #777)`,
+    "",
+    `The routable queue is below the grooming trigger of ${input.groomBelow} (${input.summary.routed} routable). ` +
+      "Duty 2's finding is now a strict contract: launch EXACTLY ONE native `task` batch this turn with the " +
+      `\`${TO_SPEC_AGENT}\` agent — never a second batch, never an improvised scout.`,
+    "",
+    "The conductor selected this batch mechanically from the live open-issue snapshot " +
+      `(issues carrying \`${input.queueLabel}\`, the \`${input.parkLabel}\` park label, issues without exactly one ` +
+      `\`${input.labelPrefix}<repo>\` routing label, parent/epic issues with sub-issues, ` +
+      "already-groomed, in-flight, lane/dependency-blocked and dispatched candidates were excluded):",
+    candidates,
+    "Excluded this tick — " +
+      `already-groomed: ${exclusions.groomed.length === 0 ? "none" : exclusions.groomed.join(", ")}; ` +
+      `in-flight batches — ${exclusions.inFlight.length === 0 ? "none" : exclusions.inFlight.join(", ")}; ` +
+      `mechanically blocked: ${exclusions.mechanicallyBlocked.length === 0 ? "none" : exclusions.mechanicallyBlocked.join(", ")}; ` +
+      `dispatched now: ${exclusions.dispatched.length === 0 ? "none" : exclusions.dispatched.join(", ")}.`,
+    "",
+    "To launch it:",
+    "",
+    `1. For each candidate above, render \`omp/src/briefs/to-spec.md\` with its placeholders — {{TRACKER_REPO}}, ` +
+      "{{ISSUE_NUMBER}}, {{CANDIDATE_TITLE}}, {{ISSUE_BODY}} (read via `gh issue view <number> --repo " +
+      `${input.tracker}\`, never from memory), {{SOURCE}} = the candidate's routed repo, {{SOURCE_REF}} = that repo's \`` +
+      "current default-branch head, fetched now (`gh api repos/<repo>/branches/HEAD` or `git ls-remote`). Your item " +
+      "`task` MUST start with the two contract lines `to-spec candidate: <owner/repo>#<issue> — <title>` and " +
+      "`to-spec source: <owner/repo>@<ref>` — the `owner/repo` must match the routing named above.",
+    `2. Call \`task\` once with \`context\` whose first line is exactly \`${TO_SPEC_BATCH_MARKER}: ${token}\`, one ` +
+      `item per candidate above, in that order — no substitutes, no extra items (\`agent: "${TO_SPEC_AGENT}"\`; this ` +
+      "extension stamps the exact outputSchema/schemaMode on the way in and refuses a second batch this turn).",
+    `3. When each item completes, whether in the tool result or later as an async-result message, persist the agent's ` +
+      `exact raw output through the \`${TO_SPEC_RESULT_TOOL}\` tool — one call per completed item (\`issue\` + \`input\`), ` +
+      "success and failure alike: a malformed, source-less or stale result persists as blocked and must not discard " +
+      "successful siblings. Read the full output from its `agent://<id>` artifact when the inline text is truncated.",
+    `Never add \`${input.queueLabel}\`, never edit an issue or its labels. This batch produces verdicts only; ` +
+      "promotion stays your decision — the tool_call gate and the store own persistence, you own the queue.",
+    "",
+  ];
+  return { token, block: lines.join("\n"), items };
 }
 
 export const TICK_SCOPE_CONSTRAINTS: { readonly [K in ReportScopeChoice]: string } = {
@@ -2284,6 +3007,29 @@ interface TickSession {
   legacyArmLogged: boolean;
   /** The local tick whose agent loop is currently running, if any. */
   activeLocalTick?: ActiveLocalTick;
+  /**
+   * The to-spec launch token the last low-queue tick authorized (#777). Set
+   * when the tick appended a launch block; the `task` tool_call gate accepts
+   * exactly one batch echoing it and refuses a marker-bearing call without
+   * it (no authorized batch this tick), with a stale token, or after a batch
+   * was already accepted. Cleared at the start of every tick — healthy and
+   * low-queue alike — so a token minted on a low-queue tick can never be
+   * spent on a later healthy-queue tick; the tick that mints the next token
+   * sets it fresh with its own {@link TickSession.launchItems}.
+   */
+  launchToken?: string;
+  /** The project the {launchToken} authorization was minted for — the one
+   *  in-flight rows are recorded against. */
+  launchProject?: string;
+  /** The mechanically selected batch the current token authorizes: the gate
+   *  refuses any item whose issue or routing is not on this list, so parked,
+   *  parent/epic and other excluded candidates cannot be stamped in-flight
+   *  no matter what the model sends. */
+  launchItems?: ToSpecLaunchItem[];
+  /** The one batch this session's gate has let through, so a second attempt
+   *  this tick refuses, and the tool_result capture can match results to
+   *  items by index. */
+  launchedBatch?: { toolCallId: string; items: ToSpecBatchItem[] };
 }
 
 /**
@@ -2357,7 +3103,20 @@ async function ensureAskSurface(pi: TickApi, resolvable: boolean): Promise<boole
  * way. Skips are deliberately silent in the UI — a disarmed fleet would
  * otherwise emit a notification every interval, forever.
  */
-async function tick(pi: TickApi, ctx: TickContext, config: TickConfig, session: TickSession): Promise<void> {
+async function tick(
+  pi: TickApi,
+  ctx: TickContext,
+  config: TickConfig,
+  session: TickSession,
+  toSpecTrackerSeam: ToSpecTrackerSeam | undefined,
+): Promise<void> {
+  // A launch authorization belongs to one emitted tick only. Revoke it before
+  // any gate, config, store or tracker read so a skipped/degraded/healthy next
+  // tick cannot reuse a token minted by an earlier low-queue tick.
+  session.launchedBatch = undefined;
+  session.launchToken = undefined;
+  session.launchProject = undefined;
+  session.launchItems = undefined;
   const live = currentConfig(ctx.cwd, config);
   const arm = live.armedFile === undefined ? undefined : resolveArmState(live.armedFile, live.project);
   if (arm?.legacy === "stranded" && !session.legacyArmLogged) {
@@ -2602,13 +3361,92 @@ async function tick(pi: TickApi, ctx: TickContext, config: TickConfig, session:
           // so the resolved name is in hand and an un-named lookup would refuse
           // to guess on a host with a second project.
           const project = findProject(loadConfig(), scope.projectName);
+          const groomBelow = project.groomBelow ?? DEFAULT_GROOM_BELOW;
+          const dispatch = frictionStore.latestDispatch(scope.projectName);
+          const grooming = store.groomingVerdicts(projectName);
+          // #848: "the queue is empty / running dry" is the tracker's word, not
+          // the last dispatch pass's echo. One open-issue snapshot per tick,
+          // read live through the same authoritative tracker surface the
+          // to-spec launch uses, overlaid with the label_ops projection
+          // exactly as the dispatch pass judges eligibility — so a promotion,
+          // unblock or projection write after the last dispatch pass is
+          // visible on the very next tick even while a drain holds claiming.
+          // The digest consumes the overlay as the live inventory; the to-spec
+          // offer shares the same raw snapshot so one tick cannot describe two
+          // queues. If the tracker read fails, the digest falls back to
+          // explicitly dated wording (never a present-tense empty claim),
+          // and the offer retries its own read exactly as it did before.
+          //
+          // The read is made only for dispatch rows the digest could render:
+          // a healthy row (routed at/above the grooming threshold) emits no
+          // queue line at all, so no freshness check is spent on it and no
+          // stale claim can leak from it. A zero-ready row (or any row below
+          // the trigger) is exactly where the old wording lied, so every such
+          // tick reads the live queue.
+          const needsQueueRead =
+            dispatch !== undefined &&
+            (dispatch.ready === 0 || dispatch.routed === 0 || dispatch.routed < groomBelow);
+          let queueObservation: QueueObservation | undefined;
+          let openSnapshot: readonly ReadyIssue[] | undefined;
+          if (toSpecTrackerSeam !== undefined && needsQueueRead) {
+            try {
+              const open = await toSpecTrackerSeam.listOpenIssues(project);
+              openSnapshot = open;
+              const effective = open.map((issue) => {
+                const pending = store.pendingLabelOpsFor(projectName, issue.number);
+                return pending.length === 0
+                  ? issue
+                  : { ...issue, labels: effectiveLabels(issue.labels, pending) };
+              });
+              queueObservation = {
+                queued: effective.filter((issue) => issue.labels.includes(project.queueLabel)).length,
+                observedAt: now,
+              };
+            } catch {
+              // No current-queue evidence this tick: the digest below renders
+              // the dispatch row as dated history instead of claiming empty.
+            }
+          }
           const queue = queueDigestLine(
-            frictionStore.latestDispatch(scope.projectName),
+            dispatch,
             project.queueLabel,
             project.routing.labelPrefix,
-            project.groomBelow ?? DEFAULT_GROOM_BELOW,
+            groomBelow,
+            grooming,
+            queueObservation,
           );
           if (queue !== undefined) content = `${content}\n${queue}`;
+          // #777: the mechanical to-spec launch boundary. The queue digest is
+          // the trigger — the same below-`groomBelow` signal that already asks
+          // the orchestrator to groom — so the launch offer is composed beside
+          // it, from the same store read, and only when a dispatch row exists
+          // to prove the queue is genuinely low. The token it carries is the
+          // only authorization the `task` tool_call gate accepts this tick;
+          // absent a block (healthy queue, no dispatch, unreadable snapshot,
+          // nothing eligible) a task call with the batch marker is refused.
+          //
+          // Every tick owns its authorization fresh — the clears above ran
+          // before the reads, so the offer below can only mint for THIS tick.
+          const launch = await offerToSpecLaunch({
+            summary: dispatch,
+            groomBelow,
+            grooming,
+            active: store.activeRuns(projectName),
+            issues: openSnapshot,
+            project,
+            trackerSeam: toSpecTrackerSeam,
+            now,
+          });
+          if (launch !== undefined) {
+            content = `${content}\n${launch.block}`;
+            // A minted token authorizes exactly the batch this tick's block
+            // describes: the project and the allowlist are captured so the
+            // tool_call gate records in-flight rows against the same project
+            // the prompt named and refuses any item off the list.
+            session.launchProject = project.name;
+            session.launchToken = launch.token;
+            session.launchItems = launch.items;
+          }
           // Pending intake is the same class of standing block as the friction
           // and decisions read-outs: a store-backed duty the orchestrator must
           // not derive from memory. The store answers, the prompt instructs.
@@ -2619,7 +3457,7 @@ async function tick(pi: TickApi, ctx: TickContext, config: TickConfig, session:
           });
           if (pendingIntake !== undefined) content = `${content}\n${pendingIntake}`;
         } catch {
-          // unreadable config: no queue digest or pending-intake block this tick
+          // unreadable config: no queue digest, launch block, or pending-intake block this tick
         }
       } catch (err) {
         frictionStore?.close();
@@ -2780,11 +3618,17 @@ function writeTickRuntimeStatus(pi: TickApi, cwd: string, intervalSeconds: numbe
  * heartbeat interval keeps handing its promise to the harness, which routes
  * rejections to the extension error channel on its own.
  */
-function armTickHeartbeat(pi: TickApi, ctx: TickContext, config: TickConfig, session: TickSession): void {
+function armTickHeartbeat(
+  pi: TickApi,
+  ctx: TickContext,
+  config: TickConfig,
+  session: TickSession,
+  toSpecTrackerSeam: ToSpecTrackerSeam | undefined,
+): void {
   writeTickRuntimeStatus(pi, ctx.cwd, config.intervalSeconds);
   const runScheduledTick = async (): Promise<void> => {
     try {
-      await tick(pi, ctx, config, session);
+      await tick(pi, ctx, config, session, toSpecTrackerSeam);
     } finally {
       writeTickRuntimeStatus(pi, ctx.cwd, config.intervalSeconds);
     }
@@ -2840,7 +3684,7 @@ function armTickHeartbeat(pi: TickApi, ctx: TickContext, config: TickConfig, ses
   // call runs inside the session_start handler dispatch, which cannot see an
   // async rejection — an escaped one reaches the process-level
   // unhandledRejection handler and takes the session down.
-  void tick(pi, ctx, config, session).catch((err) => {
+  void tick(pi, ctx, config, session, toSpecTrackerSeam).catch((err) => {
     pi.logger.error(
       `[omp-conductor] arm-time tick failed: ${err instanceof Error ? err.message : String(err)}`,
     );
@@ -2884,6 +3728,303 @@ function armTickGuard(pi: TickApi, ctx: TickContext, budgetMs: number): void {
   });
 }
 
+/**
+ * The harness surface one to-spec batch travels through (#777): the `task`
+ * tool call the orchestrator makes (with the launch marker in `context`) and
+ * its result. `details` is the task tool's `TaskToolDetails` — declared here
+ * rather than imported, exactly like {@link TickApi}, because the harness is
+ * a peer dependency. A settled batch's `details.results` carries one entry
+ * per item; a background launch returns an empty `results` array and delivers
+ * each final result later as an async-result message, which the orchestrator
+ * routes through {@link TO_SPEC_RESULT_TOOL}.
+ */
+interface ToSpecTaskToolEvent {
+  toolName: string;
+  toolCallId: string;
+  input: Record<string, unknown>;
+  details: unknown;
+}
+
+/** One settled batch item, as `details.results` carries it. */
+interface ToSpecSettledItem {
+  /** The item's index inside the batch call. */
+  index?: unknown;
+  /** The agent's raw output — the exact text that must reach the parser. */
+  output?: unknown;
+  /** The harness's parsed structured output, when one exists. */
+  structuredOutput?: unknown;
+}
+
+/**
+ * The launch gate and result capture for one to-spec batch (#777). Armed at
+ * extension-factory time; inert until a low-queue tick mints a launch token.
+ *
+ * `tool_call` on `task`:
+ *  - a call without the {@link TO_SPEC_BATCH_MARKER} in `context` is the
+ *    orchestrator's own task use and passes untouched;
+ *  - a marker-bearing call is the conductor batch and is gated hard: it needs
+ *    this tick's exact token, the batch shape (1..{@link TO_SPEC_BATCH_MAX}
+ *    items, each starting with the two contract lines), unique items and
+ *    names, every item ON the tick's mechanically selected allowlist (issue
+ *    and routing — the parked/parent/epic exclusions are baked into that
+ *    list, so a forbidden candidate can never be stamped in-flight), and
+ *    store-side eligibility — the same {@link toSpecCandidateExclusion} rule
+ *    the prompt block's exclusion lines came from, so an item excluded in
+ *    prose is excluded in the gate for the same reason;
+ *  - on acceptance it stamps every item's `agent`, `outputSchema` and
+ *    `schemaMode` (the model never carries the schema itself), records the
+ *    durable in-flight rows through the #735 grooming table, and latches the
+ *    session so a second batch this tick refuses.
+ *
+ * `tool_result` on the accepted call captures a *settled* batch: every item
+ * is routed through {@link recordToSpecGrooming} independently, so a
+ * malformed or failed item persists `blocked` and its siblings survive. A
+ * background launch settles with no results here — its completed items arrive
+ * as async-result messages and are persisted through
+ * {@link TO_SPEC_RESULT_TOOL}.
+ */
+function armToSpecGate(pi: TickApi, session: TickSession): void {
+  const api = pi as TickApi & {
+    on(
+      event: "tool_call",
+      handler: (
+        event: { toolName: string; toolCallId: string; input: Record<string, unknown> },
+        ctx: unknown,
+      ) => { block: true; reason: string } | { input: Record<string, unknown> } | undefined,
+    ): void;
+    on(event: "tool_result", handler: (event: ToSpecTaskToolEvent, ctx: unknown) => void): void;
+  };
+
+  api.on("tool_call", (event) => {
+    if (event.toolName !== "task") return undefined;
+    const input = event.input;
+    const context = input["context"];
+    if (typeof context !== "string" || !context.includes(TO_SPEC_BATCH_MARKER)) return undefined;
+    // From here on this is a conductor grooming batch — the hard gate. Each
+    // refusal names the correction, because a blocked batch costs the tick a
+    // retry and the gate is meant to catch model error, not to hide it.
+    if (session.launchToken === undefined) {
+      return {
+        block: true,
+        reason:
+          `task refused: no to-spec batch is authorized this tick (` +
+          `only a low-queue tick's launch block names a ${TO_SPEC_BATCH_MARKER} token). ` +
+          "Run no batch this turn.",
+      };
+    }
+    if (session.launchedBatch !== undefined) {
+      return {
+        block: true,
+        reason: "task refused: this tick already launched its one to-spec batch. Wait for the results.",
+      };
+    }
+    const token = new RegExp(`${TO_SPEC_BATCH_MARKER}:\\s*(\\S+)`).exec(context)?.[1];
+    if (token !== session.launchToken) {
+      return {
+        block: true,
+        reason:
+          "task refused: the context token does not match the batch this tick authorized. " +
+          "Relaunch with the token named in this tick's launch block.",
+      };
+    }
+    const tasks = input["tasks"];
+    if (!Array.isArray(tasks) || tasks.length === 0 || tasks.length > TO_SPEC_BATCH_MAX) {
+      return {
+        block: true,
+        reason:
+          `task refused: a to-spec batch carries 1–${TO_SPEC_BATCH_MAX} items (one \`tasks[]\` call) — ` +
+          `got ${Array.isArray(tasks) ? tasks.length : "none"}.`,
+      };
+    }
+    const items: ToSpecBatchItem[] = [];
+    const names = new Set<string>();
+    for (const raw of tasks) {
+      if (typeof raw !== "object" || raw === null) {
+        return { block: true, reason: "task refused: every batch item must be an object." };
+      }
+      const item = parseToSpecItem((raw as Record<string, unknown>)["task"]);
+      if (item === undefined) {
+        return {
+          block: true,
+          reason:
+            "task refused: every item's `task` must start with the two contract lines " +
+            "`to-spec candidate: <owner/repo>#<issue> — <title>` and `to-spec source: <owner/repo>@<ref>`.",
+        };
+      }
+      const name = (raw as Record<string, unknown>)["name"];
+      if (typeof name === "string" && name.length > 0) {
+        if (names.has(name)) {
+          return { block: true, reason: `task refused: duplicate item name \`${name}\`.` };
+        }
+        names.add(name);
+      }
+      items.push(item);
+    }
+    for (let i = 1; i < items.length; i += 1) {
+      for (let j = 0; j < i; j += 1) {
+        if (items[j]!.issue === items[i]!.issue) {
+          return {
+            block: true,
+            reason: `task refused: #${items[i]!.issue} appears twice in one batch.`,
+          };
+        }
+      }
+    }
+    // The allowlist is the mechanical selection this tick's token authorized:
+    // every item's issue number AND routing must match an entry the launch
+    // offer produced from the authoritative tracker snapshot. Parked,
+    // parent/epic, already-groomed, in-flight, held and dispatched candidates
+    // were never on it, so no item carrying one can be stamped in-flight here
+    // — the model cannot self-select past the conductor's selection (#805).
+    const allowlist = session.launchItems;
+    if (allowlist === undefined) {
+      return {
+        block: true,
+        reason:
+          "task refused: this tick's launch did not carry a mechanically selected batch — " +
+          "re-tick before launching.",
+      };
+    }
+    for (const item of items) {
+      if (!allowlist.some((allowed) => allowed.issue === item.issue && allowed.routing === item.routing)) {
+        const listed = allowlist.map((allowed) => `#${allowed.issue} (${allowed.routing})`).join(", ");
+        return {
+          block: true,
+          reason:
+            `task refused: #${item.issue} is not on this tick's mechanically selected to-spec batch ` +
+            `(${listed}). Launch exactly the selected candidates, no substitutes.`,
+        };
+      }
+    }
+    const projectName = session.launchProject;
+    if (projectName === undefined) {
+      return {
+        block: true,
+        reason: "task refused: the batch was authorized without a project — re-tick before launching.",
+      };
+    }
+    // Store-side eligibility, the same rule the prompt block's exclusion list
+    // came from. Eligible items then become durable in-flight rows, so a
+    // crashed batch still suppresses re-launch until the TTL expires.
+    let store: Store | undefined;
+    try {
+      store = openStore(dbPath());
+      const byIssue = new Map(
+        store.groomingVerdicts(projectName).map((row) => [row.issue, row] as const),
+      );
+      const active = new Set(store.activeRuns(projectName).map((run) => run.issue));
+      const now = Date.now();
+      for (const item of items) {
+        const reason = toSpecCandidateExclusion(
+          { issue: item.issue },
+          { grooming: byIssue.get(item.issue), active: active.has(item.issue) },
+          now,
+        );
+        if (reason !== undefined) {
+          return {
+            block: true,
+            reason: `task refused: ${reason}. Drop that item (and every other listed exclusion) from this batch and re-call.`,
+          };
+        }
+      }
+      const launchedEvidence = JSON.stringify({
+        kind: "to-spec-in-flight",
+        launchedAt: now,
+        batch: token,
+        agent: TO_SPEC_AGENT,
+      });
+      for (const item of items) {
+        store.upsertGrooming({
+          project: projectName,
+          issue: item.issue,
+          verdict: "blocked",
+          reason: TO_SPEC_IN_FLIGHT_REASON,
+          evidence: launchedEvidence,
+          at: now,
+        });
+      }
+    } catch (err) {
+      pi.logger.error(
+        `[omp-conductor] to-spec launch not recorded: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return {
+        block: true,
+        reason: `task refused: the launch could not be recorded durably (${
+          err instanceof Error ? err.message : String(err)
+        }); nothing was started.`,
+      };
+    } finally {
+      store?.close();
+    }
+    const stampedTasks = tasks.map((raw) => ({
+      ...(raw as Record<string, unknown>),
+      agent: TO_SPEC_AGENT,
+      outputSchema: TO_SPEC_SCHEMA,
+      schemaMode: "strict",
+    }));
+    session.launchedBatch = { toolCallId: event.toolCallId, items };
+    pi.logger.info(
+      `[omp-conductor] to-spec batch launched: ${items.map((item) => `#${item.issue}`).join(", ")} (${token})`,
+    );
+    return { input: { ...input, tasks: stampedTasks } };
+  });
+
+  api.on("tool_result", (event) => {
+    if (event.toolName !== "task") return;
+    const batch = session.launchedBatch;
+    if (batch === undefined || event.toolCallId !== batch.toolCallId) return;
+    const projectName = session.launchProject;
+    if (projectName === undefined) return;
+    const details = event.details as { results?: unknown } | undefined;
+    const results = details?.results;
+    if (!Array.isArray(results) || results.length === 0) {
+      // Background launch: the settled items arrive later through
+      // TO_SPEC_RESULT_TOOL; the in-flight rows keep them out of any new batch
+      // until then.
+      return;
+    }
+    let store: Store | undefined;
+    try {
+      store = openStore(dbPath());
+      for (const entry of results) {
+        const settled = entry as ToSpecSettledItem;
+        const item = batch.items[typeof settled.index === "number" ? settled.index : -1];
+        if (item === undefined) continue;
+        // The raw output is the contract input — exactly as returned, even
+        // when the item failed: the strict parser turns anything unparseable
+        // into a blocked row, and a failed sibling never touches the others.
+        const raw = typeof settled.output === "string" ? settled.output : "";
+        const structured = settled.structuredOutput;
+        const fallback =
+          structured !== null &&
+          typeof structured === "object" &&
+          typeof (structured as { data?: unknown }).data === "object"
+            ? JSON.stringify((structured as { data?: unknown }).data)
+            : "";
+        try {
+          recordToSpecGrooming(store, {
+            project: projectName,
+            issue: item.issue,
+            input: raw.trim().length > 0 ? raw : fallback,
+          });
+        } catch (err) {
+          pi.logger.error(
+            `[omp-conductor] to-spec result not persisted for #${item.issue}: ${
+              err instanceof Error ? err.message : String(err)
+            }`,
+          );
+        }
+      }
+    } catch (err) {
+      pi.logger.error(
+        `[omp-conductor] to-spec results not captured: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    } finally {
+      store?.close();
+    }
+  });
+}
+
 /**
  * Factory-time seams for the extension, used by tests. Production runs
  * `orchestratorTickExtension(pi)` with no options and gets the module's own
@@ -2892,7 +4033,21 @@ function armTickGuard(pi: TickApi, ctx: TickContext, budgetMs: number): void {
  * through the real tool deterministically, without real timers (#683).
  */
 export interface OrchestratorTickExtensionOptions {
-  ask?: { wait?: (ms: number) => Promise<void>; now?: () => number };
+  ask?: {
+    wait?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** Injected interactive delivery surface (#722); production builds its own. */
+    interactive?: AskInteractiveDelivery;
+  };
+  /**
+   * The authoritative tracker surface the low-queue to-spec launch reads
+   * (#777). Production omits it and the extension builds the real seam over
+   * the existing Tracker adapter for each project; tests inject deterministic
+   * fakes so the mechanical selection is provable without a network. A
+   * low-queue launch without a readable snapshot is refused entirely — the
+   * launch fails closed rather than trusting the model to self-filter.
+   */
+  toSpec?: { tracker?: ToSpecTrackerSeam };
 }
 
 export default function orchestratorTickExtension(
@@ -2919,6 +4074,22 @@ export default function orchestratorTickExtension(
   let releaseGateArmed = false;
   let availabilityGateArmed = false;
   let guardArmed = false;
+  // #777: the to-spec launch gate is factory-time like the tick guard. It acts
+  // only when a low-queue tick has minted a launch token, so on any other
+  // session — or any healthy queue — it observes `task` calls without touching
+  // them.
+  armToSpecGate(pi, session);
+  // The authoritative tracker seam for the launch selection. Production runs
+  // without options and builds the real seam lazily over the existing Tracker
+  // adapter (one tracker per project read, per low-queue tick); tests inject a
+  // deterministic fake. The seam is the ONLY tracker surface the launch path
+  // touches — the tick never mutates tracker state and never lets the model
+  // self-select candidates.
+  const toSpecTrackerSeam: ToSpecTrackerSeam | undefined =
+    options.toSpec?.tracker ?? {
+      listOpenIssues: (project) => makeTracker(project).listOpenIssues(),
+      childrenOf: (project, issue) => makeTracker(project).childrenOf(issue),
+    };
   // The bounded ask tool's session state. The tool itself is registered at
   // extension-factory time, before any session exists, because OMP snapshots
   // the extension's active tool set before it emits `session_start` — a tool
@@ -3047,22 +4218,25 @@ export default function orchestratorTickExtension(
         }
         return;
       }
-      // The reply to an arming challenge lands here as an ordinary user turn. It
-      // must reach the transcript exactly as sent — the host's transcript scan
-      // (`armTicks`) is the backend proof, so it is left untouched — while the
-      // model gets a trusted, machine-readable steer about it, so it stops
-      // ad-libbing pairing-safety prose at a bare `FLEET-…` token (conductor
-      // #415). The classification derives from persisted authenticated
-      // pending-challenge state (hash + expiry, keyed by this project), never
-      // from the `FLEET-` prefix, so an unsolicited lookalike that matches no
-      // active challenge stays inert.
+      // The reply to an arming challenge lands here as an ordinary user turn.
+      // This adapter — not the model, and not any transcript scan — is the
+      // sole producer of the arming acknowledgement: it classifies the turn
+      // against persisted authenticated challenge state and, on a match,
+      // atomically records the challenge-id-specific acknowledgement the
+      // host-side `arm` waits on (conductor #614), all before normal model
+      // handling. The classification derives from the pending challenge (hash
+      // + expiry, keyed by this project), never from the `FLEET-` prefix, so
+      // an unsolicited lookalike that matches no active challenge stays inert
+      // and model behaviour cannot determine whether the host becomes armed.
+      // The turn itself still reaches the transcript exactly as sent, with the
+      // same trusted machine-readable steer as before (#415).
       if (message.role === "user" && message.synthetic !== true && message.attribution !== "agent") {
         const replyText =
           message.content
             ?.filter((part) => part.type === "text" && typeof part.text === "string")
             .map((part) => part.text as string)
             .join(" ") ?? "";
-        const proof = isActiveArmProof(configuredProject, replyText, Date.now());
+        const proof = acknowledgeArmReply(configuredProject, replyText, Date.now());
         if (session.activeLocalTick !== undefined) {
           session.activeLocalTick.humanWaiting = true;
           if (proof) session.activeLocalTick.armingProof = true;
@@ -3136,7 +4310,12 @@ export default function orchestratorTickExtension(
       `delivers it to the operator per the reporting policy, and waits at most the ceiling ` +
       `(default ${DEFAULT_ASK_TIMEOUT_SECONDS}s, capped at the turn budget; pass "timeoutSeconds" to ` +
       `shorten or extend within ${MIN_ASK_TIMEOUT_SECONDS}–${MAX_ASK_TIMEOUT_SECONDS}s — an ask issued without ` +
-      `one still gets the default). When nobody answers, the declared "on-timeout" decides: ` +
+      `one still gets the default). When the Telegram surface can, the question posts as selectable ` +
+      `buttons and a tap resolves the decision row with the chosen option; when it cannot, the ask ` +
+      `degrades to plain text and the row records the degraded delivery. "recommended" is required ` +
+      `whenever "on-timeout" is "auto-proceed" (the row must record what was auto-applied) and, when ` +
+      `"options" are supplied, must be one of their labels — the label as delivered, never an index. ` +
+      `When nobody answers, the declared "on-timeout" decides: ` +
       `"auto-proceed" applies your recommended option and resolves the decision row naming the ` +
       `auto-application ("<option> (auto-applied on ask timeout)"); "park" leaves the row open and ` +
       `pending — re-surfaced in every tick prompt until answered or the seven-day expiry — and you then ` +
@@ -3196,8 +4375,11 @@ export default function orchestratorTickExtension(
           turnBudgetSeconds: config.budgetSeconds ?? DEFAULT_TICK_BUDGET_SECONDS,
           // Test seam (#683): production omits `wait`/`now` and `performAsk`
           // falls back to the module's real-time defaults; a test that wants
-          // the timeout outcomes deterministically hands both in.
-          ...(options.ask === undefined ? {} : options.ask),
+          // the timeout outcomes deterministically hands both in. The
+          // interactive surface (#722) is production's default; a test may
+          // inject a fake through the same seam.
+          interactive: options.ask?.interactive ?? interactiveAskSurface({ project: projectConfig, store }),
+          ...(options.ask === undefined ? {} : { wait: options.ask.wait, now: options.ask.now }),
           deliver: async (text, category) => {
             const at = Date.now();
             const noticeId = randomUUID();
@@ -3237,6 +4419,114 @@ export default function orchestratorTickExtension(
     },
   });
 
+  // The async half of the to-spec result capture (#777). Registered at
+  // extension-factory time like {@link ASK_TOOL}, with the same routing
+  // contract: the state it needs (cwd + startup config) is filled by
+  // `session_start` for an accepted fleet session, and the live config is
+  // re-read at execution so a restamp binds the current project. The tool
+  // only ever writes the grooming table — never an issue, a label, or a
+  // dispatch row — so the output of a background batch persists while no
+  // candidate can become claimable from it.
+  pi.registerTool({
+    name: TO_SPEC_RESULT_TOOL,
+    label: TO_SPEC_RESULT_TOOL,
+    description:
+      `Persist the exact raw output of one completed to-spec grooming item (#777). ` +
+      `Call it once per completed batch item after the batch settles — in the tool ` +
+      `result, or when an async-result message delivers the item — passing the issue ` +
+      `number and the agent's EXACT raw output as \`input\` (read agent://<id> when the ` +
+      `inline text is truncated; never paraphrase). The conductor parses the output ` +
+      `against the strict to-spec contract and records the verdict durably: a valid ` +
+      `result persists its verdict, anything malformed, source-less or stale persists ` +
+      `as blocked, and a failing item never discards its siblings. One call per item, ` +
+      `success and failure alike; never edits an issue or a label.`,
+    parameters: {
+      type: "object",
+      properties: {
+        issue: { type: "integer", description: "The tracker issue number the item groomed." },
+        input: {
+          type: "string",
+          description: "The to-spec agent's exact raw output for this item.",
+        },
+      },
+      required: ["issue", "input"],
+      additionalProperties: false,
+    },
+    approval: "write",
+    execute: async (_toolCallId, params) => {
+      const fleet = askSession;
+      if (fleet === undefined) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${TO_SPEC_RESULT_TOOL}: not available in this session (no orchestrator tick); nothing was persisted.`,
+            },
+          ],
+          isError: true,
+        };
+      }
+      const issue = params["issue"];
+      const input = params["input"];
+      if (typeof issue !== "number" || !Number.isInteger(issue) || typeof input !== "string" || input.length === 0) {
+        return {
+          content: [
+            { type: "text", text: `${TO_SPEC_RESULT_TOOL}: expected an integer \`issue\` and a non-empty \`input\` string.` },
+          ],
+          isError: true,
+        };
+      }
+      const routed = resolveAskProject(fleet.cwd, fleet.config);
+      if (routed.kind === "error") {
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                `${TO_SPEC_RESULT_TOOL}: conductor config unreadable (${routed.problem}); nothing was persisted. ` +
+                "Keep the outputs in the transcript and persist after the config is repaired.",
+            },
+          ],
+          isError: true,
+        };
+      }
+      const store = openStore(dbPath());
+      try {
+        const outcome = recordToSpecGrooming(store, {
+          project: routed.project.name,
+          issue,
+          input,
+        });
+        const record = outcome.record;
+        const kept = outcome.kind === "kept-prior" ? " (kept the prior valid verdict)" : "";
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                `${TO_SPEC_RESULT_TOOL}: #${issue} persisted as ${record.verdict} (${record.reason})${kept}. ` +
+                "The grooming table now decides re-grooming; promotion stays yours.",
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${TO_SPEC_RESULT_TOOL}: could not persist #${issue}: ${
+                err instanceof Error ? err.message : String(err)
+              } — keep the output and retry the call.`,
+            },
+          ],
+          isError: true,
+        };
+      } finally {
+        store.close();
+      }
+    },
+  });
+
   pi.on("session_start", (_event, ctx) => {
     if (decided) return;
 
@@ -3358,7 +4648,7 @@ export default function orchestratorTickExtension(
         // not create or deliver decisions). `cwd` is for re-reading the live
         // tick config at execution, `config` for the startup-only ceiling.
         askSession = { cwd: ctx.cwd, config };
-        armTickHeartbeat(pi, ctx, config, session);
+        armTickHeartbeat(pi, ctx, config, session, toSpecTrackerSeam);
         if (!guardArmed) {
           guardArmed = true;
           armTickGuard(pi, ctx, (config.budgetSeconds ?? DEFAULT_TICK_BUDGET_SECONDS) * 1000);
@@ -3380,7 +4670,7 @@ export default function orchestratorTickExtension(
     // why): a declined or unresolved session keeps `askSession` undefined and
     // the tool fails closed.
     askSession = { cwd: ctx.cwd, config };
-    armTickHeartbeat(pi, ctx, config, session);
+    armTickHeartbeat(pi, ctx, config, session, toSpecTrackerSeam);
     if (!guardArmed) {
       guardArmed = true;
       armTickGuard(pi, ctx, (config.budgetSeconds ?? DEFAULT_TICK_BUDGET_SECONDS) * 1000);
@@ -3398,3 +4688,272 @@ export default function orchestratorTickExtension(
     );
   });
 }
+
+/** One error's message, for a reason string — never a stack. */
+function errText(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * Write one prompt-protocol file the way omp-telegram's `atomicJson` does:
+ * temp file in the same directory, then rename. The bridge reads these files
+ * on a hot path (every tap), so a half-written request must never be visible.
+ */
+function atomicallyWriteJson(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const tmp = `${path}.tmp-${process.pid}-${randomUUID().slice(0, 8)}`;
+  writeFileSync(tmp, `${JSON.stringify(value)}\n`, { mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+/** Remove one prompt file; a missing file is not an error. */
+function removeFile(path: string): void {
+  try {
+    rmSync(path, { force: true });
+  } catch {
+    // best effort — a leftover prompt request dies with its owner process
+  }
+}
+
+/**
+ * The interactive Telegram surface for one bounded ask (#722).
+ *
+ * `telegram_ask` posts its options as a Bot API inline keyboard whose taps the
+ * running omp-telegram bridge acknowledges and answers through a documented
+ * cross-process file protocol (guide.md: "prompts/ — Cross-process
+ * selectable-question requests (live while their owning session is) and their
+ * answers"): the asking process writes `<state>/prompts/<nonce>.json`, the
+ * bridge validates the tap against that request (responder, chat, topic,
+ * message id, owner-pid liveness) and writes `<nonce>.answer.json`; the asking
+ * process reads the envelope and settles. `interactiveAskSurface` is that
+ * asking-process half, nothing more: it posts the question with the same
+ * `qa:<nonce>:s:<index>` callbacks `prompts.ts` routes, writes the request file
+ * so the bridge recognizes the taps, and translates the envelope the bridge
+ * writes into the decision row — the resolution is the chosen option's *label*,
+ * never an index and never free text.
+ *
+ * The decision id doubles as the protocol nonce: it fits `[A-Za-z0-9_-]`, the
+ * bridge's callback regex, and makes the pending question and its answer
+ * addressable by the row that records them.
+ */
+export function interactiveAskSurface(deps: {
+  project: ProjectConfig;
+  store: Store;
+  /** Injected Bot API transport (tests); production posts to api.telegram.org. */
+  call?: (method: string, payload: Record<string, unknown>) => Promise<Record<string, unknown>>;
+  /** Injected state dir (tests); production resolves it like the token. */
+  stateDir?: string;
+  /** Injected bot token (tests); production reads the state dir's .env. */
+  token?: string;
+  now?: () => number;
+}): AskInteractiveDelivery {
+  const surfaceStateDir = deps.stateDir ?? telegramStateDir();
+  const call = deps.call ?? telegramCall(deps.token ?? readTelegramToken() ?? "");
+  const now = deps.now ?? Date.now;
+  // Where each pending question physically sits, so collect/close can settle
+  // the right message without re-reading the request file.
+  const posted = new Map<string, { chatId: string; messageId: number; settled: boolean }>();
+
+  const promptsDir = (): string => join(surfaceStateDir, "prompts");
+  const requestPath = (nonce: string): string => join(promptsDir(), `${nonce}.json`);
+  const answerPath = (nonce: string): string => join(promptsDir(), `${nonce}.answer.json`);
+
+  const ownerId = (): string | undefined => {
+    let raw: string;
+    try {
+      raw = readFileSync(join(surfaceStateDir, "access.json"), "utf8");
+    } catch {
+      return undefined;
+    }
+    let access: { allowFrom?: unknown };
+    try {
+      access = JSON.parse(raw) as { allowFrom?: unknown };
+    } catch {
+      return undefined;
+    }
+    const allowFrom = access.allowFrom;
+    if (!Array.isArray(allowFrom) || allowFrom.length !== 1 || typeof allowFrom[0] !== "string") {
+      return undefined;
+    }
+    return allowFrom[0];
+  };
+
+  const tokenAvailable = (): boolean =>
+    deps.call !== undefined || deps.token !== undefined || readTelegramToken() !== undefined;
+
+  return {
+    unavailableReason(request) {
+      const chat = deps.project.escalation.telegramChatId;
+      if (chat === undefined || chat === "") {
+        return "no escalation.telegramChatId configured for this project";
+      }
+      if (!tokenAvailable()) {
+        return "no Telegram bot token readable (install and configure omp-telegram, or set OMP_TELEGRAM_STATE_DIR)";
+      }
+      if (ownerId() === undefined) {
+        return "no paired Telegram owner (omp-telegram access.json must name exactly one allowed user)";
+      }
+      // The interactive post is still a delivery under the reporting policy: a
+      // question the policy would hold for the digest or the availability
+      // window must not bypass that hold just because it has buttons.
+      const disposition = interruptDisposition(
+        deps.project.reporting,
+        request.category ?? "decision-needed",
+        now(),
+      );
+      if (disposition !== "interrupt") {
+        return `the question defers under the reporting policy (${disposition}) — it must be held, not posted`;
+      }
+      return undefined;
+    },
+
+    async post(request, decisionId) {
+      const chat = deps.project.escalation.telegramChatId;
+      const owner = ownerId();
+      if (chat === undefined || owner === undefined) {
+        return {
+          ok: false,
+          reason: "the interactive surface is not configured (no escalation.telegramChatId or no paired owner)",
+        };
+      }
+      const render = renderInteractiveAsk(request, decisionId);
+      const threadId = resolveProjectTopicId(deps.project);
+      let result: Record<string, unknown>;
+      try {
+        result = await call("sendMessage", {
+          chat_id: chat,
+          ...(threadId === undefined ? {} : { message_thread_id: threadId }),
+          text: render.text,
+          reply_markup: render.markup,
+        });
+      } catch (err) {
+        return { ok: false, reason: `Telegram rejected the interactive question: ${errText(err)}` };
+      }
+      const messageId = result["message_id"];
+      const chatType =
+        typeof result["chat"] === "object" && result["chat"] !== null
+          ? String((result["chat"] as Record<string, unknown>)["type"] ?? "private")
+          : "private";
+      if (typeof messageId !== "number" || !Number.isSafeInteger(messageId)) {
+        // The question went out, but unaddressable — take it back rather than
+        // leaving a button row nothing can settle.
+        await call("deleteMessage", { chat_id: chat, message_id: messageId as number }).catch(
+          () => undefined,
+        );
+        return { ok: false, reason: "Telegram posted no usable message id" };
+      }
+      const recommended =
+        request.recommended === undefined
+          ? undefined
+          : (request.options ?? []).findIndex((option) => option.label === request.recommended);
+      const requestFile = {
+        version: 1,
+        nonce: decisionId,
+        responderId: owner,
+        chatId: chat,
+        chatType,
+        threadId,
+        page: 0,
+        messageId,
+        questions: [
+          {
+            id: "q1",
+            question: request.question,
+            options: request.options ?? [],
+            ...(recommended === undefined || recommended < 0 ? {} : { recommended }),
+          },
+        ],
+        questionIndex: 0,
+        answers: [],
+        selectedIndices: [],
+        awaitingText: (request.options ?? []).length === 0,
+        ownerPid: process.pid,
+      };
+      try {
+        atomicallyWriteJson(requestPath(decisionId), requestFile as unknown);
+      } catch (err) {
+        // The buttons went out but nothing would ever answer them — take the
+        // message back rather than leave a dead keyboard in the chat.
+        await call("deleteMessage", { chat_id: chat, message_id: messageId }).catch(() => undefined);
+        return { ok: false, reason: `could not register the interactive question: ${errText(err)}` };
+      }
+      posted.set(decisionId, { chatId: chat, messageId, settled: false });
+      return { ok: true };
+    },
+
+    collect(decisionId) {
+      const state = posted.get(decisionId);
+      if (state === undefined) return;
+      let raw: string | undefined;
+      try {
+        raw = readFileSync(answerPath(decisionId), "utf8");
+      } catch {
+        return; // no answer yet
+      }
+      let parsed: AskAnswerEnvelope | undefined;
+      try {
+        parsed = parseAskAnswerEnvelope(JSON.parse(raw) as unknown);
+      } catch {
+        parsed = undefined;
+      }
+      if (parsed === undefined) return; // an unreadable envelope is "no answer yet"
+      const write = askAnswerRowWrite(parsed);
+      if (write === undefined) return; // expiry/abort: the bounded wait still owns the row
+      deps.store.resolveDecision(decisionId, write.state, write.resolution, now());
+      removeFile(requestPath(decisionId));
+      removeFile(answerPath(decisionId));
+      state.settled = true;
+      const outcomeText =
+        write.state === "withdrawn"
+          ? write.resolution
+          : `User selected: ${write.resolution}`;
+      // The bridge edits its own prompts' messages; this surface owns the edit
+      // for its own, so an answered ask reads as answered and a stale tap
+      // finds no keyboard.
+      call("editMessageText", {
+        chat_id: state.chatId,
+        message_id: state.messageId,
+        text: outcomeText,
+        reply_markup: { inline_keyboard: [] },
+      }).catch(() => undefined);
+    },
+
+    close(decisionId) {
+      const state = posted.get(decisionId);
+      removeFile(requestPath(decisionId));
+      removeFile(answerPath(decisionId));
+      if (state !== undefined && !state.settled) {
+        call("editMessageReplyMarkup", {
+          chat_id: state.chatId,
+          message_id: state.messageId,
+          reply_markup: { inline_keyboard: [] },
+        }).catch(() => undefined);
+        state.settled = true;
+      }
+    },
+  };
+}
+
+/** The Bot API transport: one JSON POST per call, the `result` back. */
+function telegramCall(
+  token: string,
+): (method: string, payload: Record<string, unknown>) => Promise<Record<string, unknown>> {
+  return async (method, payload) => {
+    if (token === "") throw new Error("no Telegram bot token");
+    const url = `https://api.telegram.org/bot${token}/${method}`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+    const raw = await res.text();
+    if (!res.ok) {
+      throw new Error(`telegram ${method} failed: HTTP ${res.status} ${raw.slice(0, 200)}`);
+    }
+    const parsed = JSON.parse(raw) as { ok?: unknown; result?: unknown };
+    if (parsed.ok !== true) {
+      throw new Error(`telegram ${method} rejected: ${raw.slice(0, 200)}`);
+    }
+    return (parsed.result as Record<string, unknown>) ?? {};
+  };
+}