@nanobpm/nano-workforce 0.209.1 → 0.210.1

package/app/readiness.test.ts

@@ -554,6 +554,95 @@ test("#856 parsePrTarget agrees with the canonical parsePr on every PR shape (no
   }
 });
 
+// ── PR #957 review round 3: the readiness `pr` path normalises events too ────────────────────────
+//
+// The `gh pr view` rollup omits `event`, so before this fix the readiness path grouped by name alone
+// and a green `push` run hid a red required `pull_request` run of the same name — `checks-green`
+// reported ready while the PR run was red. `probeOnce` now enriches the rollup through the injected
+// executor (shared transport logic with the merge loop) before parsing.
+
+test("#957 probeOnce pr checks-green: a green push run never hides a red pull_request run of the same name", async () => {
+  const head = "5fbd262a28987d647621da324bf1a7855a8da500";
+  // The `gh pr view` payload: two same-named runs, NO event on either (the CLI exporter omits it).
+  const prView = {
+    state: "OPEN",
+    mergedAt: null,
+    mergeStateStatus: "CLEAN",
+    isDraft: false,
+    headRefOid: head,
+    mergeCommit: null,
+    statusCheckRollup: [
+      { name: "build", conclusion: "FAILURE", status: "COMPLETED", startedAt: "2026-11-12T00:30:00Z", completedAt: "2026-11-12T00:41:34Z" },
+      { name: "build", conclusion: "SUCCESS", status: "COMPLETED", startedAt: "2026-11-12T00:41:30Z", completedAt: "2026-11-12T00:41:38Z" },
+    ],
+  };
+  // The GraphQL event read, keyed by the SAME head, joining by (name, startedAt).
+  const events = {
+    data: {
+      repository: {
+        pullRequest: {
+          commits: {
+            nodes: [
+              {
+                commit: {
+                  oid: head,
+                  statusCheckRollup: {
+                    contexts: {
+                      nodes: [
+                        { __typename: "CheckRun", databaseId: 1001, name: "build", startedAt: "2026-11-12T00:30:00Z", checkSuite: { workflowRun: { event: "pull_request" } } },
+                        { __typename: "CheckRun", databaseId: 1002, name: "build", startedAt: "2026-11-12T00:41:30Z", checkSuite: { workflowRun: { event: "push" } } },
+                      ],
+                      pageInfo: { hasNextPage: false, endCursor: null },
+                    },
+                  },
+                },
+              },
+            ],
+          },
+        },
+      },
+    },
+  };
+  const exec: ProbeExec = {
+    async httpGet() {
+      return { status: 0, body: "" };
+    },
+    async run(command) {
+      // Route the two reads by shape: the GraphQL call carries `api graphql`, the rollup read `pr view`.
+      if (command.includes("api") && command.includes("graphql")) return { code: 0, stdout: JSON.stringify(events), stderr: "" };
+      return { code: 0, stdout: JSON.stringify(prView), stderr: "" };
+    },
+  };
+  const p = parseProbe({ kind: "pr", target: "o/r#12", match: { prState: "checks-green" } });
+  const res = await probeOnce(p, exec, {});
+  assertEquals(res.ready, false, "the red pull_request run survives event normalisation — checks-green is NOT ready");
+  assertStringIncludes(res.detail, "failing");
+});
+
+test("#957 probeOnce pr checks-green: an event-enrichment failure degrades to name-only, never throws", async () => {
+  const prView = {
+    state: "OPEN",
+    mergedAt: null,
+    mergeStateStatus: "CLEAN",
+    isDraft: false,
+    headRefOid: "abc",
+    mergeCommit: null,
+    statusCheckRollup: [{ name: "build", conclusion: "SUCCESS", status: "COMPLETED", startedAt: "2026-11-12T00:41:30Z", completedAt: "2026-11-12T00:41:38Z" }],
+  };
+  const exec: ProbeExec = {
+    async httpGet() {
+      return { status: 0, body: "" };
+    },
+    async run(command) {
+      if (command.includes("api") && command.includes("graphql")) return { code: 1, stdout: "", stderr: "boom" }; // the event read fails
+      return { code: 0, stdout: JSON.stringify(prView), stderr: "" };
+    },
+  };
+  const p = parseProbe({ kind: "pr", target: "o/r#12", match: { prState: "checks-green" } });
+  const res = await probeOnce(p, exec, {});
+  assertEquals(res.ready, true, "a failed event read leaves the rollup event-less — a single green run is still green");
+});
+
 // ── #857: an epic target is a CANONICAL planKey (`owner/repo#N`) — never a URL ────────────────────
 // The epic probe keys off the durable lineage root (`owner/repo#N`, `parseIssue`'s `planKey` shape).
 // Delegating its validation to `parsePr` (whose grammar includes GitHub PR URLs) let a URL pass the
@@ -780,7 +869,7 @@ function prObs(over: Partial<PrObservation> = {}): PrObservation {
     totalChecks: 0,
     presentCheckNames: [],
     pendingCheckNames: [],
-    checkConclusions: {},
+    checkGateConclusions: {},
     isDraft: false,
     headRefOid: "abc123",
     mergedSha: null,

package/app/readiness.ts

@@ -18,7 +18,7 @@
 // any credential is read at execution time from the typed env-contract (`credentialEnv` names a
 // declared {@link EnvKey}; ADR 0004 pinned decision 2) and is redacted from every log line.
 import { isEnvKey, readEnv, readEnvOr } from "./contracts.ts";
-import { allCheckNames, checkConclusions, classifyMergeability, failingCheckNames, type PrState, pendingCheckNames } from "./github.ts";
+import { allCheckNames, applyRollupEvents, CHECK_EVENTS_QUERY, checkGateConclusions, classifyMergeability, failingCheckNames, type PrState, pendingCheckNames } from "./github.ts";
 import { parsePr } from "./prParse.ts";
 import { isoDuration, isoDurationToMs } from "./reviewWait.ts";
 
@@ -764,7 +764,7 @@ export function parsePrView(payload: unknown): PrObservation {
     totalChecks: rollup.length,
     presentCheckNames: allCheckNames(rollup),
     pendingCheckNames: pending,
-    checkConclusions: checkConclusions(rollup),
+    checkGateConclusions: checkGateConclusions(rollup),
     isDraft: j.isDraft === true,
     headRefOid: str(j.headRefOid).trim() || null,
     mergeQueueEntry: null, // readiness probe doesn't read native-queue membership (merge-loop-only signal)
@@ -857,6 +857,76 @@ export function prViewCommand(repo: string, number: string): string {
   return `gh pr view ${shellQuote(number)} --repo ${shellQuote(repo)} --json ${shellQuote("state,mergedAt,mergeStateStatus,statusCheckRollup,isDraft,headRefOid,mergeCommit")}`;
 }
 
+/** The GraphQL page query backing {@link enrichPrViewEvents}, as a single-quoted shell argument.
+ * Mirrors the merge loop's enrichment (`enrichRollupEvents` in `app/github.ts`) but runs through the
+ * probe's injected {@link ProbeExec} so the readiness path stays host-agnostic and unit-testable. */
+function prCheckEventsQuery(): string {
+  return CHECK_EVENTS_QUERY;
+}
+
+/** Enrich a `pr`-probe rollup with each run's triggering event, through the probe's injected
+ * executor. The `gh pr view --json statusCheckRollup` read omits `event`, so without this the
+ * readiness path groups by name alone and a green `push` run hides a red required `pull_request` run
+ * of the same name — `checks-green` then reports ready while the PR run is red (PR #957 review).
+ * Pages `statusCheckRollup.contexts` to exhaustion and pins the read to the rollup's head SHA
+ * (aborting the stamp when the head moved between the two reads), exactly like the merge loop's
+ * `enrichRollupEvents`. Never throws: any transport/parse failure leaves the rollup event-less. */
+async function enrichPrViewEvents(
+  exec: ProbeExec,
+  env: Record<string, string | undefined>,
+  repo: string,
+  number: string,
+  payload: Record<string, unknown>,
+): Promise<void> {
+  const j = payload;
+  if (!Array.isArray(j.statusCheckRollup) || j.statusCheckRollup.length === 0) return;
+  const rollup = j.statusCheckRollup;
+  const headSha = typeof j.headRefOid === "string" ? j.headRefOid : "";
+  const [owner, name] = repo.split("/");
+  const nodes: unknown[] = [];
+  let after: string | null = null;
+  for (;;) {
+    const args = [
+      "api",
+      "graphql",
+      "-f",
+      `query=${prCheckEventsQuery()}`,
+      "-f",
+      `o=${owner}`,
+      "-f",
+      `r=${name}`,
+      "-F",
+      `n=${number}`,
+    ];
+    if (after !== null) args.push("-f", `after=${after}`);
+    const command = `gh ${args.map(shellQuote).join(" ")}`;
+    const out = await exec.run(command, env);
+    if (out.code !== 0) return; // a transport hiccup leaves the rollup event-less (name-only gates)
+    const page = parseJson(out.stdout);
+    if (!isRecord(page)) return;
+    const data = isRecord(page.data) ? page.data : undefined;
+    const repository = data && isRecord(data.repository) ? data.repository : undefined;
+    const pullRequest = repository && isRecord(repository.pullRequest) ? repository.pullRequest : undefined;
+    const commits = pullRequest && isRecord(pullRequest.commits) ? pullRequest.commits : undefined;
+    const firstCommit = commits && Array.isArray(commits.nodes) ? commits.nodes[0] : undefined;
+    const commit = isRecord(firstCommit) && isRecord(firstCommit.commit) ? firstCommit.commit : undefined;
+    if (!isRecord(commit)) return;
+    // Head-pin: the rollup came from the earlier `gh pr view`; if the head moved since, these
+    // contexts belong to a different head — stamping them would join events across heads.
+    const oid = typeof commit.oid === "string" ? commit.oid : "";
+    if (headSha !== "" && oid !== "" && oid !== headSha) return;
+    const rollupObj = isRecord(commit.statusCheckRollup) ? commit.statusCheckRollup : undefined;
+    const contexts = rollupObj && isRecord(rollupObj.contexts) ? rollupObj.contexts : undefined;
+    if (contexts === undefined) return;
+    if (Array.isArray(contexts.nodes)) nodes.push(...contexts.nodes);
+    const pageInfo = isRecord(contexts.pageInfo) ? contexts.pageInfo : undefined;
+    const endCursor = pageInfo && typeof pageInfo.endCursor === "string" ? pageInfo.endCursor : "";
+    if (pageInfo?.hasNextPage !== true || endCursor === "") break;
+    after = endCursor;
+  }
+  applyRollupEvents(rollup, nodes);
+}
+
 // ── Epic / plan-fanout probe (issue #568 — gate a graph on an epic reaching "fully merged") ──────
 
 /** A live epic (plan-fanout) observation, reduced to the fields {@link matchEpic} reads. An nwf epic
@@ -974,7 +1044,15 @@ export async function probeOnce(
       if (!ref) return { ready: false, detail: "pr: unparseable target (not ready)" };
       const out = await exec.run(prViewCommand(ref.repo, ref.number), env);
       if (out.code !== 0) return { ready: false, detail: "pr: gh pr view failed (not ready)" };
-      return matchPr(probe.match, parsePrView(parseJson(out.stdout)));
+      const payload = parseJson(out.stdout);
+      if (!isRecord(payload)) return matchPr(probe.match, parsePrView(payload));
+      // Normalise each run's triggering event BEFORE parsing (PR #957 review): the `gh pr view`
+      // rollup omits `event`, so an un-enriched read groups by name alone and a green `push` run
+      // hides a red required `pull_request` run of the same name — `checks-green` would report
+      // ready while the PR run is red. Shared transport logic with the merge loop, over the
+      // injected executor.
+      await enrichPrViewEvents(exec, env, ref.repo, ref.number, payload);
+      return matchPr(probe.match, parsePrView(payload));
     }
     case "epic": {
       // "Fully merged" is the app's AGGREGATE, not a GitHub read — observe it over the app's own

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

@@ -443,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 {
@@ -669,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),
   );
 }
 
@@ -688,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`
@@ -701,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
@@ -875,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,
     });
@@ -943,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.
@@ -981,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 {
@@ -1043,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,
@@ -1114,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
@@ -1163,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.
@@ -1270,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;
@@ -1377,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,
@@ -2326,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) {
@@ -3870,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.1",
-  "gitSha": "5b70c1733cd919fcc8f43ca118a863d3714030ea",
-  "gitTag": "v0.209.1",
-  "builtAt": "2026-11-12T07:16:21.905Z"
+  "version": "0.210.1",
+  "gitSha": "e2c4e966b566ce8b4bdc19e84bceb130909a981c",
+  "gitTag": "v0.210.1",
+  "builtAt": "2026-11-12T12:00:58.232Z"
 }

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;

package/db/migrations/135_pull_requests_read_model_custom_instructions.sql

@@ -0,0 +1,52 @@
+-- Re-create the `pull_requests_read_model` VIEW so it re-exports the new base column (the VIEW must pass
+-- through EVERY base `pull_requests` column — app/pullRequestReadModel.test.ts DRIFT GUARD). A mechanical
+-- re-emission of 133 with `custom_instructions` (134, issue #956) added; the derived columns are emitted
+-- VERBATIM from app/pullRequestReadModel.ts and are unchanged. No BEGIN/COMMIT (the runner wraps each
+-- file). Numbered after 134.
+
+DROP VIEW IF EXISTS pull_requests_read_model;
+
+CREATE VIEW pull_requests_read_model AS
+SELECT
+  pr.pr_key AS pr_key,
+  pr.repo AS repo,
+  pr.number AS number,
+  pr.url AS url,
+  pr.title AS title,
+  COALESCE(pr.derived_status, pr.status) AS status,
+  pr.current_round AS current_round,
+  pr.process_key AS process_key,
+  pr.waiting_since AS waiting_since,
+  pr.last_review_id AS last_review_id,
+  pr.outcome AS outcome,
+  pr.created_at AS created_at,
+  pr.updated_at AS updated_at,
+  pr.converged_at AS converged_at,
+  pr.merged_at AS merged_at,
+  pr.active_worker AS active_worker,
+  pr.lease_until AS lease_until,
+  pr.last_nudge_at AS last_nudge_at,
+  pr.fresh_head_run_head AS fresh_head_run_head,
+  pr.abandon_token AS abandon_token,
+  pr.incident_key AS incident_key,
+  pr.incident_type AS incident_type,
+  pr.incident_since AS incident_since,
+  pr.incident_message AS incident_message,
+  pr.last_round_head AS last_round_head,
+  pr.last_progress_job_key AS last_progress_job_key,
+  pr.last_progress_result AS last_progress_result,
+  pr.last_progress_agent_watermark AS last_progress_agent_watermark,
+  pr.churn_escalated_round AS churn_escalated_round,
+  pr.root_request_key AS root_request_key,
+  pr.epic_phase_label AS epic_phase_label,
+  pr.acknowledged_at AS acknowledged_at,
+  pr.auto_resolve_escalations AS auto_resolve_escalations,
+  pr.termination_reason AS termination_reason,
+  pr.termination_process_key AS termination_process_key,
+  pr.retire_pending_key AS retire_pending_key,
+  pr.merge_requested AS merge_requested,
+  pr.merge_human_approval AS merge_human_approval,
+  pr.custom_instructions AS custom_instructions,
+  CASE WHEN COALESCE((COALESCE((COALESCE(("pr"."derived_status" = 'merged'), 0) OR COALESCE(("pr"."derived_status" = 'converged'), 0) OR COALESCE(("pr"."derived_status" = 'abandoned'), 0) OR COALESCE(("pr"."derived_status" = 'closed'), 0) OR COALESCE(("pr"."derived_status" = 'failed'), 0)), 0) AND COALESCE(("pr"."acknowledged_at" = "pr"."acknowledged_at"), 0)), 0) THEN 'history' ELSE 'active' END AS list_bucket,
+  CASE WHEN COALESCE((COALESCE((COALESCE(("pr"."derived_status" = 'merged'), 0) OR COALESCE(("pr"."derived_status" = 'converged'), 0) OR COALESCE(("pr"."derived_status" = 'abandoned'), 0) OR COALESCE(("pr"."derived_status" = 'closed'), 0) OR COALESCE(("pr"."derived_status" = 'failed'), 0)), 0) AND (NOT COALESCE(COALESCE(("pr"."acknowledged_at" = "pr"."acknowledged_at"), 0), 0))), 0) THEN 1 ELSE 0 END AS ack_open
+FROM pull_requests__tracking pr;

package/db/migrations/136_pull_requests_custom_instructions_text.sql

@@ -0,0 +1,11 @@
+-- Durable operator-steering TEXT for the convergence lifecycle (issue #956 review, Copilot threads
+-- 4547353262 / 4547353302). Migration 134 added only the boolean `custom_instructions` PROJECTION
+-- (1 ⇒ steered) so `/status` needs no engine read — but the TEXT itself lived solely on the
+-- convergence instance's variables. Every path that RE-ENTERS `submitPr` without the text
+-- (the merge→reconvergence `pr.reconverge` handoff, `handoffWaitingMergeToConvergence`, the
+-- poller's feature-delivery re-enroll) therefore started a replacement loop that ran UNSTEERED and
+-- reset the flag to 0. Persist the trimmed text on the row so any handoff can re-supply it, and so
+-- `startMerge` can re-seed the merge-loop instance (whose `pr.reconverge` is one of those paths).
+-- Run-scoped exactly like `custom_instructions`: the atomic reopen rewrites it to the fresh run's
+-- steering. NULL on every pre-existing row; those read as "no instructions".
+ALTER TABLE pull_requests ADD COLUMN custom_instructions_text TEXT;