@nanobpm/nano-workforce 0.171.9 → 0.171.11

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.171.11](https://github.com/nanobpm/nano-workforce/compare/v0.171.10...v0.171.11) (2026-09-01)
+
+### Bug Fixes
+
+* **mcp:** declare x-nano-secret-env on hookSecret so urban_debug_* mutations authorize remotely ([#700](https://github.com/nanobpm/nano-workforce/issues/700)) ([bd46ac6](https://github.com/nanobpm/nano-workforce/commit/bd46ac6e235fc9a13cab27351108cea9570f387b)), closes [#698](https://github.com/nanobpm/nano-workforce/issues/698) [#698](https://github.com/nanobpm/nano-workforce/issues/698) [#698](https://github.com/nanobpm/nano-workforce/issues/698) [pre-#698](https://github.com/nanobpm/pre-/issues/698)
+
+## [0.171.10](https://github.com/nanobpm/nano-workforce/compare/v0.171.9...v0.171.10) (2026-09-01)
+
+### Bug Fixes
+
+* **service:** emit world-restore SHA under harness-read `sha` key ([#696](https://github.com/nanobpm/nano-workforce/issues/696)) ([9794994](https://github.com/nanobpm/nano-workforce/commit/97949948913087c84f79bf0fcaa283c85a7cab0e)), closes [#324](https://github.com/nanobpm/nano-workforce/issues/324) [#695](https://github.com/nanobpm/nano-workforce/issues/695)
+
 ## [0.171.9](https://github.com/nanobpm/nano-workforce/compare/v0.171.8...v0.171.9) (2026-09-01)
 
 ### Bug Fixes

package/app/contracts.ts

@@ -384,9 +384,9 @@ export const WIRE_CONTRACTS = {
     name: "io.nanobpm.agentTask.repository",
     owner: "app/repoEnvelope.ts",
     semantics:
-      "Repo-provisioning envelope the app emits as a `createInstance` process variable (`repoEnvelopeVars`, app/repoEnvelope.ts) and the c8ctl worker harness consumes to provision an isolated clone — instead of the agent inheriting the worker's launch dir (issue #684). `ref` is the branch checked out: the PR HEAD branch on the PR-based paths (review-round / fix-ci / rebase), or — on the PRE-PR implementation path (feature.bpmn / plan-fanout's `implement-cell`, issue #684; the delivery-graph runner's agent cells, issue #686) — the BASE branch, off which the harness cuts a new feature branch named by the optional `branch.create` (the deterministic `feat/<task.id>`, emitted only for a single-task feature run; the epic seed AND the delivery-graph run-root seed omit it so each fan-out slice's agent branches per node/MI child). Beyond `{provider,url,ref}`, it carries clone-shaping fields for large monorepos (issue #287): `singleBranch:true` + `filter:\"blob:none\"` (a branch-scoped, blobless partial clone — trees fetched up-front, blobs lazily, no `--depth 1` so the merge-base/3-dot diff stays valid) and an optional `baseRef` (the PR base branch, emitted only when resolvable, so the harness fetches its tip and keeps `origin/<base>` reachable). World-restore (issue #324, ADR 0062 Slice 4/5): an optional `commitSha` — the last durable push-checkpoint — is emitted so a REPLACEMENT activation on a fresh worktree reconstructs the tree to the EXACT pushed SHA (inverting the round's `git push` into `git fetch && git checkout <sha>`), omitted when the PR has no checkpoint yet. Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91).",
+      "Repo-provisioning envelope the app emits as a `createInstance` process variable (`repoEnvelopeVars`, app/repoEnvelope.ts) and the c8ctl worker harness consumes to provision an isolated clone — instead of the agent inheriting the worker's launch dir (issue #684). `ref` is the branch checked out: the PR HEAD branch on the PR-based paths (review-round / fix-ci / rebase), or — on the PRE-PR implementation path (feature.bpmn / plan-fanout's `implement-cell`, issue #684; the delivery-graph runner's agent cells, issue #686) — the BASE branch, off which the harness cuts a new feature branch named by the optional `branch.create` (the deterministic `feat/<task.id>`, emitted only for a single-task feature run; the epic seed AND the delivery-graph run-root seed omit it so each fan-out slice's agent branches per node/MI child). Beyond `{provider,url,ref}`, it carries clone-shaping fields for large monorepos (issue #287): `singleBranch:true` + `filter:\"blob:none\"` (a branch-scoped, blobless partial clone — trees fetched up-front, blobs lazily, no `--depth 1` so the merge-base/3-dot diff stays valid) and an optional `baseRef` (the PR base branch, emitted only when resolvable, so the harness fetches its tip and keeps `origin/<base>` reachable). World-restore (issue #324, ADR 0062 Slice 4/5): an optional `sha` — the last durable push-checkpoint — is emitted so a REPLACEMENT activation on a fresh worktree reconstructs the tree to the EXACT pushed SHA (inverting the round's `git push` into `git fetch && git checkout <sha>`), omitted when the PR has no checkpoint yet. The field is named `sha` because that is the field the c8ctl harness's `provisionRepo` reads to drive the checkout — an earlier `commitSha` key was a silent no-op (issue #695). Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91).",
     shape:
-      '{ provider: "github", url: string, ref: string, singleBranch: true, filter: "blob:none", baseRef?: string, commitSha?: string, branch?: { create: string } }',
+      '{ provider: "github", url: string, ref: string, singleBranch: true, filter: "blob:none", baseRef?: string, sha?: string, branch?: { create: string } }',
   },
   "epicSet.submit": {
     category: "wire",

package/app/repoEnvelope.ts

@@ -36,10 +36,12 @@ const AGENT_TASK_NS = "io.nanobpm.agentTask";
  * that base reachable for the diff.
  *
  * World-restore (issue #324, ADR 0062 Slice 4/5): when a PR already has a durable push-checkpoint,
- * `commitSha` is emitted so a REPLACEMENT activation (a fresh worktree after a lease loss)
- * reconstructs the working tree to the EXACT pushed SHA — the inversion of the round's outbound
- * `git push` into an inbound `git fetch && git checkout <sha>` — rather than to a branch tip that may
- * have moved. Omitted (no key) when the PR has no checkpoint yet, so a first activation clones the
+ * the last pushed SHA is emitted under the `sha` key so a REPLACEMENT activation (a fresh worktree
+ * after a lease loss) reconstructs the working tree to the EXACT pushed SHA — the inversion of the
+ * round's outbound `git push` into an inbound `git fetch && git checkout <sha>` — rather than to a
+ * branch tip that may have moved. The key is `sha` (not `commitSha`) because that is the field the
+ * c8ctl worker harness actually reads to drive the checkout; the earlier `commitSha` key was a silent
+ * no-op (issue #695). Omitted (no key) when the PR has no checkpoint yet, so a first activation clones the
  * head branch normally.
  *
  * Pre-PR provisioning (issue #684): the implementation path (feature.bpmn / plan-fanout's
@@ -80,13 +82,16 @@ export function repoEnvelopeVars(
         // single-branch head, keeping `origin/<base>` reachable for the diff. Omitted when unknown.
         ...(baseRef ? { baseRef } : {}),
         // World-restore (issue #324): the last pushed SHA a replacement activation reconstructs the
-        // working tree to (inverting the round's push into a fetch+checkout). Only emitted when it is
-        // a well-formed 40-hex commit SHA: `commitSha` is forwarded to the harness as an EXACT
-        // checkout target, so a non-SHA ref or a whitespace-tainted value could reconstruct to an
-        // unintended ref (a moved branch tip) or fail provisioning. A malformed value degrades to
+        // working tree to (inverting the round's push into a fetch+checkout). Emitted under the key
+        // `sha` — the field the c8ctl worker harness actually reads (`provisionRepo` normalizes
+        // `repo.sha` and drives `git fetch origin <sha>` + `git checkout --detach <sha>` off it); a
+        // prior `commitSha` key was a silent no-op the harness never read (issue #695). Only emitted
+        // when the value is a well-formed 40-hex commit SHA: it is forwarded to the harness as an
+        // EXACT checkout target, so a non-SHA ref or a whitespace-tainted value could reconstruct to
+        // an unintended ref (a moved branch tip) or fail provisioning. A malformed value degrades to
         // omission — the harness then clones the head branch tip, the pre-#324 behaviour. Omitted too
         // when the PR has no durable push-checkpoint yet.
-        ...(isCommitSha(commitSha) ? { commitSha } : {}),
+        ...(isCommitSha(commitSha) ? { sha: commitSha } : {}),
         // Pre-PR provisioning (issue #684): the implementation path (feature.bpmn / plan-fanout's
         // implement-cell) dispatches its agent BEFORE any PR exists, so `ref` is the BASE branch, not a
         // head. `branchCreate` asks the harness to cut the deterministic `feat/<task.id>` feature branch

package/app/service.test.ts

@@ -534,20 +534,24 @@ test("repoEnvelopeVars emits nothing for a malformed repo (not owner/repo)", ()
   }
 });
 
-test("repoEnvelopeVars emits commitSha only for a well-formed 40-hex SHA (world-restore, #324)", () => {
+test("repoEnvelopeVars emits the push-checkpoint under the harness-read `sha` key, only for a well-formed 40-hex SHA (world-restore, #324/#695)", () => {
   const sha = "77ee0993cc6ad4493da0f7551212ef16722135db";
   const env = (repoEnvelopeVars("owner/repo", "feat/x", "main", sha) as any)["io.nanobpm.agentTask"];
-  assertEquals(env.repository.commitSha, sha, "a valid 40-hex SHA is threaded through as the exact checkout target");
-  // A non-SHA ref, an abbreviated SHA, or a whitespace-tainted value is dropped (no `commitSha` key):
-  // it is forwarded to the harness as an EXACT checkout target, so a bad value could reconstruct to a
-  // moved branch tip or fail provisioning. Omission degrades to the pre-#324 head-branch-tip clone.
+  // The emitted key MUST be `sha` — the field the c8ctl harness `provisionRepo` reads to drive
+  // `git fetch origin <sha>` + `git checkout --detach <sha>`. A prior `commitSha` key was a silent
+  // no-op the harness never read (issue #695), so guard the exact wire name here, not just presence.
+  assertEquals(env.repository.sha, sha, "a valid 40-hex SHA is threaded through under the harness-read `sha` key");
+  assertEquals("commitSha" in env.repository, false, "the retired `commitSha` key must never be emitted (silent no-op, #695)");
+  // A non-SHA ref, an abbreviated SHA, or a whitespace-tainted value is dropped (no `sha` key): it is
+  // forwarded to the harness as an EXACT checkout target, so a bad value could reconstruct to a moved
+  // branch tip or fail provisioning. Omission degrades to the pre-#324 head-branch-tip clone.
   for (const bad of ["main", "feat/x", "77ee099", `${sha} `, ` ${sha}`, `${sha}\n`, "z".repeat(40), `${sha}0`, ""]) {
     const r = (repoEnvelopeVars("owner/repo", "feat/x", "main", bad) as any)["io.nanobpm.agentTask"].repository;
-    assertEquals("commitSha" in r, false, `expected no commitSha for "${JSON.stringify(bad)}"`);
+    assertEquals("sha" in r, false, `expected no sha for "${JSON.stringify(bad)}"`);
   }
   // Omitted entirely when there is no checkpoint SHA at all (the common first-activation case).
   const none = (repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"].repository;
-  assertEquals("commitSha" in none, false);
+  assertEquals("sha" in none, false);
 });
 
 // Pre-PR provisioning (issue #684): the implementation path has no head branch yet, so it passes

package/docs/mcp-runbook.md

@@ -133,6 +133,41 @@ header on **both reads and mutations** — read endpoints like `GET /app/api/age
 `/app/mcp` follows the same `network.bind` manifest setting as the rest of the app's
 HTTP surface.
 
+### Framework mutation guard — `urban_debug_*` mutations need `x-hook-secret` too
+
+The framework-owned **mutating** `urban_debug_*` tools (`set_variables`, `retry_job`,
+`resolve_incident`, `cancel_instance`) are gated by the Urban runtime's *own* mutation
+guard (`authorizeMutation`), which is separate from nwf's app-operation guard above. It
+authorizes a mutation one of two ways:
+
+1. **Loopback bypass** — `URBAN_MCP_ALLOW_MUTATIONS=true` **and** `mcp.allowRemote` off.
+   This is the credential-free, local-only path; it is disabled the moment the surface is
+   remote-exposed (`allowRemote` on), by design — the guard never drops for a non-loopback
+   caller.
+2. **Shared-secret scheme** — an apiKey *header* security scheme that declares an
+   `x-nano-secret-env` extension naming the env var holding the secret. nwf declares this
+   on **`hookSecret`** (`x-nano-secret-env: NANO_PR_WEBHOOK_SECRET`), so a mutating
+   `urban_debug_*` call carrying `x-hook-secret: <NANO_PR_WEBHOOK_SECRET>` is authorized on
+   a remote-exposed instance.
+
+This is the **same secret and same header** as nwf's app-operation guard (both key on
+`NANO_PR_WEBHOOK_SECRET` via `x-hook-secret`), so reads and mutations — app-operation and
+framework — share one credential. The MCP server entry's `headers` already carries it (§1);
+nothing extra is needed for `urban_debug_*` mutations once the secret is set.
+
+**Fail-closed caveat.** When `NANO_PR_WEBHOOK_SECRET` is **unset** there is no credential to
+present, so on a remote-exposed instance (`allowRemote` on) framework mutations remain
+**closed** — this is correct fail-closed behavior, not a regression. Because the scheme is now
+*declared* (it names the env var) but the secret is absent, the runtime surfaces the attempt as a
+`500` *security-misconfigured* ("secret env `NANO_PR_WEBHOOK_SECRET` is not set") rather than a
+plain refusal — either way no mutation occurs. An operator who needs remote mutation repair (e.g.
+patching a wedged instance's variable + retrying a `JOB_NO_RETRIES` job) must set
+`NANO_PR_WEBHOOK_SECRET`; then a `urban_debug_*` mutation carrying `x-hook-secret: <secret>`
+succeeds, while a missing or wrong header `401`s. The loopback bypass
+(`URBAN_MCP_ALLOW_MUTATIONS=true` with `allowRemote` off) remains the credential-free
+local-only alternative. Only `hookSecret` may carry `x-nano-secret-env` — the runtime
+throws on more than one shared-secret scheme.
+
 **Operator-only doors stay operator-only.** The staged delivery-graph lifecycle —
 `stageDeliveryGraph`, `dispatchDeliveryGraph`, `dismissProposal` — is `x-mcp`-excluded
 from the projected tool surface (ADR 0067 §2): the human clicking **Dispatch** in the

package/e2e/mcp-surface.e2e.ts

@@ -184,12 +184,18 @@ describe("MCP surface e2e — the runtime-served /app/mcp handshake, per tool (S
   });
 
   test("mutating framework tools are gated without the shared secret (set-variables)", async () => {
+    // This harness boots WITHOUT `NANO_PR_WEBHOOK_SECRET`. Since #698 declares the `hookSecret`
+    // shared-secret scheme (`x-nano-secret-env`), a remote-exposed mutation now fails CLOSED
+    // DETERMINISTICALLY as a misconfiguration ("secret env … is not set") — the credential the guard
+    // requires cannot exist until the operator sets the env var. Pin exactly that new shape (NOT the
+    // pre-#698 no-scheme "shared secret"/"allowMutations" refusal), so the test actually proves #698's
+    // `x-nano-secret-env` declaration took effect rather than accepting the old behavior.
     const res = await h.callTool("urban_debug_set_variables", { processInstanceKey: "1", variables: {} });
     assert.ok(res.isError, "urban_debug_set_variables must refuse a credential-free mutation");
     assert.match(
       res.text,
-      /shared secret|allowMutations/i,
-      `the refusal must name the guard: ${res.text}`,
+      /secret env .* is not set|misconfigured/i,
+      `the refusal must be the #698 misconfiguration shape: ${res.text}`,
     );
   });
 
@@ -264,3 +270,71 @@ describe("MCP surface e2e — the runtime-served /app/mcp handshake, per tool (S
     assert.deepEqual(json?.proposals, [], "no live staged proposals may remain");
   });
 });
+
+// Framework mutation-guard authorization (issue #698).
+// --------------------------------------------------------------------------
+// The framework-owned mutating `urban_debug_*` tools (set_variables/retry_job/resolve_incident/
+// cancel_instance) are gated by @nanobpm/urban's OWN mutation guard (`authorizeMutation`), distinct
+// from nwf's app-operation guard. On a REMOTE-exposed instance (the harness always boots with
+// `URBAN_MCP_ALLOW_REMOTE: "true"`) the loopback bypass is off, so the ONLY door left is the
+// shared-secret apiKey scheme — which the guard recognizes only when an apiKey *header* scheme
+// declares `x-nano-secret-env`. nwf now declares `x-nano-secret-env: NANO_PR_WEBHOOK_SECRET` on the
+// `hookSecret` scheme (this issue), so a mutating call carrying `x-hook-secret: <secret>` is
+// authorized past the guard, while a missing/wrong header stays 401. This pins that contract.
+const HOOK_SECRET = "issue-698-shared-secret";
+
+describe("MCP surface e2e — framework mutation guard authorizes with the shared secret (#698)", () => {
+  let h: McpHarness;
+
+  before(async () => {
+    // Remote-exposed (harness default) + a shared secret set: the exact condition of #698, where the
+    // loopback bypass is off and the shared-secret scheme is the only authorization door.
+    h = await bootMcpHarness({ env: { NANO_PR_WEBHOOK_SECRET: HOOK_SECRET } });
+  });
+
+  after(async () => {
+    await h?.stop();
+  });
+
+  test("a mutating urban_debug_* call is refused WITHOUT the shared-secret header", async () => {
+    const res = await h.callTool("urban_debug_set_variables", { processInstanceKey: "1", variables: {} });
+    assert.ok(res.isError, "a credential-free mutation must be refused on a remote-exposed instance");
+    assert.match(
+      res.text,
+      /unauthorized|401/i,
+      `a missing shared-secret header must 401: ${res.text}`,
+    );
+  });
+
+  test("a mutating urban_debug_* call is refused WITH A WRONG shared-secret header", async () => {
+    const res = await h.callTool(
+      "urban_debug_set_variables",
+      { processInstanceKey: "1", variables: {} },
+      { "x-hook-secret": "not-the-secret" },
+    );
+    assert.ok(res.isError, "a wrong-secret mutation must still be refused");
+    assert.match(
+      res.text,
+      /unauthorized|401/i,
+      `a wrong shared-secret header must 401: ${res.text}`,
+    );
+  });
+
+  test("a mutating urban_debug_* call carrying the correct x-hook-secret is authorized past the guard", async () => {
+    const res = await h.callTool(
+      "urban_debug_set_variables",
+      { processInstanceKey: "1", variables: {} },
+      { "x-hook-secret": HOOK_SECRET },
+    );
+    // The correct credential clears the shared-secret guard. The call may still fail downstream (the
+    // hermetic engine has no instance `1`), but it must NO LONGER be the shared-secret refusal NOR a
+    // generic authorization failure (401/unauthorized) — excluding those is the falsifiable proof the
+    // `x-nano-secret-env` declaration made the scheme authorizable (rather than the credential silently
+    // still being rejected).
+    assert.doesNotMatch(
+      res.text,
+      /shared secret|allowMutations|NO_SHARED_SECRET|unauthorized|401/i,
+      `the authorized call must clear the shared-secret guard, got: ${res.text}`,
+    );
+  });
+});

package/e2e/support/mcp-harness.ts

@@ -125,8 +125,9 @@ export interface McpHarness {
   readonly sessionId: string;
   /** `tools/list` — the projected tool catalogue (app operations + framework debug tools). */
   listTools(): Promise<McpTool[]>;
-  /** `tools/call` — invoke a tool by name with its argument object. */
-  callTool(name: string, args?: Record<string, unknown>): Promise<McpToolResult>;
+  /** `tools/call` — invoke a tool by name with its argument object. Optional `extraHeaders` are
+   *  overlaid on the POST (e.g. an `x-hook-secret` shared-secret credential for a gated mutation). */
+  callTool(name: string, args?: Record<string, unknown>, extraHeaders?: Record<string, string>): Promise<McpToolResult>;
   /** A raw JSON-RPC request against `/app/mcp` (escape hatch for a bespoke case). `params` omitted →
    *  no `params` field; a `notifications/*` method is sent as a notification (no `id`, no response). */
   rpc(method: string, params?: unknown): Promise<McpRpcResult>;
@@ -175,13 +176,22 @@ export async function bootMcpHarness(opts: BootMcpHarnessOptions = {}): Promise<
   }
 
   let idCounter = 0;
-  const rpc = async (method: string, params?: unknown, sessionId?: string): Promise<McpRpcResult> => {
+  const rpc = async (
+    method: string,
+    params?: unknown,
+    sessionId?: string,
+    extraHeaders?: Record<string, string>,
+  ): Promise<McpRpcResult> => {
     const headers: Record<string, string> = {
       "content-type": "application/json",
       // The Streamable-HTTP transport inspects Accept; a real client offers both even when the
       // server answers JSON (the runtime sets `enableJsonResponse`).
       accept: "application/json, text/event-stream",
     };
+    // Apply caller-supplied overlay headers FIRST so the session header stays authoritative — a
+    // caller passing auth headers (e.g. `x-hook-secret`) must not be able to clobber `mcp-session-id`
+    // and break the MCP handshake for this request.
+    if (extraHeaders) Object.assign(headers, extraHeaders);
     if (sessionId) headers[SESSION_HEADER] = sessionId;
     const isNotification = method.startsWith("notifications/");
     const message: Record<string, unknown> = { jsonrpc: "2.0", method };
@@ -252,8 +262,8 @@ export async function bootMcpHarness(opts: BootMcpHarnessOptions = {}): Promise<
       }
       return body.result.tools;
     },
-    async callTool(name, args = {}): Promise<McpToolResult> {
-      const res = await rpc("tools/call", { name, arguments: args }, sessionId);
+    async callTool(name, args = {}, extraHeaders): Promise<McpToolResult> {
+      const res = await rpc("tools/call", { name, arguments: args }, sessionId, extraHeaders);
       const body = res.body as
         | { result?: { isError?: boolean; content?: Array<{ type: string; text?: string }> }; error?: { message?: string } }
         | undefined;

package/openapi.yaml

@@ -24,9 +24,16 @@ components:
       type: apiKey
       in: header
       name: x-hook-secret
-      description: Optional shared secret. Enforced by the delegate (NOT the runtime) only when
-        NANO_PR_WEBHOOK_SECRET is set; unset means the endpoint is open. Declared here for
-        documentation.
+      x-nano-secret-env: NANO_PR_WEBHOOK_SECRET
+      description: Shared secret. Enforced by the delegate (NOT the runtime) on this app's own
+        operations only when NANO_PR_WEBHOOK_SECRET is set; unset means those endpoints are open.
+        The `x-nano-secret-env` extension additionally makes this the app's canonical shared-secret
+        scheme for the Urban runtime's framework mutation guard (`authorizeMutation`), so the
+        framework-owned mutating `urban_debug_*` MCP tools (set_variables, retry_job,
+        resolve_incident, cancel_instance) are authorizable on a remote-exposed instance by
+        presenting the `x-hook-secret` header set to NANO_PR_WEBHOOK_SECRET. One shared secret, one
+        header, for both app-operation reads/mutations and framework mutations. Must remain the sole
+        apiKey scheme carrying `x-nano-secret-env` — the runtime throws on ambiguity.
   schemas:
     ErrorBody:
       type: object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.171.9",
+  "version": "0.171.11",
   "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/overview.page.json

@@ -84,7 +84,7 @@
           "title": "Point your agent at Nano Workforce",
           "description": "Copy this prompt and paste it into your coding agent (Copilot, Claude, etc.). It connects the agent to this instance's MCP server \u2014 the workforce's operations become native tools (including the live operator guide as `getAgentInstructions`, or its addressable companion `getAgentGuide(section?)` \u2014 preferred over the ~43KB blob to avoid tool-result overrun), so it can drive and debug your workforce; agents with no MCP client fall back to fetching the operator skill. Note: `/app/mcp` is served on the same HTTP surface as the rest of the app \u2014 reachable on loopback by default, and from a remote instance (merlin, an ngrok tunnel) only when the app is bound wide (`network.bind`) or fronted by a reverse proxy, per the MCP runbook.",
           "copyLabel": "Copy prompt",
-          "copyText": "Add this running Nano Workforce instance as an MCP server, then help me drive and debug my workforce \u2014 a durable orchestration app that drives pull requests to review convergence against an automated reviewer, merges them, and can take a whole issue and plan \u2192 implement \u2192 converge it across a fleet of coding agents.\n\nRegister ONE MCP server entry per instance (streamable-HTTP transport, URL {{appBase}}app/mcp). Naming the instance makes targeting the wrong one structurally impossible \u2014 its tools are namespaced under that name:\n\n    copilot mcp add --transport http workforce-local {{appBase}}app/mcp\n\nGive each instance its own entry (e.g. `workforce-merlin` for a LAN/remote node). In config form (~/.copilot/mcp-config.json or repo-scoped .mcp.json):\n\n    {\n      \"mcpServers\": {\n        \"workforce-local\": {\n          \"type\": \"http\",\n          \"url\": \"{{appBase}}app/mcp\",\n          \"tools\": [\"*\"]\n        }\n      }\n    }\n\nIf this instance is secured with a shared secret (NANO_PR_WEBHOOK_SECRET), pass it on the MCP connection \u2014 reads AND mutations both require it:\n\n    copilot mcp add --transport http workforce-local {{appBase}}app/mcp \\\n      --header \"x-hook-secret: $NANO_PR_WEBHOOK_SECRET\"\n\nIn config form, add a `headers` entry alongside `url` on that server (per the MCP runbook) \u2014 the config path has no header flag, so omitting this yields 401s:\n\n    \"headers\": { \"x-hook-secret\": \"$NANO_PR_WEBHOOK_SECRET\" }\n\nA Basic-Auth-fronted instance (behind a reverse proxy) additionally needs `Authorization: Basic \u2026` on the connection.\n\nMCP servers register at host startup \u2014 add the entry, THEN start a new session so its tools load. The `workforce-*` tools then appear (the full set of operations projected from this instance's OpenAPI contract, including the live operator guide itself as the `getAgentInstructions` read tool \u2014 or its addressable companion `getAgentGuide(section?)`, which the MCP runbook recommends over the ~43KB blob to avoid tool-result overrun \u2014 plus the `urban_debug_*` family for inspecting a wedged instance's process instances, wait states, and incidents).\n\nThe instance's operations are now native tools. Ask, naming the instance: \"Using workforce-local, show what's in flight and any open escalations.\" It should call the status tool, not curl. Operator-only doors (the delivery-graph stage/dispatch/dismiss lifecycle \u2014 the human click IS the approval) are deliberately not tools.\n\nNo MCP client? The curl path is unchanged \u2014 fetch and follow the live guide (the response is JSON with a `skill` markdown field), adding `-H \"x-hook-secret: <secret>\"` if this instance is secured:\n\n    curl -sS {{appBase}}app/api/agent/skill\n\nThat skill bootstraps you to this instance's live operator guide at {{appBase}}app/api/agent (the same guide MCP exposes as `getAgentInstructions`, or section-addressably as `getAgentGuide`). If you find a bug or a stuck process, the guide explains how to raise an issue or a PR against nanobpm/nano-workforce."
+          "copyText": "Add this running Nano Workforce instance as an MCP server, then help me drive and debug my workforce \u2014 a durable orchestration app that drives pull requests to review convergence against an automated reviewer, merges them, and can take a whole issue and plan \u2192 implement \u2192 converge it across a fleet of coding agents.\n\nRegister ONE MCP server entry per instance (streamable-HTTP transport, URL {{appBase}}app/mcp). Naming the instance makes targeting the wrong one structurally impossible \u2014 its tools are namespaced under that name:\n\n    copilot mcp add --transport http workforce-local {{appBase}}app/mcp\n\nGive each instance its own entry (e.g. `workforce-merlin` for a LAN/remote node). In config form (~/.copilot/mcp-config.json or repo-scoped .mcp.json):\n\n    {\n      \"mcpServers\": {\n        \"workforce-local\": {\n          \"type\": \"http\",\n          \"url\": \"{{appBase}}app/mcp\",\n          \"tools\": [\"*\"]\n        }\n      }\n    }\n\nIf this instance is secured with a shared secret (NANO_PR_WEBHOOK_SECRET), pass it on the MCP connection \u2014 reads AND mutations both require it (including the framework-owned mutating urban_debug_* tools \u2014 set_variables, retry_job, resolve_incident, cancel_instance \u2014 which authorize against this same x-hook-secret on a remote-exposed instance):\n\n    copilot mcp add --transport http workforce-local {{appBase}}app/mcp \\\n      --header \"x-hook-secret: $NANO_PR_WEBHOOK_SECRET\"\n\nIn config form, add a `headers` entry alongside `url` on that server (per the MCP runbook) \u2014 the config path has no header flag, so omitting this yields 401s:\n\n    \"headers\": { \"x-hook-secret\": \"$NANO_PR_WEBHOOK_SECRET\" }\n\nA Basic-Auth-fronted instance (behind a reverse proxy) additionally needs `Authorization: Basic \u2026` on the connection.\n\nMCP servers register at host startup \u2014 add the entry, THEN start a new session so its tools load. The `workforce-*` tools then appear (the full set of operations projected from this instance's OpenAPI contract, including the live operator guide itself as the `getAgentInstructions` read tool \u2014 or its addressable companion `getAgentGuide(section?)`, which the MCP runbook recommends over the ~43KB blob to avoid tool-result overrun \u2014 plus the `urban_debug_*` family for inspecting a wedged instance's process instances, wait states, and incidents).\n\nThe instance's operations are now native tools. Ask, naming the instance: \"Using workforce-local, show what's in flight and any open escalations.\" It should call the status tool, not curl. Operator-only doors (the delivery-graph stage/dispatch/dismiss lifecycle \u2014 the human click IS the approval) are deliberately not tools.\n\nNo MCP client? The curl path is unchanged \u2014 fetch and follow the live guide (the response is JSON with a `skill` markdown field), adding `-H \"x-hook-secret: <secret>\"` if this instance is secured:\n\n    curl -sS {{appBase}}app/api/agent/skill\n\nThat skill bootstraps you to this instance's live operator guide at {{appBase}}app/api/agent (the same guide MCP exposes as `getAgentInstructions`, or section-addressably as `getAgentGuide`). If you find a bug or a stuck process, the guide explains how to raise an issue or a PR against nanobpm/nano-workforce."
         }
       }
     },