@nanobpm/nano-workforce 0.200.8 → 0.201.0

package/app/implementEscalationReason.test.ts

@@ -0,0 +1,216 @@
+// Unit coverage for the implement-stage escalation reason builder (issue #865). The defect: the
+// implement-cell synthesised ONE generic "no machine-readable result (no status was reported)" reason
+// for every non-clean-terminal outcome — a FALSE diagnosis when the agent reported `status: "completed"`
+// with a summary but opened no PR. These tests pin the accurate, self-contained reason.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import {
+  AFFIRMATIVE_COMPLETION_STATUSES,
+  classifyImplementEscalation,
+  implementEscalationQuestion,
+  isClaimedCompletion,
+  NO_RESULT_QUESTION,
+  RECOGNIZED_IMPLEMENT_STATUSES,
+} from "./implementEscalationReason.ts";
+
+test("RECOGNIZED_IMPLEMENT_STATUSES is exactly the agent result vocabulary", () => {
+  assertEquals([...RECOGNIZED_IMPLEMENT_STATUSES].sort(), ["blocked", "escalated", "opened", "skipped"]);
+});
+
+test("isClaimedCompletion: ONLY an affirmative-completion alias is a claimed completion (#865 review)", () => {
+  // Affirmative-completion aliases → claimed completion.
+  assertEquals(isClaimedCompletion("completed"), true);
+  assertEquals(isClaimedCompletion("done"), true);
+  assertEquals(isClaimedCompletion("success"), true);
+  // Case-insensitive — an agent shouting `DONE`/`Completed` still claims completion.
+  assertEquals(isClaimedCompletion("Completed"), true);
+  assertEquals(isClaimedCompletion("DONE"), true);
+  // Non-affirmative off-vocabulary (failure / input-required / unknown) is NOT a completion claim:
+  // it must escalate accurately, never be adopted as success or retried with a false diagnosis.
+  assertEquals(isClaimedCompletion("failed"), false);
+  assertEquals(isClaimedCompletion("needs_input"), false);
+  assertEquals(isClaimedCompletion("error"), false);
+  assertEquals(isClaimedCompletion("wibble"), false);
+  // Recognised statuses and blanks are never claimed completions.
+  assertEquals(isClaimedCompletion("opened"), false);
+  assertEquals(isClaimedCompletion("escalated"), false);
+  assertEquals(isClaimedCompletion(null), false);
+  assertEquals(isClaimedCompletion("  "), false);
+  // The alias set is non-empty and stable.
+  assertEquals(AFFIRMATIVE_COMPLETION_STATUSES.has("completed"), true);
+});
+
+test("classifyImplementEscalation: blank → no-result; affirmative → completed-without-delivery; else → reported-status", () => {
+  assertEquals(classifyImplementEscalation(null), "no-result");
+  assertEquals(classifyImplementEscalation("  "), "no-result");
+  assertEquals(classifyImplementEscalation("completed"), "completed-without-delivery");
+  assertEquals(classifyImplementEscalation("done"), "completed-without-delivery");
+  // A reported `escalated` with no answerable question is NOT a no-result — it is a reported status
+  // (#865 review: the false "no status was reported" diagnosis is retired).
+  assertEquals(classifyImplementEscalation("escalated"), "reported-status");
+  // A non-affirmative off-vocabulary failure/input-required is a reported status, never a completion.
+  assertEquals(classifyImplementEscalation("failed"), "reported-status");
+  assertEquals(classifyImplementEscalation("needs_input"), "reported-status");
+});
+
+test("NO_RESULT_QUESTION: the blank-status reason names a true no-result, not a completion", () => {
+  assertEquals(NO_RESULT_QUESTION.includes("without a machine-readable result"), true);
+  assertEquals(NO_RESULT_QUESTION.includes('reported status "'), false);
+  // No summary/transcript folded in when none supplied.
+  assertEquals(NO_RESULT_QUESTION.includes("summary"), false);
+  assertEquals(NO_RESULT_QUESTION.includes("Transcript:"), false);
+});
+
+test("implementEscalationQuestion: a claimed completion names the exact status it reported", () => {
+  const q = implementEscalationQuestion({ status: "completed" });
+  assertEquals(q.includes('reported status "completed"'), true);
+  // It claims completion — but with no delivery evidence supplied the reason must NOT assert the
+  // unverified "...without delivering any work" (#865 review round 3).
+  assertEquals(q.includes("claimed completion"), true);
+  // Distinct from the generic no-result lead.
+  assertEquals(q.includes("without a machine-readable result"), false);
+});
+
+test("implementEscalationQuestion: a reported non-completion status names it accurately, never 'no status' or 'claimed completion' (#865 review)", () => {
+  // A reported `escalated` whose question was blank reaches the builder — it must NOT claim "no status
+  // was reported", and must NOT claim completion.
+  const esc = implementEscalationQuestion({ status: "escalated" });
+  assertEquals(esc.includes('reported status "escalated"'), true);
+  assertEquals(esc.includes("gave no answerable question"), true);
+  assertEquals(esc.includes("without a machine-readable result"), false);
+  assertEquals(esc.includes("claimed completion"), false);
+  // A non-affirmative off-vocabulary failure is reported accurately, not adopted as a completion claim.
+  const failed = implementEscalationQuestion({ status: "failed" });
+  assertEquals(failed.includes('reported status "failed"'), true);
+  assertEquals(failed.includes("claimed completion"), false);
+});
+
+test("implementEscalationQuestion: an agent's answerable question leads and PRESERVES its summary + transcript context (#865 review)", () => {
+  // The #865-review defect: an `escalated` result carrying a question + summary + transcript persisted
+  // ONLY the question, losing the supporting decision context pollUserTasks surfaces.
+  const q = implementEscalationQuestion({
+    status: "escalated",
+    question: "Should I target the epic base or main?",
+    summary: "drafted the migration but the base is ambiguous",
+    transcriptUrl: "http://merlin.local:3000/t?stream=job%3A777",
+  });
+  // The agent's own question leads.
+  assertEquals(q.startsWith("Should I target the epic base or main?"), true);
+  // Its summary and transcript are preserved as context.
+  assertEquals(q.includes('The agent\'s own summary: "drafted the migration but the base is ambiguous".'), true);
+  assertEquals(q.includes("Transcript: http://merlin.local:3000/t?stream=job%3A777"), true);
+  // No synthesised lead / recovery tail when the agent raised its own genuine escalation.
+  assertEquals(q.includes("without a machine-readable result"), false);
+  assertEquals(q.includes("/tmp/<repo>"), false);
+});
+
+test("implementEscalationQuestion: a blank/whitespace question does NOT lead — it synthesises accurately", () => {
+  const q = implementEscalationQuestion({ status: "completed", question: "   " });
+  assertEquals(q.includes('reported status "completed"'), true);
+  assertEquals(q.includes("/tmp/<repo>"), true); // recovery tail present on the synthesised path
+});
+
+test("implementEscalationQuestion: folds in the agent's own summary and the transcript link (#863)", () => {
+  const q = implementEscalationQuestion({
+    status: "completed",
+    summary: "implemented src/pin.rs and supporting changes",
+    transcriptUrl: "http://merlin.local:3000/app/api/agentic/transcripts?stream=job%3A123",
+  });
+  assertEquals(q.includes('The agent\'s own summary: "implemented src/pin.rs and supporting changes".'), true);
+  assertEquals(q.includes("Transcript: http://merlin.local:3000/app/api/agentic/transcripts?stream=job%3A123"), true);
+  // The workspace-confinement hint (#865 ask 3) is present.
+  assertEquals(q.includes("/tmp/<repo>"), true);
+});
+
+test("implementEscalationQuestion: a blank status with a summary surfaces the summary on the no-result lead", () => {
+  const q = implementEscalationQuestion({ status: null, summary: "did some work" });
+  assertEquals(q.includes("without a machine-readable result"), true);
+  assertEquals(q.includes('The agent\'s own summary: "did some work".'), true);
+});
+
+// --- Issue #865 review (round 3): never assert UNVERIFIED delivery -------------------------------
+// The synthesised reason must not claim "no adoptable pull request was found" from status alone. Two
+// unverified cases must be worded as unverified:
+//   (a) a preserved PR is still in scope (an `escalated`/`failed` with a blank question retains its PR
+//       without any GitHub lookup) — the builder must NOT say "opened no pull request";
+//   (b) the GitHub lookup never confirmed delivery state (it threw, or the transport was unavailable)
+//       — the builder must NOT assert a verified absence.
+// Only a SUCCESSFUL lookup that found no adoptable PR may assert "no adoptable pull request was found".
+//
+// --- Issue #865 review (round 4): a VERIFIED absence is only ever about an ADOPTABLE PR --------------
+// `deliveryVerified === true` means the reconcile lookup ran and found no open PR on the required base.
+// It does NOT check branch existence — a PR targeting the WRONG base leaves the `feat/<task.id>` branch
+// pushed. So the verified-absence wording must NEVER claim "pushed no branch" / "no branch" — only the
+// absence of an adoptable PR.
+
+test("implementEscalationQuestion: a preserved PR is surfaced, never the false 'opened no pull request' (#865 review)", () => {
+  // An `escalated` result with a blank question retains its PR (reconcile carries it through without a
+  // lookup). The reason must name that PR, not assert none was opened.
+  const q = implementEscalationQuestion({ status: "escalated", pr: "owner/repo#42" });
+  assertEquals(q.includes("owner/repo#42"), true);
+  assertEquals(q.includes("opened no pull request"), false);
+  assertEquals(q.includes("no adoptable pull request"), false);
+});
+
+test("implementEscalationQuestion: an unverified lookup (thrown / unavailable) does NOT assert a verified absence (#865 review)", () => {
+  // `completed` reached the builder after a thrown/unavailable lookup — delivery state is UNVERIFIED,
+  // so the reason must not claim a verified absence.
+  const q = implementEscalationQuestion({ status: "completed", deliveryVerified: false });
+  assertEquals(q.includes('reported status "completed"'), true);
+  assertEquals(q.includes("no adoptable pull request"), false);
+  // It still tells the human the delivery could not be confirmed.
+  assertEquals(q.includes("could not be confirmed"), true);
+});
+
+test("implementEscalationQuestion: a SUCCESSFUL lookup with no adoptable PR asserts the absence — but NEVER 'pushed no branch' (#865 review round 4)", () => {
+  // Only when the lookup succeeded and confirmed no adoptable PR may the reason say so. But the lookup
+  // checks only for an ADOPTABLE PR (open, on the required base) — it does NOT check branch existence,
+  // so a wrong-base PR leaves the branch pushed. The verified-absence wording must describe ONLY the
+  // missing adoptable PR, never claim the branch was not pushed.
+  const q = implementEscalationQuestion({ status: "completed", deliveryVerified: true });
+  assertEquals(q.includes("no adoptable pull request"), true);
+  // The regression the round-4 review cited: verified absence must not overstate the evidence.
+  assertEquals(q.includes("pushed no branch"), false);
+  assertEquals(q.includes("(and pushed no branch)"), false);
+});
+
+test("implementEscalationQuestion: an UNVERIFIED delivery never promises automatic adoption (#865 review round 6)", () => {
+  // For `failed`/`needs_input`/`escalated` with no answerable question and no reported PR,
+  // `shouldReconcileImplement()` skips the GitHub lookup entirely — so `deliveryVerified` is false and NO
+  // adoption attempt ran. The recovery text must NOT claim a delivered PR "would have been adopted
+  // automatically" (it was never even looked for, so a valid PR can sit unadopted). Instead it must ask
+  // the operator to check for an existing PR before re-running. This covers every non-affirmative
+  // reported status that bypasses reconciliation.
+  for (const status of ["failed", "needs_input", "escalated"]) {
+    const q = implementEscalationQuestion({ status, deliveryVerified: false });
+    assertEquals(q.includes("would have been adopted automatically"), false, `status=${status} must not promise automatic adoption`);
+    assertEquals(q.includes("check"), true, `status=${status} must direct the operator to check for an existing PR`);
+  }
+});
+
+test("implementEscalationQuestion: an UNVERIFIED delivery never falsely claims 'no lookup ran' (#865 review round 6b)", () => {
+  // `deliveryVerified === false` covers THREE paths in reconcileImplement: the reconciliation bypass
+  // (no lookup ran), the catch where the lookup THREW, and a `null` listing (transport unavailable). On
+  // the latter two a lookup WAS attempted, so the recovery text must say a lookup never CONFIRMED
+  // delivery — never the false blanket "no lookup ran" for an outcome where one did run.
+  for (const status of ["failed", "needs_input", "escalated", "completed"]) {
+    const q = implementEscalationQuestion({ status, deliveryVerified: false });
+    assertEquals(q.includes("No GitHub lookup ran"), false, `status=${status} must not claim no lookup ran`);
+    assertEquals(q.includes("No GitHub lookup confirmed delivery"), true, `status=${status} must frame the absence as unconfirmed`);
+  }
+});
+
+test("implementEscalationQuestion: a VERIFIED absence still promises automatic adoption (the lookup ran) (#865 review round 6)", () => {
+  // The verified branch is the one place the adoption promise IS accurate: a lookup ran and confirmed no
+  // adoptable PR, so a delivered PR on the right base genuinely would have been adopted. Guard the
+  // round-6 fix from over-correcting the verified wording away.
+  const q = implementEscalationQuestion({ status: "completed", deliveryVerified: true });
+  assertEquals(q.includes("adopted automatically"), true);
+});
+
+test("implementEscalationQuestion: default (no evidence supplied) stays unverified — no false verified absence", () => {
+  // Back-compat / safest default: with no delivery evidence the reason must not assert a verified
+  // absence. (The builder is pure; a caller that has not run a lookup passes no evidence.)
+  const q = implementEscalationQuestion({ status: "completed" });
+  assertEquals(q.includes("no adoptable pull request"), false);
+});

package/app/implementEscalationReason.ts

@@ -0,0 +1,213 @@
+// Implement-stage escalation reason — the single canonical builder for the human-facing escalation
+// text when an implement-cell slice reaches the escalation arm with no adoptable PR (issue #865).
+//
+// The defect #865 fixed: the shared `implement-cell` synthesised ONE generic reason — "finished
+// without a machine-readable result (no status was reported)" — for EVERY non-clean-terminal outcome.
+// But an agent that reported `status: "completed"` (an off-vocabulary status) with a summary, yet
+// opened no PR, DID report a status: the generic text was a false diagnosis the human had to untangle.
+// This module classifies the escalation precisely and always carries the agent's own `summary` and the
+// run's transcript link (cf. #863) so the human sees an accurate, self-contained reason.
+//
+// It is a pure, exhaustively-testable builder shared by `record-feature-escalation` (the escalation
+// recorder) so the reason can never drift between raise sites — the "one canonical implementation"
+// rule applied to the escalation text.
+import { hasAnswerableQuestion } from "./escalationTaxonomy.ts";
+
+/** The agent result vocabulary the implement-cell recognises (resources/prompts/feature.md). Any other
+ *  reported status is OFF-vocabulary: the agent reported an outcome the cell cannot route on.
+ *  `opened`/`blocked`/`skipped` are clean terminals the `ic_gw` "clean terminal?" gate converges before
+ *  the escalation arm; `escalated` is the agent's own answerable escalation. */
+export const RECOGNIZED_IMPLEMENT_STATUSES: ReadonlySet<string> = new Set([
+  "opened",
+  "blocked",
+  "skipped",
+  "escalated",
+]);
+
+/** The AFFIRMATIVE-completion aliases an agent reports off-vocabulary when it believes it SUCCEEDED
+ *  (feature.md names `completed`/`done`/`success` as the canonical examples of this mistake). ONLY these
+ *  off-vocabulary words claim completion. A non-affirmative off-vocabulary status — `failed`,
+ *  `needs_input`, `error`, or any unknown word — reports a FAILURE / INPUT-REQUIRED / UNKNOWN outcome,
+ *  NOT a completion: treating it as one would adopt a failure as success or auto-retry it with a false
+ *  "claimed completion" diagnosis (issue #865 review). This is the shared source of truth for "did the
+ *  agent CLAIM COMPLETION?" — `implementReconcile` reads it to decide whether to look for / retry a
+ *  delivered PR, and this module reads it to word the escalation accurately. Matched case-insensitively
+ *  so `Completed`/`DONE` are caught too. */
+export const AFFIRMATIVE_COMPLETION_STATUSES: ReadonlySet<string> = new Set([
+  "completed",
+  "complete",
+  "done",
+  "success",
+  "succeeded",
+  "finished",
+  "finish",
+]);
+
+const str = (v: unknown): string | undefined =>
+  typeof v === "string" && v.trim().length > 0 ? v.trim() : undefined;
+
+/** True iff `status` is a non-blank AFFIRMATIVE-completion alias (e.g. `completed`/`done`/`success`) —
+ *  the "claimed-completion-without-delivery" signal. A blank/absent status is NOT a claimed completion
+ *  (it is a no-result); a recognised status (`opened`/`escalated`/…) is the agent's own routed outcome;
+ *  and a non-affirmative off-vocabulary status (`failed`/`needs_input`/unknown) is a reported
+ *  failure/input-required/unknown outcome, NOT a completion claim (issue #865 review). */
+export function isClaimedCompletion(status: unknown): boolean {
+  const s = str(status);
+  return s !== undefined && AFFIRMATIVE_COMPLETION_STATUSES.has(s.toLowerCase());
+}
+
+/** The outcome the escalation reason distinguishes:
+ *  - `no-result` = blank/absent status — the agent returned nothing we can read;
+ *  - `completed-without-delivery` = an affirmative-completion alias was reported (the agent CLAIMED
+ *    completion) but no PR/branch was delivered;
+ *  - `reported-status` = some OTHER non-blank status reached the escalation arm with no answerable
+ *    question — a recognised status such as `escalated` whose question was blank, or a non-affirmative
+ *    off-vocabulary failure/input-required/unknown. It names the reported status accurately rather than
+ *    falsely claiming "no status was reported" (#865 review) or "claimed completion". */
+export type ImplementEscalationKind = "no-result" | "completed-without-delivery" | "reported-status";
+
+export function classifyImplementEscalation(status: unknown): ImplementEscalationKind {
+  const s = str(status);
+  if (s === undefined) return "no-result";
+  return isClaimedCompletion(s) ? "completed-without-delivery" : "reported-status";
+}
+
+/** What the escalation builder needs from the implement-step outcome. `question` is the agent's OWN
+ *  answerable question (when it raised a genuine escalation) — used as the lead when present; `summary`
+ *  is the agent's own one-line result (always surfaced when present); `transcriptUrl` is the run's
+ *  transcript link (cf. #863).
+ *
+ *  Delivery EVIDENCE (issue #865 review — never assert an UNVERIFIED delivery claim):
+ *  - `pr` is any PR key still in scope. An `escalated`/`failed` result with a blank question RETAINS its
+ *    PR (the reconcile step carries it through without a GitHub lookup), so when `pr` is set the reason
+ *    must NAME it — never the false "opened no pull request".
+ *  - `deliveryVerified` is whether a GitHub lookup actually CONFIRMED the delivery state. It is `true`
+ *    only when the reconcile step's lookup SUCCEEDED and found no adoptable PR — the one case where the
+ *    reason may say "no adoptable PR was found". It is `false`/absent when no lookup ran, the lookup
+ *    threw, or the transport was unavailable (a `null` listing): there the delivery state is UNVERIFIED,
+ *    so the reason says the delivery "could not be confirmed" rather than asserting an absence it never
+ *    checked. Note `deliveryVerified === true` verifies only the absence of an ADOPTABLE PR (an open PR
+ *    on the required base) — it does NOT check branch existence, so a wrong-base PR means the branch may
+ *    still be pushed; the reason never claims "pushed no branch" (#865 review). */
+export interface ImplementEscalationReasonInput {
+  status?: unknown;
+  question?: unknown;
+  summary?: unknown;
+  transcriptUrl?: unknown;
+  pr?: unknown;
+  deliveryVerified?: unknown;
+}
+
+// The lead sentence for a genuine no-result (blank status) — the agent returned nothing we can read.
+const NO_RESULT_LEAD =
+  "The implementation agent finished without a machine-readable result (no status was reported), so we cannot tell whether the slice succeeded.";
+
+// The delivery clause qualifies the lead with what is actually KNOWN about delivery (issue #865 review):
+//  - a preserved PR (`pr`) is NAMED — the agent may have delivered, so we never claim it opened none;
+//  - a VERIFIED absence (`deliveryVerified === true`: the reconcile lookup succeeded and found no
+//    adoptable PR) is the one case that may assert "no adoptable pull request was found". The lookup
+//    checks only for an ADOPTABLE PR (an open PR on the required base) — it does NOT check branch
+//    existence, so a wrong-base PR leaves the branch pushed; the clause never claims "pushed no branch";
+//  - anything else (no lookup ran, the lookup threw, or the transport was unavailable) is UNVERIFIED —
+//    the clause says delivery "could not be confirmed" rather than asserting an absence never checked.
+function deliveryClause(pr: string | undefined, deliveryVerified: boolean): string {
+  if (pr) return `it may already have a pull request open as ${pr} (preserved from the run, not re-verified)`;
+  if (deliveryVerified) return "a GitHub lookup confirmed no adoptable pull request was found for this slice on its base branch";
+  return "its delivery could not be confirmed (no GitHub lookup verified whether it opened a pull request or pushed a branch)";
+}
+
+// The lead sentence when the agent reported an affirmative-completion alias (e.g. `completed`) — it
+// claimed completion. The delivery clause states only what is verified about delivery (never an
+// unverified "opened no pull request"). Names the exact status so the human sees this is distinct from
+// a true no-result.
+const completedWithoutDeliveryLead = (status: string, delivery: string): string =>
+  `The implementation agent reported status "${status}" — it claimed completion — but ${delivery}.`;
+
+// The lead sentence when the agent reported SOME other status (a recognised `escalated` with a blank
+// question, or a non-affirmative off-vocabulary failure/input-required/unknown) and left no answerable
+// question. Names the exact reported status — never the false "no status was reported" diagnosis
+// (#865 review) — and does not claim completion. The delivery clause states only what is verified.
+const reportedStatusLead = (status: string, delivery: string): string =>
+  `The implementation agent reported status "${status}" and gave no answerable question, but ${delivery}, so we cannot tell whether the slice succeeded.`;
+
+// The shared tail: how recovery works, the workspace-confinement hint (#865 ask 3 — edits outside the
+// run workspace are discarded on teardown), and the two answers the cell's `ic_gw_answer` gateway routes
+// on. The delivery-absence clause is EVIDENCE-BASED (issue #865 review): only a verified lookup says
+// "no adoptable PR was found on the base branch" (it does NOT verify branch existence — a wrong-base PR
+// leaves the branch pushed, so it never claims "no branch"); an unverified delivery says so instead of
+// asserting an absence never checked. The automatic-adoption promise is likewise evidence-gated (#865
+// review round 6): only a VERIFIED lookup may say a delivered PR "would have been adopted automatically".
+// An UNVERIFIED outcome — the SAME three `deliveryVerified === false` cases `deliveryClause` names (a
+// reported non-completion status with no answerable question bypasses reconciliation so no lookup ran,
+// OR the lookup threw, OR the transport was unavailable) — must not promise an adoption that never
+// happened. Because the thrown/unavailable paths DID attempt a lookup, the wording says a lookup never
+// CONFIRMED delivery (not the false "no lookup ran"), and asks the operator to check for an existing PR
+// before re-running (#865 review round 6).
+function recoveryTail(pr: string | undefined, deliveryVerified: boolean): string {
+  const absence = pr
+    ? `A pull request may already be open as ${pr} — check and retarget or adopt it before re-running`
+    : deliveryVerified
+      ? "A delivered PR on the slice's `feat/<task.id>` branch targeting this run's base would have been adopted automatically; no adoptable PR was found on the base branch (the branch may still be pushed — e.g. a PR targeting a different base — so check and retarget it before re-running)"
+      : "No GitHub lookup confirmed delivery for this outcome, so a delivered PR on the slice's `feat/<task.id>` branch would NOT have been adopted automatically — check whether one already exists (and retarget or adopt it) before re-running";
+  return `${absence} (if the agent worked OUTSIDE its run workspace — e.g. \`cd /tmp/<repo>\` — those edits were discarded on teardown). Choose "Answer" and give guidance to re-run the slice — or choose "Abandon" to skip it and continue.`;
+}
+
+/** Build the accurate, self-contained escalation reason for an implement-cell slice that reached the
+ *  escalation arm. When the agent raised a GENUINE escalation (an answerable `question`), its own
+ *  question is the lead and its `summary`/transcript are folded in as the supporting decision context
+ *  (`pollUserTasks` surfaces this — #865 review). Otherwise it synthesises an accurate reason —
+ *  distinguishing a true no-result from a claimed-completion-without-delivery and from a reported
+ *  non-completion status — folds in the agent's own `summary` and the transcript link when present
+ *  (#863), and appends the recovery tail. Pure — the single canonical implementation
+ *  `record-feature-escalation` uses so the reason can never drift. */
+export function implementEscalationQuestion(input: ImplementEscalationReasonInput): string {
+  const question = str(input.question);
+  const summary = str(input.summary);
+  const transcriptUrl = str(input.transcriptUrl);
+
+  // The agent declared a genuine, answerable escalation: lead with its own question, then preserve its
+  // summary and transcript so the human has the full supporting context (#865 review — otherwise an
+  // `escalated` result's summary/transcript were dropped and only the bare question survived). No
+  // recovery tail here — this is the agent's own decision, not a missing-delivery recovery.
+  if (question && hasAnswerableQuestion(question)) {
+    return withContext([question], summary, transcriptUrl).join(" ");
+  }
+
+  // No answerable question — synthesise an accurate reason by outcome, fold in the context, then append
+  // the recovery tail (how a human recovers the slice). The delivery evidence (`pr` still in scope, and
+  // whether a lookup VERIFIED the delivery state) qualifies every delivery claim so the reason never
+  // asserts an UNVERIFIED absence (#865 review).
+  const status = str(input.status);
+  const pr = str(input.pr);
+  const deliveryVerified = input.deliveryVerified === true;
+  const delivery = deliveryClause(pr, deliveryVerified);
+  const parts = withContext([leadForKind(classifyImplementEscalation(status), status, delivery)], summary, transcriptUrl);
+  parts.push(recoveryTail(pr, deliveryVerified));
+  return parts.join(" ");
+}
+
+/** The lead sentence for a synthesised (no-answerable-question) escalation, by classified kind. The
+ *  `delivery` clause (built from the preserved PR + the verified-lookup flag) states only what is
+ *  actually known about delivery — never an unverified "opened no pull request" (#865 review). */
+function leadForKind(kind: ImplementEscalationKind, status: string | undefined, delivery: string): string {
+  switch (kind) {
+    case "no-result":
+      return NO_RESULT_LEAD;
+    case "completed-without-delivery":
+      return completedWithoutDeliveryLead(status ?? "", delivery);
+    case "reported-status":
+      return reportedStatusLead(status ?? "", delivery);
+  }
+}
+
+/** Append the agent's own summary and transcript link to an escalation reason when present (#863). */
+function withContext(parts: string[], summary: string | undefined, transcriptUrl: string | undefined): string[] {
+  if (summary) parts.push(`The agent's own summary: "${summary}".`);
+  if (transcriptUrl) parts.push(`Transcript: ${transcriptUrl}`);
+  return parts;
+}
+
+/** The generic no-result question (blank status, no summary, no transcript) — the stable default the
+ *  escalation recorder emits when the agent left nothing to read. Exported so the recorder and its tests
+ *  share one constant. */
+export const NO_RESULT_QUESTION: string = implementEscalationQuestion({});