@nanobpm/nano-workforce 0.209.0 → 0.210.0

package/app/github.ts

@@ -716,7 +716,10 @@ export async function requestCopilotReview(
   const path = `repos/${repo}/pulls/${number}/requested_reviewers`;
   if (await useGh()) {
     try {
-      await runGh(["api", path, "-X", "POST", "-f", `reviewers[]=${COPILOT_REVIEWER}`]);
+      // `gh pr edit --add-reviewer @copilot` (issue #951): the REST POST with the bot login can add a
+      // `review_requested` event yet never start Copilot (`copilot_work_started` never appears); the
+      // gh-native @copilot reviewer path is the one that reliably triggers the review.
+      await runGh(["pr", "edit", String(number), "--repo", repo, "--add-reviewer", "@copilot"]);
       return "requested";
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
@@ -743,6 +746,73 @@ export async function requestCopilotReview(
   throw new Error(`github ${r.status} ${r.statusText}: ${(await r.text()).slice(0, 300)}`.trim());
 }
 
+/** Whether Copilot has STARTED working on a review request since `sinceIso` — a
+ * `copilot_work_started` event on the PR's issue timeline (issue #951). A request that produced
+ * `review_requested` but never `copilot_work_started` was silently dropped. `null` when no transport
+ * is usable or the read failed (unknown — callers must not treat it as "dropped").
+ *
+ * `opts.timeoutMs` bounds the WHOLE read (issue #951 review): the verification caller has a fixed
+ * deadline, so a stalled `gh` or REST read must not run past it and starve the BPMN review-wait
+ * timer. The `gh` path passes it to `runGh`'s process `timeout`; the REST path creates ONE
+ * `AbortSignal.timeout` before pagination and shares it across every page, so the whole walk —
+ * not each page — is bounded by the budget. A timeout surfaces as `null` (unknown), never `false`. */
+export async function hasCopilotWorkStarted(
+  repo: string,
+  number: number | string,
+  token: string,
+  sinceIso: string,
+  opts: { timeoutMs?: number } = {},
+): Promise<boolean | null> {
+  const path = `repos/${repo}/issues/${number}/timeline?per_page=100`;
+  try {
+    let events: { event?: string; created_at?: string }[];
+    if (await useGh()) {
+      const out = await runGh(
+        ["api", path, "--paginate", "--slurp", "-H", "Accept: application/vnd.github+json"],
+        opts.timeoutMs === undefined ? undefined : { timeoutMs: opts.timeoutMs },
+      );
+      // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+      events = (JSON.parse(out) as { event?: string; created_at?: string }[][]).flat();
+    } else {
+      if (!token) return null;
+      // Walk EVERY page (mirrors the `gh --paginate` path): a `copilot_work_started` beyond the first
+      // 100 events must not read as "never started". An incomplete read (non-OK page, or the page cap
+      // still advertising `rel="next"`) is UNKNOWN (`null`), never `false`.
+      const MAX_PAGES = 20;
+      const signal = opts.timeoutMs === undefined ? undefined : AbortSignal.timeout(opts.timeoutMs);
+      events = [];
+      for (let page = 1; page <= MAX_PAGES; page++) {
+        const r = await fetch(`https://api.github.com/${path}&page=${page}`, {
+          headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json" },
+          ...(signal === undefined ? {} : { signal }),
+        });
+        if (!r.ok) return null;
+        // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+        const batch = (await r.json()) as { event?: string; created_at?: string }[];
+        if (!Array.isArray(batch)) return null;
+        events.push(...batch);
+        const hasNext = /<[^>]*>;\s*rel="next"/.test(r.headers.get("link") ?? "");
+        if (!hasNext) break;
+        if (page === MAX_PAGES) return copilotWorkStartedSince(events, sinceIso) ? true : null;
+      }
+    }
+    return copilotWorkStartedSince(events, sinceIso);
+  } catch {
+    return null;
+  }
+}
+
+/** Pure: does the timeline carry a `copilot_work_started` at/after `sinceIso`? GitHub timeline
+ * timestamps have WHOLE-SECOND precision, so the lower bound is floored to the second — otherwise a
+ * start in the same second as a millisecond-precise request time would never count. */
+export function copilotWorkStartedSince(events: { event?: string; created_at?: string }[], sinceIso: string): boolean {
+  const parsed = Date.parse(sinceIso);
+  const since = Number.isNaN(parsed) ? parsed : Math.floor(parsed / 1000) * 1000;
+  return events.some(
+    (e) => e.event === "copilot_work_started" && (Number.isNaN(since) || Date.parse(e.created_at ?? "") >= since),
+  );
+}
+
 /** Withdraw a pending Copilot review request (REST reviewers DELETE). Used by the merge loop's
  * head-current review request (issue #939) when a prior request was silently ignored: Copilot stays
  * listed as pending but never reviews, and a second POST is a no-op — removing and re-adding it is
@@ -1631,6 +1701,32 @@ function requiredChecksVerdict(s: PrState, protocol?: MergeProtocol): "blocked"
   return "pass";
 }
 
+/** True for Mergify's merge-queue check run (e.g. "Mergify Merge Queue" / "Mergify — Merge Queue"). */
+export function isMergifyQueueCheck(name: string): boolean {
+  return /mergify/i.test(name) && /queue/i.test(name);
+}
+
+const SETTLED_OK_CONCLUSIONS = new Set(["SUCCESS", "SKIPPED"]);
+
+/** Issue #951: is this BLOCKED PR merely waiting for the repo's declared `mergify-queue` land step?
+ * True only when the protocol lands via `mergify-queue`, checks are enumerable and settled (none
+ * failing, none pending), and every non-SUCCESS/SKIPPED check is a Mergify queue check at NEUTRAL —
+ * with at least one such check present. Anything else keeps the conservative `waiting`. */
+export function awaitingMergifyEnqueue(s: PrState, protocol?: MergeProtocol): boolean {
+  if (protocol?.land.method !== "mergify-queue") return false;
+  if (s.failingChecks !== 0 || s.pendingCheckNames.length > 0) return false;
+  let sawMergifyNeutral = false;
+  for (const [name, conclusion] of Object.entries(s.checkConclusions)) {
+    if (SETTLED_OK_CONCLUSIONS.has(conclusion)) continue;
+    if (conclusion === "NEUTRAL" && isMergifyQueueCheck(name)) {
+      sawMergifyNeutral = true;
+      continue;
+    }
+    return false;
+  }
+  return sawMergifyNeutral;
+}
+
 export function classifyMergeability(s: PrState, protocol?: MergeProtocol): Mergeability {
   // A draft PR is NEVER landable — GitHub refuses the merge outright, whatever its checks say — so
   // draft outranks every other signal (issue #454). Surface it as a first-class verdict rather than
@@ -1723,6 +1819,11 @@ export function classifyMergeability(s: PrState, protocol?: MergeProtocol): Merg
           return "blocked";
         case "review-threads":
           return "review-threads";
+        case "reviews":
+          // Issue #951: on a `mergify-queue` repo a green, thread-free PR whose ONLY non-success
+          // check is Mergify's own queue check at NEUTRAL ("not queued yet") is waiting for the
+          // declared land step (`@mergifyio queue`), not a human review — land it.
+          return awaitingMergifyEnqueue(s, protocol) ? "ready" : "waiting";
         default:
           return "waiting";
       }
@@ -2321,3 +2422,38 @@ export async function ensurePromotionPr(
   if (!created) return null;
   return { ...created, created: true };
 }
+
+/** Bring a PR's head up to date with its base (GitHub's "Update branch" — `PUT
+ * /pulls/{n}/update-branch`, the API behind `gh pr update-branch`). `expectedHeadSha` pins the head
+ * the caller judged, so a concurrent push makes GitHub refuse (422) rather than merge base into a
+ * head nobody inspected. Returns whether GitHub accepted the update; never throws (best-effort —
+ * a refusal falls through to the caller's existing remediation). Issue #951. */
+export async function updatePrBranch(
+  repo: string,
+  number: number | string,
+  token: string,
+  expectedHeadSha: string | null,
+): Promise<boolean> {
+  const apiPath = `repos/${repo}/pulls/${number}/update-branch`;
+  try {
+    if (await useGh()) {
+      const args = ["api", "-X", "PUT", apiPath, "-H", "Accept: application/vnd.github+json"];
+      if (expectedHeadSha) args.push("-f", `expected_head_sha=${expectedHeadSha}`);
+      await runGh(args);
+      return true;
+    }
+    if (!token) return false;
+    const r = await fetch(`https://api.github.com/${apiPath}`, {
+      method: "PUT",
+      headers: {
+        authorization: `Bearer ${token}`,
+        accept: "application/vnd.github+json",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify(expectedHeadSha ? { expected_head_sha: expectedHeadSha } : {}),
+    });
+    return r.ok;
+  } catch {
+    return false;
+  }
+}

package/app/mergeLoopBehaviour.test.ts

@@ -523,6 +523,55 @@ test("the stall-round cap escalates to a human instead of looping forever (#636)
   assert(!completedElementIds(engine).has("mark-merged"), "an exhausted stall must not mark-merged");
 });
 
+test("an exhausted stall budget re-polls (not escalates) while a behind-base update is pending (#951)", async () => {
+  // The probe reports `waiting` + `updatePending: true` (an accepted update-branch still exposes the
+  // old head). The remedy's own bounded hold owns liveness, so `gw-merge-stall` must re-poll rather
+  // than escalate even with `mergeStallMax` spent.
+  const engine = await boot({
+    vars: { mergeStallMax: 0 },
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "waiting", updatePending: true, failingChecks: 0, failingChecksList: "" },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-mergeable-repoll");
+  assert(!completedElementIds(engine).has("merge-esc-conflict"), "a pending update must not escalate");
+});
+
+test("an exhausted stall budget still escalates an ordinary waiting verdict (#951)", async () => {
+  const engine = await boot({
+    vars: { mergeStallMax: 0 },
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "waiting", updatePending: false, failingChecks: 0, failingChecksList: "" },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-stall-probe", "merge-esc-conflict");
+});
+
+test("an exhausted stall budget whose probe re-reads a MERGED PR completes merged — never escalates (#951)", async () => {
+  // The probe re-reads PR state and surfaces `ready` for an already-merged PR (a human queued it while
+  // the loop waited). Even with the stall budget exhausted, `gw-merge-stall` must route a `ready`
+  // re-derivation to `attempt-merge` (whose already-merged short-circuit returns `merged`) rather
+  // than opening a "merge-blocked" escalation against a PR that has already landed.
+  const engine = await boot({
+    vars: { mergeStallMax: 0 },
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "ready", failingChecks: 0, failingChecksList: "" },
+      "pr.merge": { mergeStatus: "merged" },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .hasCompleted()
+    .hasNoIncident()
+    .hasCompletedElements("merge-stall-probe", "attempt-merge", "mark-merged");
+  assert(!completedElementIds(engine).has("merge-esc-conflict"), "a merged PR must never escalate");
+});
+
 // ---------------------------------------------------------------------------
 // Async-UNKNOWN "waiting" verdict → bounded re-poll, NOT a human (issue #774)
 // ---------------------------------------------------------------------------
@@ -1437,3 +1486,51 @@ test("an abandoned merge ends the whole instance via the root terminate, without
   const open = await engine.searchUserTasks({});
   assert(open.length === 0, "the root terminate must leave nothing running (no re-armed poller, no parked escalation)");
 });
+
+// Operator steering (issue #956 review): the merge-stage agents must carry the run's custom
+// instructions in their `appendPrompt` (e.g. a required commit email), and an agent echo must not
+// clear them for later re-arms.
+const STEER = "Commit as bot@example.test.";
+const STEER_BLOCK = `## Operator custom instructions\n\nThe operator supplied these instructions for this run — follow them:\n\n${STEER}`;
+
+for (const [jobType, mergeState, failingChecks, failingChecksList, status] of [
+  ["senior:fix-ci", "blocked", 1, "build", "fixed"],
+  ["senior:rebase", "conflict", 0, "", "rebased"],
+] as const) {
+  test(`${jobType} appendPrompt carries operator custom instructions; an echo cannot clear them (#956)`, async () => {
+    const prompts: string[] = [];
+    const engine = await boot({
+      vars: { customInstructions: STEER },
+      responses: {
+        "pr.merge-stall-probe": { mergeState, failingChecks, failingChecksList },
+        [jobType]: (job) => {
+          prompts.push(String(job.variables.appendPrompt ?? ""));
+          return { status, customInstructions: null };
+        },
+      },
+    });
+    await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+    await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+    assert(prompts.length >= 1, `${jobType} was never dispatched`);
+    assertStringIncludes(prompts[0], STEER_BLOCK);
+    assertStringIncludes(prompts[0], "Abort if cancelled");
+    assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasVariable("customInstructions", STEER);
+  });
+
+  test(`${jobType} appendPrompt omits the operator block when no instructions were seeded (#956)`, async () => {
+    const prompts: string[] = [];
+    const engine = await boot({
+      responses: {
+        "pr.merge-stall-probe": { mergeState, failingChecks, failingChecksList },
+        [jobType]: (job) => {
+          prompts.push(String(job.variables.appendPrompt ?? ""));
+          return { status };
+        },
+      },
+    });
+    await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+    await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+    assert(prompts.length >= 1, `${jobType} was never dispatched`);
+    assert(!prompts[0].includes("Operator custom instructions"), "absent instructions must not append the block");
+  });
+}

package/app/pullRequestReadModel.test.ts

@@ -33,7 +33,7 @@ import {
 const MIG = (name: string) => readFileSync(fileURLToPath(new URL(`../db/migrations/${name}`, import.meta.url)), "utf8");
 const PAGE = (name: string) => JSON.parse(readFileSync(fileURLToPath(new URL(`../pages/${name}`, import.meta.url)), "utf8"));
 
-const READ_MODEL_MIGRATION = "133_pull_requests_read_model_merge_policy.sql";
+const READ_MODEL_MIGRATION = "138_pull_requests_read_model_custom_instructions_text.sql";
 
 // The real base `pull_requests` columns, in schema order — DERIVED from the migration chain (not a
 // hand-kept list that could silently omit one), used by both the drift guard and the e2e stand-in.

package/app/service.test.ts

@@ -6,7 +6,7 @@
 // loop already guards in `startPlan`). Drives `submitPr` against an in-memory data layer with the
 // GitHub transport forced off so it is hermetic.
 import { test } from "node:test";
-import { assertEquals, assertRejects, assertStringIncludes } from "#test-assert";
+import { assert, assertEquals, assertRejects, assertStringIncludes } from "#test-assert";
 import { memDataFor } from "../test/worldDb.ts";
 import { withTrackingViews } from "../test/trackingViews.ts";
 import { DurableResumeRegistry } from "./durableResume.ts";
@@ -1627,6 +1627,130 @@ test("startMerge stamps the merge-stage policy on the row (issue #947)", async (
   });
 });
 
+// ── Issue #956 review: the operator-steering TEXT is durable and survives the merge handoff ──────
+// Copilot threads 4547353262 / 4547353302: the #956 projection carried only the boolean
+// `custom_instructions` flag — the TEXT lived solely on the convergence instance's variables, so
+// every re-enrollment path that re-enters `submitPr` without it (merge→reconvergence handoff,
+// `handoffWaitingMergeToConvergence`, the poller's feature-delivery re-enroll) silently dropped the
+// steering and reset the flag. The text is now persisted on the row (`custom_instructions_text`)
+// and re-seeded by `startMerge`, so a steered run stays steered across the whole lifecycle.
+
+test("submitPr persists the instruction TEXT on the row (insert path) (#956 review)", async () => {
+  await withGithubOff(async () => {
+    const { data, engine, stores } = captureRoot();
+    await submitPr(
+      data,
+      engine,
+      { repo: "owner/repo", number: 31, url: "https://github.com/owner/repo/pull/31", prKey: "owner/repo#31" },
+      [],
+      20,
+      false,
+      null,
+      false,
+      false,
+      undefined,
+      null,
+      null,
+      "  prefer Deno; keep the diff small  ",
+    );
+    const pr = stores.pull_requests.rows[0] as Record<string, unknown>;
+    assertEquals(pr.custom_instructions, 1, "the presence flag is stamped");
+    assertEquals(pr.custom_instructions_text, "prefer Deno; keep the diff small", "the TRIMMED text is durable on the row");
+  });
+});
+
+test("submitPr's run-scoped reopen carries a re-supplied text (and a handoff re-supplying the row's text keeps it) (#956 review)", async () => {
+  await withGithubOff(async () => {
+    const { data, engine, stores, vars } = captureRoot();
+    const parsed = { repo: "owner/repo", number: 32, url: "https://github.com/owner/repo/pull/32", prKey: "owner/repo#32" };
+    await submitPr(data, engine, parsed, [], 20, false, null, false, false, undefined, null, null, "steer me");
+    const firstVars = vars();
+    assertEquals(firstVars.customInstructions, "steer me", "the first submission seeds the steering");
+    // A merge→reconvergence handoff re-enters `submitPr` on the LIVE row, and by then the merge
+    // loop OWNS it (`startMerge` re-points `process_key` at the merge instance). Simulate that
+    // owner: without this, `handoffFrom: "PI-MERGE"` fails the live-owner gate and the call
+    // short-circuits as `alreadyRunning` — never exercising the reopen this test exists for.
+    const row = stores.pull_requests.rows[0] as Record<string, unknown>;
+    assertEquals(row.process_key, "PI-1", "the first submission owns the row");
+    row.process_key = "PI-MERGE";
+    const handedBack = await submitPr(
+      data,
+      engine,
+      parsed,
+      [],
+      20,
+      false,
+      null,
+      false,
+      true,
+      undefined,
+      "PI-MERGE",
+      null,
+      row.custom_instructions_text as string,
+    );
+    assertEquals(handedBack, { prKey: "owner/repo#32", processKey: "PI-1" }, "the owning merge loop's hand-back mints a SUCCESSOR, not alreadyRunning");
+    const after = stores.pull_requests.rows[0] as Record<string, unknown>;
+    assertEquals(after.custom_instructions, 1, "the flag survives the handoff reopen");
+    assertEquals(after.custom_instructions_text, "steer me", "the text survives the handoff reopen");
+    const successorVars = vars();
+    assertEquals(successorVars.customInstructions, "steer me", "the fresh convergence instance is re-seeded with the steering");
+    assert(successorVars !== firstVars, "a successor instance was actually created (not the first submission's captured variables)");
+    assertEquals(after.process_key, "PI-1", "the successor instance now owns the row (the fake engine mints PI-1 per capture)");
+  });
+});
+
+test("startMerge re-seeds the merge-loop instance with the row's custom instructions (#956 review)", async () => {
+  await withGithubOff(async () => {
+    const { data, engine, stores, vars } = captureRoot();
+    (stores.pull_requests.rows as unknown[]).push({
+      pr_key: "owner/repo#33",
+      repo: "owner/repo",
+      number: 33,
+      url: "https://github.com/owner/repo/pull/33",
+      status: "converged",
+      current_round: 2,
+      process_key: "PI-CONV",
+      merge_requested: 1,
+      merge_human_approval: 1,
+      custom_instructions: 1,
+      custom_instructions_text: "commit as josh.wulf@camunda.com",
+    });
+    await startMerge(data, engine, {
+      repo: "owner/repo",
+      number: 33,
+      url: "https://github.com/owner/repo/pull/33",
+      prKey: "owner/repo#33",
+      round: 2,
+    });
+    assertEquals(vars()?.customInstructions, "commit as josh.wulf@camunda.com", "the merge stage carries the steering (and a reconverge can re-read it)");
+  });
+});
+
+test("startMerge seeds customInstructions null on an unsteered row (prompts stay byte-identical)", async () => {
+  await withGithubOff(async () => {
+    const { data, engine, stores, vars } = captureRoot();
+    (stores.pull_requests.rows as unknown[]).push({
+      pr_key: "owner/repo#34",
+      repo: "owner/repo",
+      number: 34,
+      url: "https://github.com/owner/repo/pull/34",
+      status: "converged",
+      current_round: 1,
+      process_key: "PI-CONV",
+      custom_instructions: 0,
+      custom_instructions_text: null,
+    });
+    await startMerge(data, engine, {
+      repo: "owner/repo",
+      number: 34,
+      url: "https://github.com/owner/repo/pull/34",
+      prKey: "owner/repo#34",
+      round: 1,
+    });
+    assertEquals(vars()?.customInstructions ?? null, null, "no steering → null, never a blank string");
+  });
+});
+
 // The repository envelope drives the c8ctl harness's isolated workspace provisioning: it is
 // emitted under the reserved `io.nanobpm.agentTask` namespace with the PR head branch as the
 // checkout ref, and omitted entirely when the head branch couldn't be resolved (so the harness

package/app/service.ts

@@ -13,6 +13,7 @@ import { matchAdjudication, prAdjudications, resetAdjudications } from "./adjudi
 import { AGENT_SLA_JOB_TYPES, recordAgentJobObservation } from "./agentActivationLedger.ts";
 import { completeEscalationAutoApplied, escalationFormId } from "./agentCompletion.ts";
 import { AGENT_SLA_TIMEOUT } from "./agentSla.ts";
+import { maybeUpdateBehindBranch } from "./behindBaseRemedy.ts";
 import {
   CAPS_RESOLVED_MESSAGE,
   type CapabilityNeed,
@@ -442,6 +443,17 @@ export interface PullRequest {
   // rows fall back to the #937 batched engine read. Run-scoped: reset by the atomic reopen.
   merge_requested?: number | null;
   merge_human_approval?: number | null;
+  // Operator-steering projection (134_pull_requests_custom_instructions.sql, issue #956): 1 ⇒ this
+  // run's converge agents carry `customInstructions` (stamped by `submitPr` at submit/reopen, run-
+  // scoped like the merge policy), so `/status` shows the loop is steered with no engine read. NULL
+  // marks a row written before the projection existed; it reads as false.
+  custom_instructions?: number | null;
+  // The steering TEXT itself (136_pull_requests_custom_instructions_text.sql, issue #956 review):
+  // the boolean above can't re-seed a loop, so the trimmed instructions are durable on the row and
+  // every re-enrollment path (merge→reconvergence `pr.reconverge`, `handoffWaitingMergeToConvergence`,
+  // the poller's feature-delivery re-enroll) re-supplies them, and `startMerge` re-seeds the merge
+  // instance. Run-scoped with the flag; NULL when the run carries no steering.
+  custom_instructions_text?: string | null;
 }
 
 interface PrDependency {
@@ -668,9 +680,10 @@ export async function submitPr(
   autoMerge?: boolean,
   handoffFrom: string | null = null,
   headShaOverride: string | null = null,
+  customInstructions: string | null = null,
 ) {
   return withPrSubmitLock(parsed.prKey, () =>
-    submitPrCritical(data, engine, parsed, dependsOn, maxRounds, convergeOnly, rootRequestKey, humanApproval, autoResolveEscalations, autoMerge, handoffFrom, headShaOverride),
+    submitPrCritical(data, engine, parsed, dependsOn, maxRounds, convergeOnly, rootRequestKey, humanApproval, autoResolveEscalations, autoMerge, handoffFrom, headShaOverride, customInstructions),
   );
 }
 
@@ -687,6 +700,7 @@ async function submitPrCritical(
   autoMerge?: boolean,
   handoffFrom: string | null = null,
   headShaOverride: string | null = null,
+  customInstructions: string | null = null,
 ) {
   // Merge intent (issue #916): `autoMerge` is the CANONICAL positive form end to end — the same name
   // the feature/convergence-loop/plan-fanout doors accept. The legacy inverted `convergeOnly`
@@ -700,6 +714,13 @@ async function submitPrCritical(
   // merge-loop — its own predicate, `AUTO_MERGE && merge intent on`. A run that won't merge
   // (review-only, or the global switch off) must not park for a pointless approval.
   const gated = humanApproval && mergeIntent && AUTO_MERGE;
+  // Operator free-text steering for the converge agents (issue #956), mirrored from the feature path
+  // (feature.ts): blank/absent → null so the agent tasks' `appendPrompt` FEEL skips the "## Operator
+  // custom instructions" block rather than appending an empty heading — an omitted/blank value leaves
+  // every prompt byte-identical to no-instructions.
+  const instructions = typeof customInstructions === "string" && customInstructions.trim() !== ""
+    ? customInstructions.trim()
+    : null;
   const table = prs(data);
   const existing = await table.get(parsed.prKey);
   // ADR-0065: classify "already running" on the DERIVED terminal edge, not the base transient. A
@@ -874,6 +895,11 @@ async function submitPrCritical(
       // Mirror the engine seed EXACTLY (PR #950 review): an ungated loop is seeded
       // `humanApproval: false` (decided — no gate), a gated one `true` (outstanding).
       merge_human_approval: gated ? 1 : 0,
+      // Operator-steering projection (issue #956): 1 ⇒ this run's converge agents carry custom
+      // instructions, so `/status` can show the loop is steered with no engine read. The TEXT is
+      // durable alongside (issue #956 review) so a handoff/re-enrollment can re-supply it.
+      custom_instructions: instructions != null ? 1 : 0,
+      custom_instructions_text: instructions,
       created_at: ts,
       updated_at: ts,
     });
@@ -942,6 +968,11 @@ async function submitPrCritical(
       // review-round agent's prompt, so it can stop before pushing if the run is cancelled.
       abandonUrl: abUrl,
       abandonBrief: renderAbandonBrief(abUrl),
+      // Optional operator steering (issue #956): appended to EVERY converge round's agent prompt
+      // (review-round + adversarial-review) via their `appendPrompt` FEEL, under the same
+      // "## Operator custom instructions" block the implement cell uses. Null when none was supplied;
+      // persists on the instance, so reconverge re-dispatches and later rounds keep carrying it.
+      customInstructions: instructions,
       // Host-git provisioning (c8ctl): deliver the repository envelope so the `senior:pr-review`
       // harness clones an isolated workspace checked out on the PR head branch. Spread last so an
       // unresolved head (`{}`) leaves the other vars untouched.
@@ -980,6 +1011,9 @@ async function submitPrCritical(
         // authoritative (`stale: false`) in `/status`.
         merge_requested: existing.merge_requested ?? null,
         merge_human_approval: existing.merge_human_approval ?? null,
+        // The operator-steering projection (issue #956) rolls back with the same ownership.
+        custom_instructions: existing.custom_instructions ?? null,
+        custom_instructions_text: existing.custom_instructions_text ?? null,
       }
     : null;
   try {
@@ -1042,6 +1076,9 @@ async function submitPrCritical(
         // the fresh run's intent wins, and the approval state mirrors the fresh loop's `humanApproval` seed.
         merge_requested: mergeIntent ? 1 : 0,
         merge_human_approval: gated ? 1 : 0,
+        // Operator-steering projection (issue #956): run-scoped too — the fresh run's steering wins.
+        custom_instructions: instructions != null ? 1 : 0,
+        custom_instructions_text: instructions,
         // Publish the fresh run's identity in the SAME write as the status flip (may be null if the
         // instance could not be created — a phantom row a retry re-enrolls, as on first submit).
         process_key: processKey,
@@ -1113,6 +1150,14 @@ export async function startMerge(
   // self-rooted PR carries its own `pr_key`; `?? null` only tolerates a legacy row predating the
   // column.
   const rootRequestKey = existing?.root_request_key ?? null;
+  // Operator steering (issue #956 review): re-seed the merge-loop instance with the run's durable
+  // custom instructions. The convergence instance's own copy dies with it at the merge handoff, and
+  // the merge stage's `pr.reconverge` re-entry is one of the paths that must not drop the steering —
+  // carrying it here keeps the merge-stage agents (and any reconverge fallback) steered.
+  const customInstructions =
+    typeof existing?.custom_instructions_text === "string" && existing.custom_instructions_text.trim() !== ""
+      ? existing.custom_instructions_text.trim()
+      : null;
   const abUrl = abandonUrl(abandonToken);
   // Resolve the PR head branch so the merge agents (fix-ci, rebase) get an isolated clone checked
   // out on it (same host-git provisioning path as review-round). Best-effort: an unresolved head
@@ -1162,6 +1207,9 @@ export async function startMerge(
       reviewRequest: null,
       // Lineage (issue #245): thread the origin identity onto the merge instance (see startMerge).
       rootRequestKey,
+      // Operator steering (issue #956 review): the run's durable custom instructions, so the merge
+      // stage's agents and a `pr.reconverge` re-entry keep the steering the convergence loop ran with.
+      customInstructions,
       // Merge policy (issue #936): a merge loop only starts for a requested, approved merge. Seeding
       // the policy triple keeps it in /status's batched reads (no per-instance probes). Inert here —
       // the merge-loop process reads none of them.
@@ -1269,6 +1317,10 @@ export interface ActivePr {
   /** Whether this PR opted in to the escalation steward (issue #889) — its open escalations are
    * eligible for steward auto-resolution. Shown in `/status` per PR. */
   autoResolveEscalations: boolean;
+  /** Whether this run's converge agents carry operator custom instructions (issue #956), served
+   * from the durable `custom_instructions` row projection — the operator can see a loop is being
+   * steered with no engine read. */
+  hasCustomInstructions: boolean;
   /** The effective merge policy (issue #916): what the run intends (`requested`), what the
    * deployment allows (`enabled`), and what will actually happen (`effective`/`blockedBy`). */
   merge: MergePolicy;
@@ -1376,6 +1428,7 @@ export async function activePrs(
       activeWorker: p.active_worker ?? null,
       leaseUntil: p.lease_until ?? null,
       autoResolveEscalations: p.auto_resolve_escalations === 1,
+      hasCustomInstructions: p.custom_instructions === 1,
       merge: mergeByPr.get(p.pr_key) ?? mergePolicyDefault(),
       incident,
       terminationReason: p.termination_reason ?? null,
@@ -2325,6 +2378,10 @@ export async function handoffWaitingMergeToConvergence(
       pr.auto_resolve_escalations === 1,
       undefined,
       mergeKey,
+      // Operator steering (issue #956 review): re-supply the run's durable instruction text so the
+      // merge→convergence handoff never starts an unsteered replacement loop.
+      null,
+      typeof pr.custom_instructions_text === "string" ? pr.custom_instructions_text : null,
     );
     const successor = "processKey" in res ? res.processKey : null;
     if (successor == null) {
@@ -2646,6 +2703,12 @@ export async function pollMerges(data: DataLayer, engine: EngineClient, token: s
         );
         continue;
       }
+      if (verdict === "blocked" && (await maybeUpdateBehindBranch(repo, number, token, st, protocol))) {
+        // Issue #951: the checks failed on a head BEHIND its base (e.g. a CI-infra fix since landed on
+        // base) — update the branch (and reopen on a reopen-CI repo) and re-poll the fresh head
+        // instead of dispatching fix-ci / escalating "failing required checks". Once per head.
+        continue;
+      }
       if (verdict === "ready") {
         const lane = await mergeLaneDecisionForPr(data, prKey);
         if (lane?.isHeld) {
@@ -3863,6 +3926,12 @@ export async function pollFeatureDelivery(
             // Merge intent (issue #916): the canonical positive `autoMerge`, derived from the run's
             // durable `auto_merge` flag (mirrors `converge-feature`).
             run.auto_merge === 1,
+            // Operator steering (issue #956 review): the run's durable instruction text, so a
+            // poller-driven (re-)enrollment — which has no job variables — recovers the same
+            // steering the `converge-feature` worker would have forwarded.
+            null,
+            null,
+            typeof run.custom_instructions === "string" ? run.custom_instructions : null,
           );
         }
       }

package/build-info.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.209.0",
-  "gitSha": "21622b4529383c575de7ffcf77548a704353c4d4",
-  "gitTag": "v0.209.0",
-  "builtAt": "2026-11-12T05:08:52.210Z"
+  "version": "0.210.0",
+  "gitSha": "c1a72ce90744ccd23aa8160d20f0add2779db837",
+  "gitTag": "v0.210.0",
+  "builtAt": "2026-11-12T10:53:21.705Z"
 }

package/db/migrations/134_pull_requests_custom_instructions.sql

@@ -0,0 +1,8 @@
+-- Durable operator-steering projection for /status (issue #956). `startConvergenceLoop` accepts an
+-- optional `customInstructions` string that is appended to EVERY converge round's agent prompt
+-- (review-round + adversarial-review) via their `appendPrompt` FEEL. So the operator can SEE that a
+-- loop is being steered without an engine read, the writer that already knows — `submitPr`
+-- (submit/reopen) — stamps `custom_instructions` (1|0) on the row, and `/status` serves it as
+-- `hasCustomInstructions`. Run-scoped: the atomic reopen resets it to the fresh run's steering.
+-- `custom_instructions` is NULL on every pre-#956 row; those legacy rows read as false.
+ALTER TABLE pull_requests ADD COLUMN custom_instructions INTEGER;