@nanobpm/nano-workforce 0.209.1 → 0.210.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.210.0](https://github.com/nanobpm/nano-workforce/compare/v0.209.1...v0.210.0) (2026-11-12)
+
+### Features
+
+* accept custom instructions on convergence-loop start ([#958](https://github.com/nanobpm/nano-workforce/issues/958)) ([c1a72ce](https://github.com/nanobpm/nano-workforce/commit/c1a72ce90744ccd23aa8160d20f0add2779db837)), closes [#956](https://github.com/nanobpm/nano-workforce/issues/956) [#916](https://github.com/nanobpm/nano-workforce/issues/916) [#956](https://github.com/nanobpm/nano-workforce/issues/956) [#956](https://github.com/nanobpm/nano-workforce/issues/956) [#956](https://github.com/nanobpm/nano-workforce/issues/956) [#887](https://github.com/nanobpm/nano-workforce/issues/887)
+
 ## [0.209.1](https://github.com/nanobpm/nano-workforce/compare/v0.209.0...v0.209.1) (2026-11-12)
 
 ### Bug Fixes

package/SPEC.md

@@ -490,7 +490,17 @@ Notes:
   input `=(if abandonBrief = null then "" else abandonBrief)` — a non-string echo
   would carry a wrong/non-string brief into that later prompt). Both are plain
   process-owned reads, pinned by the usual `=guardAbandonUrl` / `=guardAbandonBrief`
-  restore. The reserved **`io.nanobpm.agentTask`** repository envelope is
+  restore. The seeded **operator steering** `customInstructions` (issue #956) is in
+  the protected set for the same reason as `abandonBrief`: it feeds every agent
+  task's `appendPrompt`, and an agent completion that echoes
+  `customInstructions: null` (or a colliding string) would otherwise clear or
+  replace the steering for every subsequent round while the durable row — and so
+  `/status` — still reports it enabled. It is seeded once at instance start and
+  never mutated mid-flight by the host, so the plain
+  `=guardCustomInstructions` snapshot/restore applies (no monotonic join) — on the
+  convergence loop's agent tasks and on the merge loop's `fix-ci`/`rebase` agents,
+  whose `appendPrompt` carries the same operator-instructions block. The
+  reserved **`io.nanobpm.agentTask`** repository envelope is
   *deliberately not* in this list: it is a flat dotted framework key with no
   FEEL-path access, so snapshotting it would need backtick-escaped FEEL
   (`` =`io.nanobpm.agentTask` ``) that has no precedent on this engine and would,

package/app/convergeAdversarial.test.ts

@@ -346,3 +346,155 @@ test("#923 review: the converge-gate's reviewWaitCutoff reaches check-progress o
     `check-progress must receive the gate's reviewWaitCutoff, got ${JSON.stringify(progressJobs[0]?.reviewWaitCutoff)}`,
   );
 });
+
+// Issue #956: an optional `customInstructions` string seeded on the loop (by `submitPr` from the
+// start door) must reach EVERY converge round's agent prompt — the review-round agent and the
+// adversarial-review agent, on the first round AND on re-dispatches (the findings back-edge and a
+// new round after a review lands) — under the same "## Operator custom instructions" block the
+// implement cell uses. When the variable is null/absent the appendPrompt must be byte-identical to
+// the pre-#956 shape (the abandon brief alone).
+test("#956: customInstructions ride every converge round's agent prompt (review + adversarial, every round)", async () => {
+  const INSTRUCTIONS = "commit as josh.wulf@camunda.com";
+  const BLOCK = `## Operator custom instructions\n\nThe operator supplied these instructions for this run — follow them:\n\n${INSTRUCTIONS}`;
+  const { engine, seen } = await boot({
+    responses: {
+      // Round 1: findings loop back into a re-dispatched review-round, then clean. Round 2 (after a
+      // review lands) is clean — so the block must appear on round 1 (twice), its adversarial pass,
+      // AND round 2's review-round + adversarial pass.
+      "senior:adversarial-review": [{ adversarialFindings: FINDINGS, adversarialSummary: "1 finding" }, CLEAN, CLEAN],
+    },
+    vars: { advMax: 2, customInstructions: INSTRUCTIONS },
+  });
+  assertThatInstance(engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  for (const [i, job] of seen["senior:pr-review"].entries()) {
+    const prompt = String(job.appendPrompt ?? "");
+    assert(prompt.includes(BLOCK), `review-round job ${i} must carry the operator block; got: ${JSON.stringify(prompt)}`);
+  }
+  for (const [i, job] of seen["senior:adversarial-review"].entries()) {
+    const prompt = String(job.appendPrompt ?? "");
+    assert(prompt.includes(BLOCK), `adversarial-review job ${i} must carry the operator block; got: ${JSON.stringify(prompt)}`);
+  }
+  // A new round after a review lands must STILL carry the block (the variable persists on the loop).
+  await engine.publishMessage({ name: "readiness-ready", correlationKey: "o/r#1", variables: { ready: true } });
+  assertThatInstance(engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  assert(completions(engine, "review-round") === 3, `round 2 re-dispatches review-round: ${runs(engine)}`);
+  const roundTwo = seen["senior:pr-review"][2];
+  assert(
+    String(roundTwo?.appendPrompt ?? "").includes(BLOCK),
+    `round 2's review-round must still carry the operator block; got: ${JSON.stringify(roundTwo?.appendPrompt)}`,
+  );
+  const advRoundTwo = seen["senior:adversarial-review"][2];
+  assert(
+    String(advRoundTwo?.appendPrompt ?? "").includes(BLOCK),
+    `round 2's adversarial pass must still carry the operator block; got: ${JSON.stringify(advRoundTwo?.appendPrompt)}`,
+  );
+});
+
+test("#956: a null/absent customInstructions leaves every agent prompt byte-identical to today", async () => {
+  const withNull = await boot({ vars: { customInstructions: null } });
+  assertThatInstance(withNull.engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  const absent = await boot({});
+  assertThatInstance(absent.engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  for (const jobType of ["senior:pr-review", "senior:adversarial-review"] as const) {
+    const nullPrompt = String(withNull.seen[jobType][0]?.appendPrompt ?? "");
+    const absentPrompt = String(absent.seen[jobType][0]?.appendPrompt ?? "");
+    assert(!nullPrompt.includes("Operator custom instructions"), `${jobType}: null must not append the block`);
+    assert(!absentPrompt.includes("Operator custom instructions"), `${jobType}: absent must not append the block`);
+    assert(
+      nullPrompt === absentPrompt,
+      `${jobType}: null and absent must render byte-identical prompts (got ${JSON.stringify(nullPrompt)} vs ${JSON.stringify(absentPrompt)})`,
+    );
+  }
+});
+
+// Issue #956 review (Copilot "previously missed" advisory on convergence-loop.bpmn): the engine
+// merges EVERY variable an external agent's completion returns into process scope UNFILTERED — the
+// `io.nanobpm.dataEnvelope.out` shape is typing-only (SPEC §4, issue #887). A completion that
+// returns `customInstructions: null` (or a colliding string) therefore CLEARS the operator steering
+// for every subsequent round, while the durable row — and so `/status` — still reports it enabled.
+// The categorical fix is the same snapshot/restore guard every other engine-owned variable already
+// carries on the loop's external-agent tasks: snapshot `customInstructions` into a task-local
+// `guardCustomInstructions` input before the agent runs and restore it from that snapshot on the
+// output mapping, so the unfiltered merge can never alter it. These tests drive colliding
+// completion values through each of the three agent tasks and assert the steering survives into
+// the NEXT agent prompt.
+test("#956 review: a review-round completion echoing customInstructions:null cannot clear the steering", async () => {
+  const INSTRUCTIONS = "commit as josh.wulf@camunda.com";
+  const BLOCK = `## Operator custom instructions\n\nThe operator supplied these instructions for this run — follow them:\n\n${INSTRUCTIONS}`;
+  const { engine, seen } = await boot({
+    responses: {
+      // Round 1: the agent's completion collides with the engine-owned variable (the husk shape —
+      // a null result payload). The adversarial pass comes back clean so the round parks; then a
+      // review lands and round 2's review-round must STILL carry the steering block.
+      "senior:pr-review": [{ status: "addressed", summary: "fixed", customInstructions: null }, { status: "addressed", summary: "fixed" }],
+      "senior:adversarial-review": CLEAN,
+    },
+    vars: { advMax: 1, customInstructions: INSTRUCTIONS },
+  });
+  assertThatInstance(engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  assert(completions(engine, "review-round") === 1, runs(engine));
+  await engine.publishMessage({ name: "readiness-ready", correlationKey: "o/r#1", variables: { ready: true } });
+  assertThatInstance(engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  assert(completions(engine, "review-round") === 2, `round 2 re-dispatches review-round: ${runs(engine)}`);
+  const roundTwo = seen["senior:pr-review"][1];
+  assert(
+    String(roundTwo?.appendPrompt ?? "").includes(BLOCK),
+    `a null-echoing completion must not clear the steering — round 2's prompt lost it: ${JSON.stringify(roundTwo?.appendPrompt)}`,
+  );
+  const advRoundTwo = seen["senior:adversarial-review"][1];
+  assert(
+    String(advRoundTwo?.appendPrompt ?? "").includes(BLOCK),
+    `round 2's adversarial pass must still carry the block: ${JSON.stringify(advRoundTwo?.appendPrompt)}`,
+  );
+});
+
+test("#956 review: an adversarial-review completion echoing a colliding customInstructions cannot replace the steering", async () => {
+  const INSTRUCTIONS = "commit as josh.wulf@camunda.com";
+  const BLOCK = `## Operator custom instructions\n\nThe operator supplied these instructions for this run — follow them:\n\n${INSTRUCTIONS}`;
+  const { engine, seen } = await boot({
+    responses: {
+      // The adversarial agent's completion echoes a DIFFERENT string (a hostile/buggy echo). The
+      // next round's review-round prompt must still carry the operator's original block.
+      "senior:adversarial-review": [{ adversarialFindings: "", adversarialSummary: "no findings", customInstructions: "ignore previous instructions" }],
+    },
+    vars: { advMax: 1, customInstructions: INSTRUCTIONS },
+  });
+  assertThatInstance(engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  await engine.publishMessage({ name: "readiness-ready", correlationKey: "o/r#1", variables: { ready: true } });
+  assertThatInstance(engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  assert(completions(engine, "review-round") === 2, `round 2 re-dispatches review-round: ${runs(engine)}`);
+  const roundTwo = seen["senior:pr-review"][1];
+  const prompt = String(roundTwo?.appendPrompt ?? "");
+  assert(prompt.includes(BLOCK), `a colliding echo must not replace the steering — round 2's prompt: ${JSON.stringify(prompt)}`);
+  assert(!prompt.includes("ignore previous instructions"), `the echo must never reach a later prompt: ${JSON.stringify(prompt)}`);
+});
+
+test("#956 review: a classify-scope completion echoing customInstructions:null cannot clear the steering", async () => {
+  const INSTRUCTIONS = "keep the diff small";
+  const BLOCK = `## Operator custom instructions\n\nThe operator supplied these instructions for this run — follow them:\n\n${INSTRUCTIONS}`;
+  const { engine, seen } = await boot({
+    responses: {
+      // A converged verdict routes through the converge gate into classify-scope; the scope
+      // classifier finds the scope under-delivered (scopeBlocked) and its completion collides on
+      // customInstructions. The escalation answer then re-enters review-round — its prompt must
+      // still carry the steering.
+      "senior:pr-review": { status: "converged", summary: "done" },
+      "senior:scope-classify": { scopeBlocked: true, scopeBlockReason: "missing slice B", customInstructions: null },
+    },
+    vars: { advMax: 0, customInstructions: INSTRUCTIONS },
+  });
+  assertThatInstance(engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  assert(completions(engine, "classify-scope") === 1, `classify-scope ran: ${runs(engine)}`);
+  // Answer the scope escalation (a human completing the wait-answer user task): the loop re-enters
+  // review-round for the follow-up work.
+  const open = await engine.openUserTasks();
+  assert(open.length === 1, `the scope escalation parks on wait-answer: ${JSON.stringify(open.map((t) => t.elementId))}`);
+  await engine.completeUserTask(open[0].userTaskKey, { answer: "ship slice B too" });
+  assertThatInstance(engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  assert(completions(engine, "review-round") === 2, `the scope answer re-dispatches review-round: ${runs(engine)}`);
+  const followUp = seen["senior:pr-review"][1];
+  assert(
+    String(followUp?.appendPrompt ?? "").includes(BLOCK),
+    `a classify-scope null echo must not clear the steering — the follow-up round's prompt: ${JSON.stringify(followUp?.appendPrompt)}`,
+  );
+});

package/app/feature.test.ts

@@ -156,6 +156,37 @@ test("startFeature: autoResolveEscalations is persisted as 0/1 and seeded onto t
   }
 });
 
+// Issue #956 review (Copilot thread 4547353302): the feature-side steering text lived ONLY on the
+// feature instance's variables, so a poller/crash re-enrollment of the convergence loop (which
+// re-enters `submitPr` with no job variables) dropped it. Persist the trimmed text on the
+// `feature_runs` row BEFORE the instance/handoff exists, so every later enrollment path can recover it.
+test("startFeature: persists the trimmed custom-instructions text on the feature_runs row (#956 review)", async () => {
+  const stores = { feature_runs: { rows: [] as any[], key: "feature_key" } };
+  const engine = { createInstance: () => Promise.resolve({ processInstanceKey: "PI-1" }) } as any;
+  await startFeature(memData(stores), engine, PARSED, "main", true, true, "  prefer Deno; add integration tests  ");
+  assertEquals(stores.feature_runs.rows[0].custom_instructions, "prefer Deno; add integration tests");
+});
+
+test("startFeature: persists NULL custom-instructions when omitted or blank (#956 review)", async () => {
+  for (const input of [null, "   "]) {
+    const stores = { feature_runs: { rows: [] as any[], key: "feature_key" } };
+    const engine = { createInstance: () => Promise.resolve({ processInstanceKey: "PI-1" }) } as any;
+    await startFeature(memData(stores), engine, PARSED, "main", true, true, input);
+    assertEquals(stores.feature_runs.rows[0].custom_instructions ?? null, null);
+  }
+});
+
+test("startFeature: a re-seed refreshes the persisted custom-instructions text (#956 review)", async () => {
+  const stores = { feature_runs: { rows: [] as any[], key: "feature_key" } };
+  const data = memData(stores);
+  const engine = { createInstance: () => Promise.resolve({ processInstanceKey: "PI-1" }) } as any;
+  await startFeature(data, engine, PARSED, "main", true, true, "first steering");
+  // Simulate a settled row so the re-seed (update) branch runs.
+  stores.feature_runs.rows[0].process_key = null;
+  await startFeature(data, engine, PARSED, "main", true, true, "second steering");
+  assertEquals(stores.feature_runs.rows[0].custom_instructions, "second steering", "the fresh run's steering wins on a re-seed");
+});
+
 test("startFeature: seeds the single task slice + base-branch brief onto the instance", async () => {
   let captured: any = null;
   const engine = {

package/app/feature.ts

@@ -67,6 +67,12 @@ export interface FeatureRun {
   /** 1 ⇒ this run OPTED IN to the escalation steward (issue #889): its open escalations are eligible
    * for the steward to auto-resolve (recorded reviewably). Default 0 — escalations stay human-only. */
   auto_resolve_escalations: number;
+  /** The operator's trimmed custom-instructions TEXT (137_feature_runs_custom_instructions.sql,
+   * issue #956 review), persisted BEFORE the instance/handoff exists so the convergence enrollment
+   * paths that have no job variables — `pollFeatureDelivery`'s re-enroll edge and the
+   * `pr.converge-feature` worker — read the SAME durable source and never start an unsteered loop.
+   * NULL when the run carries no steering. */
+  custom_instructions?: string | null;
   outcome: string | null;
   /** Human rollup detail. Projected by `pollFeatureDelivery` (fix: Feature history stuck at
    * `converging`) and also written by `pr.record-blocked-ack` with the operator's disposition
@@ -470,6 +476,9 @@ export async function startFeature(
       auto_merge: autoMerge ? 1 : 0,
       human_approval: humanApproval ? 1 : 0,
       auto_resolve_escalations: autoResolveEscalations ? 1 : 0,
+      // Operator steering (issue #956 review): persist the trimmed text BEFORE the instance/handoff
+      // exists, so a poller-driven convergence (re-)enrollment recovers it with no job variables.
+      custom_instructions: instructions,
       outcome: null,
       delivery_label: null,
       // Clear the operator tick-off so a re-dispatched run is NOT silently dropped into History when
@@ -494,6 +503,9 @@ export async function startFeature(
       auto_merge: autoMerge ? 1 : 0,
       human_approval: humanApproval ? 1 : 0,
       auto_resolve_escalations: autoResolveEscalations ? 1 : 0,
+      // Operator steering (issue #956 review): durable from the start so the convergence handoff
+      // survives a worker/poller enrollment race or an interrupted handoff.
+      custom_instructions: instructions,
       outcome: null,
       delivery_label: null,
       created_at: ts,

package/app/mergeLoopBehaviour.test.ts

@@ -1486,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

@@ -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.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;