@nanobpm/nano-workforce 0.209.0 → 0.210.0

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;

package/db/migrations/137_feature_runs_custom_instructions.sql

@@ -0,0 +1,66 @@
+-- Durable operator-steering TEXT on the feature run (issue #956 review, Copilot thread
+-- 4547353302). `startFeature` already seeds `customInstructions` onto the feature INSTANCE's
+-- variables, and the `pr.converge-feature` worker forwards it to `submitPr` — but the worker
+-- publishes `converging` BEFORE enrolling, so `pollFeatureDelivery`'s re-enroll edge can win the
+-- race (or recover an interrupted handoff) and call `submitPr` with NO job variables, starting a
+-- loop without the instructions; the worker's later call then returns `alreadyRunning` without
+-- updating the live loop. Persist the trimmed text on the run row BEFORE the instance/handoff
+-- exists so the poller's enrollment path (and the worker) read the SAME durable source. The text
+-- is the operator's own input (already written to the instance and prompts), so a TEXT column
+-- carries no new sensitivity class. NULL when the run carries no steering.
+--
+-- The column is mirrored through the `delivery_units` aggregate so the `feature_runs__units` compat
+-- VIEW stays row-for-row equal to `feature_runs` (ADR 0006, parity-tested in
+-- app/deliveryUnit.test.ts): the Feature sync triggers (089) and VIEW (091) are re-created verbatim
+-- plus `custom_instructions`, exactly as migration 125 did for the pr-link columns.
+
+ALTER TABLE feature_runs ADD COLUMN custom_instructions TEXT;
+
+ALTER TABLE delivery_units ADD COLUMN custom_instructions TEXT;
+
+DROP TRIGGER IF EXISTS feature_runs__du_ai;
+CREATE TRIGGER feature_runs__du_ai AFTER INSERT ON feature_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, base_branch, status, process_key, pr_key, converge, auto_merge, human_approval, auto_resolve_escalations, custom_instructions, outcome, delivery_label, pr_linked_pr_key, pr_link_want_pr_key, pr_link_lease_at, acknowledged_at, stage, stage_state, stage_skipped, attention, list_bucket, created_at, updated_at)
+  VALUES ('feature:' || NEW.feature_key, 'feature', NEW.feature_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'converging' THEN 'converging' WHEN NEW.status = 'awaiting_operator' THEN 'awaiting_operator' WHEN NEW.status = 'merged' THEN 'merged' WHEN NEW.status = 'converged' THEN 'converged' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('opened', 'converging', 'merged', 'converged', 'blocked', 'skipped', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running', 'escalated', 'awaiting_operator') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.base_branch, NEW.status, NEW.process_key, NEW.pr_key, NEW.converge, NEW.auto_merge, NEW.human_approval, NEW.auto_resolve_escalations, NEW.custom_instructions, NEW.outcome, NEW.delivery_label, NEW.pr_linked_pr_key, NEW.pr_link_want_pr_key, NEW.pr_link_lease_at, NEW.acknowledged_at, NEW.stage, NEW.stage_state, NEW.stage_skipped, NEW.attention, NEW.list_bucket, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS feature_runs__du_au;
+CREATE TRIGGER feature_runs__du_au AFTER UPDATE ON feature_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, base_branch, status, process_key, pr_key, converge, auto_merge, human_approval, auto_resolve_escalations, custom_instructions, outcome, delivery_label, pr_linked_pr_key, pr_link_want_pr_key, pr_link_lease_at, acknowledged_at, stage, stage_state, stage_skipped, attention, list_bucket, created_at, updated_at)
+  VALUES ('feature:' || NEW.feature_key, 'feature', NEW.feature_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'converging' THEN 'converging' WHEN NEW.status = 'awaiting_operator' THEN 'awaiting_operator' WHEN NEW.status = 'merged' THEN 'merged' WHEN NEW.status = 'converged' THEN 'converged' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('opened', 'converging', 'merged', 'converged', 'blocked', 'skipped', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running', 'escalated', 'awaiting_operator') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.base_branch, NEW.status, NEW.process_key, NEW.pr_key, NEW.converge, NEW.auto_merge, NEW.human_approval, NEW.auto_resolve_escalations, NEW.custom_instructions, NEW.outcome, NEW.delivery_label, NEW.pr_linked_pr_key, NEW.pr_link_want_pr_key, NEW.pr_link_lease_at, NEW.acknowledged_at, NEW.stage, NEW.stage_state, NEW.stage_skipped, NEW.attention, NEW.list_bucket, NEW.created_at, NEW.updated_at);
+END;
+
+DROP VIEW IF EXISTS feature_runs__units;
+CREATE VIEW feature_runs__units AS
+SELECT
+  du.legacy_key AS feature_key,
+  du.repo AS repo,
+  du.issue_number AS issue_number,
+  du.issue_url AS issue_url,
+  du.base_branch AS base_branch,
+  du.status AS status,
+  du.process_key AS process_key,
+  du.pr_key AS pr_key,
+  du.converge AS converge,
+  du.auto_merge AS auto_merge,
+  du.human_approval AS human_approval,
+  du.auto_resolve_escalations AS auto_resolve_escalations,
+  du.custom_instructions AS custom_instructions,
+  du.outcome AS outcome,
+  du.created_at AS created_at,
+  du.updated_at AS updated_at,
+  du.delivery_label AS delivery_label,
+  du.pr_linked_pr_key AS pr_linked_pr_key,
+  du.pr_link_want_pr_key AS pr_link_want_pr_key,
+  du.pr_link_lease_at AS pr_link_lease_at,
+  du.title AS title,
+  du.acknowledged_at AS acknowledged_at,
+  du.stage AS stage,
+  du.stage_state AS stage_state,
+  du.stage_skipped AS stage_skipped,
+  du.attention AS attention,
+  du.list_bucket AS list_bucket
+FROM delivery_units du
+WHERE du.kind = 'feature';

package/db/migrations/138_pull_requests_read_model_custom_instructions_text.sql

@@ -0,0 +1,53 @@
+-- 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 135 with `custom_instructions_text` (136, issue #956 review) added; the derived columns are emitted
+-- VERBATIM from app/pullRequestReadModel.ts and are unchanged. No BEGIN/COMMIT (the runner wraps each
+-- file). Numbered after 137.
+
+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,
+  pr.custom_instructions_text AS custom_instructions_text,
+  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/docs/agent-guide.md

@@ -76,6 +76,7 @@ curl -sS -X POST __BASE__/actions/start/convergence-loop \
 | `maxRounds` | integer | round cap before escalating (1–100; default `NANO_PR_MAX_ROUNDS`, 20). |
 | `dependsOn` | string[] | `prKey`s that must land before this one merges. |
 | `autoResolveEscalations` | boolean | opt in to the escalation steward (§3). Default `false`. |
+| `customInstructions` | string | OPTIONAL free-text steering appended to **every** converge round's agent prompt (review-round and adversarial-review) under a `## Operator custom instructions` block — e.g. `"commit as josh.wulf@camunda.com"`, `"don't touch file X"`, `"keep the diff small"`. Blank/whitespace is treated as absent (the prompt stays byte-identical to no-instructions); a non-string is a `400`. Persists across reconverge re-dispatches. Read it back as `hasCustomInstructions` on the PR's `/status` row. |
 
 Idempotent on the PR key: re-POSTing refreshes the record instead of starting a second
 loop. The 202 response echoes `prKey` and `processKey`.

package/openapi.yaml

@@ -92,6 +92,7 @@ components:
         - activeWorker
         - leaseUntil
         - autoResolveEscalations
+        - hasCustomInstructions
         - merge
         - incident
         - terminationReason
@@ -172,6 +173,13 @@ components:
             Whether this PR's run opted into automatic escalation resolution by the escalation
             steward (issue #889). Derived from the subject row's durable `auto_resolve_escalations`
             flag, never a clobbered process variable.
+        hasCustomInstructions:
+          type: boolean
+          description: >-
+            Whether this run's converge agents carry operator custom instructions (issue #956) —
+            the loop was started with `customInstructions` and every round's agent prompt is being
+            steered. Served from the durable `custom_instructions` row projection that `submitPr`
+            stamps at submit/reopen; a pre-#956 (NULL) row reads false. Never an engine read.
         merge:
           type: object
           additionalProperties: false
@@ -2253,6 +2261,10 @@ components:
         autoResolveEscalations:
           type: boolean
           description: "Opt this loop's escalations into the escalation steward (issue #889) — it reviews each open escalation every 30 min and submits a recommended choice, recorded reviewably in Auto-resolutions. Default off."
+        customInstructions:
+          type: string
+          maxLength: 8000
+          description: "OPTIONAL free-text steering appended to every converge round's agent prompt (review-round and adversarial-review), like `FeatureStartByIssue.customInstructions` for the implementer. Blank is treated as absent; a non-string is a 400. Surfaced on `/status` as `hasCustomInstructions`."
         convergeOnly:
           type: boolean
           deprecated: true
@@ -2280,6 +2292,10 @@ components:
         autoResolveEscalations:
           type: boolean
           description: "Opt this loop's escalations into the escalation steward (issue #889) — it reviews each open escalation every 30 min and submits a recommended choice, recorded reviewably in Auto-resolutions. Default off."
+        customInstructions:
+          type: string
+          maxLength: 8000
+          description: "OPTIONAL free-text steering appended to every converge round's agent prompt (review-round and adversarial-review), like `FeatureStartByIssue.customInstructions` for the implementer. Blank is treated as absent; a non-string is a 400. Surfaced on `/status` as `hasCustomInstructions`."
         convergeOnly:
           type: boolean
           deprecated: true
@@ -5304,6 +5320,10 @@ paths:
                     autoResolveEscalations:
                       type: boolean
                       description: "Opt this loop's escalations into the escalation steward (issue #889) — it reviews each open escalation every 30 min and submits a recommended choice, recorded reviewably in Auto-resolutions. Default off."
+                    customInstructions:
+                      type: string
+                      maxLength: 8000
+                      description: OPTIONAL free-text steering appended to every converge round's agent prompt (review-round and adversarial-review), like `FeatureStartByIssue.customInstructions` for the implementer. Blank is treated as absent; a non-string is a 400. Surfaced on `/status` as `hasCustomInstructions`.
                     convergeOnly:
                       type: boolean
                       deprecated: true
@@ -5330,6 +5350,10 @@ paths:
                     autoResolveEscalations:
                       type: boolean
                       description: "Opt this loop's escalations into the escalation steward (issue #889) — it reviews each open escalation every 30 min and submits a recommended choice, recorded reviewably in Auto-resolutions. Default off."
+                    customInstructions:
+                      type: string
+                      maxLength: 8000
+                      description: OPTIONAL free-text steering appended to every converge round's agent prompt (review-round and adversarial-review), like `FeatureStartByIssue.customInstructions` for the implementer. Blank is treated as absent; a non-string is a 400. Surfaced on `/status` as `hasCustomInstructions`.
                     convergeOnly:
                       type: boolean
                       deprecated: true

package/operations/listActivePrs.test.ts

@@ -66,6 +66,23 @@ test("returns 200 with a count + projected active PRs", async () => {
   assertEquals(r.body.prs[0].processKey, "9");
 });
 
+test("surfaces hasCustomInstructions from the durable row projection (issue #956)", async () => {
+  // The operator can see that a loop is being steered without opening the engine: `submitPr` stamps
+  // the `custom_instructions` column (1/0) at submit/reopen, and `/status` serves it as a boolean.
+  // A legacy row (NULL — written before the projection existed) reads false, never an engine read.
+  const app = memApp([
+    { pr_key: "o/r#30", repo: "o/r", number: 30, url: "u30", title: "steered", status: "converging", current_round: 1, process_key: "PI-30", updated_at: "2026-01-03", custom_instructions: 1 },
+    { pr_key: "o/r#31", repo: "o/r", number: 31, url: "u31", title: "plain", status: "converging", current_round: 1, process_key: "PI-31", updated_at: "2026-01-02", custom_instructions: 0 },
+    { pr_key: "o/r#32", repo: "o/r", number: 32, url: "u32", title: "legacy", status: "converging", current_round: 1, process_key: "PI-32", updated_at: "2026-01-01" },
+  ]);
+  const res = (await handler(input(), app)) as any;
+  assertEquals(res.status, 200);
+  const byKey = (k: string) => res.body.prs.find((p: any) => p.prKey === k);
+  assertEquals(byKey("o/r#30").hasCustomInstructions, true, "a steered loop is visible");
+  assertEquals(byKey("o/r#31").hasCustomInstructions, false, "an unsteered loop reads false");
+  assertEquals(byKey("o/r#32").hasCustomInstructions, false, "a legacy (NULL) row reads false");
+});
+
 test("carries the running app's identity as a top-level version object (issue #925)", async () => {
   // `/status` is the endpoint everyone polls, so it must answer "is the fix live?" on its own:
   // version.version + version.gitSha, derived from the SAME app/version.ts getter /version uses.

package/operations/startAndMessage.test.ts

@@ -207,6 +207,86 @@ test("startConvergenceLoop → 400 on a non-boolean autoMerge (issue #916)", asy
   });
 });
 
+// Issue #956: the convergence-loop start door accepts an optional `customInstructions` string and
+// threads it to every converge round's agent prompt — mirroring the feature door. The capture
+// harness above records `convergeOnly`; this one records `customInstructions` off the same
+// createInstance variables.
+function captureInstructions() {
+  const rows: Record<string, unknown>[] = [];
+  let captured: unknown;
+  const data = {
+    table: (_name: string, key: string) => ({
+      get: (k: unknown) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+      find: (q: Record<string, unknown>) =>
+        Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+      insert: (r: Record<string, unknown>) => {
+        rows.push(r);
+        return Promise.resolve(r);
+      },
+      update: (k: unknown, patch: Record<string, unknown>) => {
+        const row = rows.find((r) => r[key] === k);
+        if (row) Object.assign(row, patch);
+        return Promise.resolve(row);
+      },
+      delete: (k: unknown) => {
+        const i = rows.findIndex((r) => r[key] === k);
+        if (i >= 0) rows.splice(i, 1);
+        return Promise.resolve();
+      },
+    }),
+  };
+  const engine = {
+    createInstance: (req: { variables?: Record<string, unknown> }) => {
+      captured = req.variables?.customInstructions;
+      return Promise.resolve({ processInstanceKey: "PI-1" });
+    },
+  };
+  return { app: { data, engine, log: noopLog() } as any as AppApi, get: () => captured };
+}
+
+test("startConvergenceLoop threads customInstructions (trimmed) into the loop's variables (#956)", async () => {
+  await withGithubOff(async () => {
+    const { app: capApp, get } = captureInstructions();
+    const res = await startConvergenceLoop(
+      input({ pr: "owner/repo#20", customInstructions: "  commit as josh.wulf@camunda.com  " }),
+      capApp,
+    );
+    assertEquals((res as any).status, 202);
+    assertEquals(get(), "commit as josh.wulf@camunda.com");
+  });
+});
+
+test("startConvergenceLoop seeds customInstructions null when omitted or blank (#956)", async () => {
+  await withGithubOff(async () => {
+    const omitted = captureInstructions();
+    const res = await startConvergenceLoop(input({ pr: "owner/repo#21" }), omitted.app);
+    assertEquals((res as any).status, 202);
+    assertEquals(omitted.get(), null, "omitted ⇒ null, so the appendPrompt FEEL skips the block");
+
+    const blank = captureInstructions();
+    const blankRes = await startConvergenceLoop(
+      input({ pr: "owner/repo#22", customInstructions: "   " }),
+      blank.app,
+    );
+    assertEquals((blankRes as any).status, 202);
+    assertEquals(blank.get(), null, "blank/whitespace ⇒ null (byte-identical prompt to today)");
+  });
+});
+
+// Mirrors the `autoMerge` non-boolean 400 (issue #916): a present-but-non-string `customInstructions`
+// must not be silently dropped — the operator believes they steered the loop when nothing was
+// appended. Rejected at the edge with a 400.
+test("startConvergenceLoop → 400 on a non-string customInstructions (#956)", async () => {
+  await withGithubOff(async () => {
+    const { app: capApp, get } = captureInstructions();
+    const res = await startConvergenceLoop(input({ pr: "owner/repo#23", customInstructions: 42 }), capApp);
+    const r = res as any;
+    assertEquals(r.status, 400);
+    assertEquals(typeof r.body.error, "string");
+    assertEquals(get(), undefined, "a rejected door never reaches the engine");
+  });
+});
+
 test("startPlanFanout → 400 on an unparseable issue reference", async () => {
   const res = await startPlanFanout(input({ issue: "" }), app);
   const r = res as any;

package/operations/startConvergenceLoop.ts

@@ -44,7 +44,18 @@ export default defineOperation("startConvergenceLoop", async ({ body }, app) =>
   // Opt-in escalation steward (issue #889): only when explicitly requested do this loop's
   // escalations become eligible for steward auto-resolution. Default off.
   const autoResolveEscalations = "autoResolveEscalations" in body && body.autoResolveEscalations === true;
-  const result = await submitPr(app.data, app.engine, parsed, dependsOn, maxRounds, false, null, false, autoResolveEscalations, autoMerge);
+  // Optional operator steering (issue #956), mirrored from the feature door: a present-but-non-string
+  // `customInstructions` is a 400 (the same way `autoMerge` is validated, #916) — silently dropping it
+  // would leave the operator believing they steered the loop when nothing was appended. Blank is
+  // normalized to null downstream (submitPr) so the prompt stays byte-identical to no-instructions.
+  if ("customInstructions" in body && typeof body.customInstructions !== "string") {
+    app.log.warn("start-convergence rejected: customInstructions must be a string", { customInstructions: body.customInstructions });
+    return { status: 400, body: { error: "customInstructions must be a string" } };
+  }
+  const customInstructions = "customInstructions" in body && typeof body.customInstructions === "string"
+    ? body.customInstructions
+    : null;
+  const result = await submitPr(app.data, app.engine, parsed, dependsOn, maxRounds, false, null, false, autoResolveEscalations, autoMerge, null, null, customInstructions);
   app.log.info("convergence loop started", {
     prKey: parsed.prKey,
     alreadyRunning: "alreadyRunning" in result && result.alreadyRunning === true,
@@ -52,6 +63,7 @@ export default defineOperation("startConvergenceLoop", async ({ body }, app) =>
     maxRounds,
     autoMerge: autoMerge ?? body.convergeOnly !== true,
     autoResolveEscalations,
+    hasCustomInstructions: customInstructions != null && customInstructions.trim() !== "",
   });
   return { status: 202, body: result };
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.209.0",
+  "version": "0.210.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/pages/home.page.json

@@ -136,12 +136,17 @@
           },
           {
             "key": "autoMerge",
-            "label": "Auto-merge \u2014 after convergence, drive the merge-loop",
+            "label": "Auto-merge — after convergence, drive the merge-loop",
             "type": "checkbox"
           },
+          {
+            "key": "customInstructions",
+            "label": "Custom instructions (optional) — extra steering appended to every converge round's agent prompt, e.g. “commit as josh.wulf@camunda.com; keep the diff small; don't touch file X”",
+            "type": "text"
+          },
           {
             "key": "autoResolveEscalations",
-            "label": "Automatically resolve escalations \u2014 the opt-in escalation steward reviews this loop's open escalations every 30 min and submits a recommended choice, recorded reviewably in Auto-resolutions",
+            "label": "Automatically resolve escalations — the opt-in escalation steward reviews this loop's open escalations every 30 min and submits a recommended choice, recorded reviewably in Auto-resolutions",
             "type": "checkbox"
           }
         ]

package/resources/processes/convergence-loop.bpmn

@@ -149,7 +149,7 @@
           <zeebe:property name="io.nanobpm.dataEnvelope.out" value="PrReviewRoundOut" />
         </zeebe:properties>
         <zeebe:ioMapping>
-          <zeebe:input source="=(if (abandonBrief = null) then &#34;&#34; else abandonBrief)" target="appendPrompt" />
+          <zeebe:input source="=(if (abandonBrief = null) then &#34;&#34; else abandonBrief) + (if (is defined(customInstructions) = false or customInstructions = null) then &#34;&#34; else &#34;&#10;&#10;---&#10;&#10;## Operator custom instructions&#10;&#10;The operator supplied these instructions for this run — follow them:&#10;&#10;&#34; + customInstructions)" target="appendPrompt" />
           <zeebe:input source="=round" target="guardRound" />
           <zeebe:input source="=maxRounds" target="guardMaxRounds" />
           <zeebe:input source="=advPass" target="guardAdvPass" />
@@ -169,6 +169,7 @@
           <zeebe:input source="=roundEntryHead" target="guardRoundEntryHead" />
           <zeebe:input source="=abandonUrl" target="guardAbandonUrl" />
           <zeebe:input source="=abandonBrief" target="guardAbandonBrief" />
+          <zeebe:input source="=customInstructions" target="guardCustomInstructions" />
           <zeebe:output source="=null" target="answer" />
           <zeebe:output source="=false" target="scopePending" />
           <zeebe:output source="=null" target="adversarialFindings" />
@@ -191,6 +192,7 @@
           <zeebe:output source="=guardRoundEntryHead" target="roundEntryHead" />
           <zeebe:output source="=guardAbandonUrl" target="abandonUrl" />
           <zeebe:output source="=guardAbandonBrief" target="abandonBrief" />
+          <zeebe:output source="=guardCustomInstructions" target="customInstructions" />
         </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_capture</bpmn:incoming>
@@ -245,7 +247,7 @@
           <zeebe:property name="io.nanobpm.dataEnvelope.out" value="PrAdversarialReviewOut" />
         </zeebe:properties>
         <zeebe:ioMapping>
-          <zeebe:input source="=(if (abandonBrief = null) then &#34;&#34; else abandonBrief)" target="appendPrompt" />
+          <zeebe:input source="=(if (abandonBrief = null) then &#34;&#34; else abandonBrief) + (if (is defined(customInstructions) = false or customInstructions = null) then &#34;&#34; else &#34;&#10;&#10;---&#10;&#10;## Operator custom instructions&#10;&#10;The operator supplied these instructions for this run — follow them:&#10;&#10;&#34; + customInstructions)" target="appendPrompt" />
           <zeebe:input source="=round" target="guardRound" />
           <zeebe:input source="=maxRounds" target="guardMaxRounds" />
           <zeebe:input source="=advPass" target="guardAdvPass" />
@@ -265,6 +267,7 @@
           <zeebe:input source="=roundEntryHead" target="guardRoundEntryHead" />
           <zeebe:input source="=abandonUrl" target="guardAbandonUrl" />
           <zeebe:input source="=abandonBrief" target="guardAbandonBrief" />
+          <zeebe:input source="=customInstructions" target="guardCustomInstructions" />
           <zeebe:output source="=adversarialFindings" target="adversarialFindings" />
           <zeebe:output source="=(if guardAdvPass = null then 0 else guardAdvPass) + 1" target="advPass" />
           <zeebe:output source="=(if adversarialFindings != null and trim(adversarialFindings) != &#34;&#34; then null else status)" target="status" />
@@ -288,6 +291,7 @@
           <zeebe:output source="=guardRoundEntryHead" target="roundEntryHead" />
           <zeebe:output source="=guardAbandonUrl" target="abandonUrl" />
           <zeebe:output source="=guardAbandonBrief" target="abandonBrief" />
+          <zeebe:output source="=guardCustomInstructions" target="customInstructions" />
         </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_advDue</bpmn:incoming>
@@ -579,6 +583,7 @@
           <zeebe:input source="=roundEntryHead" target="guardRoundEntryHead" />
           <zeebe:input source="=abandonUrl" target="guardAbandonUrl" />
           <zeebe:input source="=abandonBrief" target="guardAbandonBrief" />
+          <zeebe:input source="=customInstructions" target="guardCustomInstructions" />
           <zeebe:output source="=null" target="scopeAnswer" />
           <zeebe:output source="=guardRound" target="round" />
           <zeebe:output source="=guardMaxRounds" target="maxRounds" />
@@ -599,6 +604,7 @@
           <zeebe:output source="=guardRoundEntryHead" target="roundEntryHead" />
           <zeebe:output source="=guardAbandonUrl" target="abandonUrl" />
           <zeebe:output source="=guardAbandonBrief" target="abandonBrief" />
+          <zeebe:output source="=guardCustomInstructions" target="customInstructions" />
         </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_convergeOk</bpmn:incoming>

package/resources/processes/feature.bpmn

@@ -19,6 +19,7 @@
           <nano:extend name="prKey" type="string" optional="true" />
           <nano:extend name="autoMerge" type="boolean" optional="true" />
           <nano:extend name="humanApproval" type="boolean" optional="true" />
+          <nano:extend name="customInstructions" type="string" optional="true" />
         </nano:shape>
       </nano:shapes>
     </bpmn:extensionElements>

package/resources/processes/merge-loop.bpmn

@@ -55,6 +55,7 @@
           <nano:extend name="failingChecksList" type="string" optional="true" />
           <nano:extend name="reviewThreads" type="integer" optional="true" />
           <nano:extend name="pendingChecks" type="integer" optional="true" />
+          <nano:extend name="updatePending" type="boolean" optional="true" />
         </nano:shape>
         <nano:shape id="LandedProbeIn" name="Landed probe — input">
           <nano:extend name="prKey" type="string" />
@@ -476,8 +477,9 @@
             <zeebe:property name="io.nanobpm.dataEnvelope.out" value="FixCiOut" />
           </zeebe:properties>
           <zeebe:ioMapping>
-            <zeebe:input source="=(if (failingChecksList = null or failingChecksList = &#34;&#34;) then &#34;&#34; else &#34;&#10;&#10;Failing checks to make green:&#10;&#34; + failingChecksList) + (if (abandonBrief = null) then &#34;&#34; else abandonBrief)" target="appendPrompt" />
+            <zeebe:input source="=(if (failingChecksList = null or failingChecksList = &#34;&#34;) then &#34;&#34; else &#34;&#10;&#10;Failing checks to make green:&#10;&#34; + failingChecksList) + (if (abandonBrief = null) then &#34;&#34; else abandonBrief) + (if (is defined(customInstructions) = false or customInstructions = null) then &#34;&#34; else &#34;&#10;&#10;---&#10;&#10;## Operator custom instructions&#10;&#10;The operator supplied these instructions for this run — follow them:&#10;&#10;&#34; + customInstructions)" target="appendPrompt" />
             <zeebe:input source="=ciFixRound" target="guardCiFixRound" />
+            <zeebe:input source="=customInstructions" target="guardCustomInstructions" />
             <zeebe:input source="=ciFixMax" target="guardCiFixMax" />
             <zeebe:input source="=rebaseRound" target="guardRebaseRound" />
             <zeebe:input source="=rebaseMax" target="guardRebaseMax" />
@@ -521,6 +523,7 @@
             <zeebe:output source="=guardRound" target="round" />
             <zeebe:output source="=guardAbandonUrl" target="abandonUrl" />
             <zeebe:output source="=guardAbandonBrief" target="abandonBrief" />
+            <zeebe:output source="=guardCustomInstructions" target="customInstructions" />
             <zeebe:output source="=guardReviewRequestRound" target="reviewRequestRound" />
             <zeebe:output source="=guardReviewRequestMax" target="reviewRequestMax" />
             <zeebe:output source="=guardReviewRequestWait" target="reviewRequestWait" />
@@ -686,8 +689,9 @@
             <zeebe:property name="io.nanobpm.dataEnvelope.out" value="RebaseOut" />
           </zeebe:properties>
           <zeebe:ioMapping>
-            <zeebe:input source="=(if (abandonBrief = null) then &#34;&#34; else abandonBrief)" target="appendPrompt" />
+            <zeebe:input source="=(if (abandonBrief = null) then &#34;&#34; else abandonBrief) + (if (is defined(customInstructions) = false or customInstructions = null) then &#34;&#34; else &#34;&#10;&#10;---&#10;&#10;## Operator custom instructions&#10;&#10;The operator supplied these instructions for this run — follow them:&#10;&#10;&#34; + customInstructions)" target="appendPrompt" />
             <zeebe:input source="=ciFixRound" target="guardCiFixRound" />
+            <zeebe:input source="=customInstructions" target="guardCustomInstructions" />
             <zeebe:input source="=ciFixMax" target="guardCiFixMax" />
             <zeebe:input source="=rebaseRound" target="guardRebaseRound" />
             <zeebe:input source="=rebaseMax" target="guardRebaseMax" />
@@ -731,6 +735,7 @@
             <zeebe:output source="=guardRound" target="round" />
             <zeebe:output source="=guardAbandonUrl" target="abandonUrl" />
             <zeebe:output source="=guardAbandonBrief" target="abandonBrief" />
+            <zeebe:output source="=guardCustomInstructions" target="customInstructions" />
             <zeebe:output source="=guardReviewRequestRound" target="reviewRequestRound" />
             <zeebe:output source="=guardReviewRequestMax" target="reviewRequestMax" />
             <zeebe:output source="=guardReviewRequestWait" target="reviewRequestWait" />
@@ -846,7 +851,7 @@
     <bpmn:sequenceFlow id="f_mw_stall" sourceRef="wait-mergeable-timeout" targetRef="merge-stall-probe" />
     <bpmn:sequenceFlow id="f_msp_gate" sourceRef="merge-stall-probe" targetRef="gw-merge-stall" />
     <bpmn:sequenceFlow id="f_msp_rederive" name="re-derived — route to arm" sourceRef="gw-merge-stall" targetRef="gw-mergeable">
-      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=mergeStallRounds &lt;= mergeStallMax</bpmn:conditionExpression>
+      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=mergeStallRounds &lt;= mergeStallMax or mergeState = "ready" or updatePending = true</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
     <bpmn:sequenceFlow id="f_msp_giveup" name="stall budget exhausted" sourceRef="gw-merge-stall" targetRef="merge-esc-conflict" />
     <bpmn:sequenceFlow id="f_m_ready" sourceRef="wait-mergeable" targetRef="gw-mergeable" />

package/workers/converge-feature/worker.ts

@@ -53,13 +53,22 @@ const handler: AppJobHandler<In, Record<string, never>> = async (job, app) => {
   // read the durable flag off the `feature_runs` row (the source of truth) and hand it to `submitPr`.
   const featureRow = await featureRuns(app.data).get(featureKey);
   const autoResolve = featureRow?.auto_resolve_escalations === 1;
-  await submitPr(app.data, app.engine, parsed, [], MAX_ROUNDS, false, featureKey, humanApproval, autoResolve, autoMerge);
+  // Propagate the run's operator custom instructions (issue #956) the same way. Read the DURABLE
+  // text off the `feature_runs` row — persisted by `startFeature` before the instance/handoff
+  // existed (issue #956 review) — NOT the job variable: the worker publishes `converging` BEFORE
+  // enrolling, so `pollFeatureDelivery`'s re-enroll edge can win the race (or recover an
+  // interrupted handoff) with no job variables at all. Both paths now read this one durable source,
+  // so the steering survives the worker/poller interleaving.
+  const rowInstructions = featureRow?.custom_instructions;
+  const customInstructions = typeof rowInstructions === "string" && rowInstructions.trim() !== "" ? rowInstructions : null;
+  await submitPr(app.data, app.engine, parsed, [], MAX_ROUNDS, false, featureKey, humanApproval, autoResolve, autoMerge, null, null, customInstructions);
   app.log.info("converge-feature: enrolled PR into convergence loop", {
     featureKey,
     prKey: parsed.prKey,
     autoMerge,
     humanApproval,
     autoResolveEscalations: autoResolve,
+    hasCustomInstructions: customInstructions != null,
   });
   return {};
 };