@nanobpm/nano-workforce 0.171.10 → 0.172.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.172.0](https://github.com/nanobpm/nano-workforce/compare/v0.171.11...v0.172.0) (2026-09-01)
+
+### Features
+
+* **service:** emit repository.cloneTimeoutMs in the agent-task envelope ([#697](https://github.com/nanobpm/nano-workforce/issues/697)) ([0d8a358](https://github.com/nanobpm/nano-workforce/commit/0d8a3582769f6561d647563168a8a50d0d54f3df)), closes [#694](https://github.com/nanobpm/nano-workforce/issues/694)
+
+## [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

package/app/contracts.ts

@@ -96,6 +96,14 @@ export const ENV_CONTRACTS = {
     semantics: "Poller cadence in milliseconds for the self-scheduling reconciliation loop.",
     default: "60000",
   },
+  NANO_PR_CLONE_TIMEOUT_MS: {
+    category: "env",
+    name: "NANO_PR_CLONE_TIMEOUT_MS",
+    owner: "app/repoEnvelope.ts",
+    semantics:
+      "Clone timeout in milliseconds emitted as `repository.cloneTimeoutMs` in the agent-task envelope so the c8ctl harness raises its 120s default for large-repo provisioning (branch-scoped blobless clones of big monorepos still approach/exceed 120s; issue #694). Inherited by both the review-round and merge paths via the one `repoEnvelopeVars` builder.",
+    default: "600000",
+  },
   NANO_PR_MAX_ROUNDS: {
     category: "env",
     name: "NANO_PR_MAX_ROUNDS",
@@ -384,9 +392,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 `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).",
+      "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) and a `cloneTimeoutMs` (from `NANO_PR_CLONE_TIMEOUT_MS`, default 600000 = 10 min) that raises the harness's 120s default so a large monorepo's blobless single-branch clone provisions instead of dying at 120s (issue #694). 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, sha?: string, branch?: { create: string } }',
+      '{ provider: "github", url: string, ref: string, singleBranch: true, filter: "blob:none", cloneTimeoutMs: number, baseRef?: string, sha?: string, branch?: { create: string } }',
   },
   "epicSet.submit": {
     category: "wire",

package/app/repoEnvelope.ts

@@ -8,6 +8,7 @@
 // rebase) and the PRE-PR implementation dispatch (`feature.ts`: `startFeature`; `plan.ts`:
 // `startPlan` → the epic's `implement-cell`) derive from this single implementation without a
 // `plan.ts ↔ service.ts` import cycle (AGENTS.md "derivation over duplication — no drift surfaces").
+import { readEnvOr } from "./contracts.ts";
 import { isCommitSha } from "./world/index.ts";
 
 /** The reserved namespace key the c8ctl nano worker harness reads the agent-task envelope from
@@ -78,6 +79,13 @@ export function repoEnvelopeVars(
         // has a valid merge-base. Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91).
         singleBranch: true,
         filter: "blob:none",
+        // Raise the harness's 120s default clone timeout for large-repo provisioning (issue #694).
+        // A branch-scoped blobless clone of a 24.6k-file monorepo (`camunda/camunda`) still
+        // approaches/exceeds 120s, so we emit `cloneTimeoutMs` (default 600000 = 10 min, via the
+        // `NANO_PR_CLONE_TIMEOUT_MS` knob) rather than let the harness fall back to its 120000ms
+        // default. Emitted on ALL paths from this one builder, so BOTH the review-round path
+        // (`service.ts` `submitPr`) and the merge path (`service.ts` `startMerge`) inherit it.
+        cloneTimeoutMs: cloneTimeoutMs(),
         // The base branch this PR targets — emitted so the harness fetches its tip alongside the
         // single-branch head, keeping `origin/<base>` reachable for the diff. Omitted when unknown.
         ...(baseRef ? { baseRef } : {}),
@@ -105,3 +113,16 @@ export function repoEnvelopeVars(
     },
   };
 }
+
+/** Resolve the clone timeout (ms) the harness applies to provisioning, from the one typed knob
+ * `NANO_PR_CLONE_TIMEOUT_MS` (default 600000 = 10 min; issue #694). A branch-scoped blobless clone
+ * of a large monorepo still approaches/exceeds the harness's 120s default, so we raise it here. A
+ * non-numeric or non-positive override degrades to the registered default rather than emitting a
+ * bogus (0 / NaN) timeout the harness would then treat as "use the 120s default". */
+function cloneTimeoutMs(): number {
+  const raw = Number(readEnvOr("NANO_PR_CLONE_TIMEOUT_MS"));
+  return Number.isFinite(raw) && raw > 0 ? raw : Number(envDefaultCloneTimeoutMs);
+}
+
+/** The registered default, resolved once from the schema so the fallback stays single-sourced. */
+const envDefaultCloneTimeoutMs = readEnvOr("NANO_PR_CLONE_TIMEOUT_MS", "600000", {});

package/app/service.test.ts

@@ -483,6 +483,38 @@ test("repoEnvelopeVars emits the repository envelope keyed on the PR head branch
   assertEquals(env.repository.filter, "blob:none");
   // The base branch is emitted so the harness fetches its tip, keeping `origin/<base>` reachable.
   assertEquals(env.repository.baseRef, "main");
+  // The clone timeout is raised above the harness's 120s default for large-repo provisioning (#694).
+  assertEquals(env.repository.cloneTimeoutMs, 600000);
+});
+
+test("repoEnvelopeVars emits cloneTimeoutMs from NANO_PR_CLONE_TIMEOUT_MS, default 600000 (#694)", () => {
+  // Default (knob unset): 600000ms = 10 min, raising the harness's 120000ms default so a
+  // branch-scoped blobless clone of a large monorepo provisions instead of dying at 120s.
+  const prev = process.env.NANO_PR_CLONE_TIMEOUT_MS;
+  delete process.env.NANO_PR_CLONE_TIMEOUT_MS;
+  try {
+    const def = (repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"];
+    assertEquals(def.repository.cloneTimeoutMs, 600000);
+    // Override wins.
+    process.env.NANO_PR_CLONE_TIMEOUT_MS = "900000";
+    const over = (repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"];
+    assertEquals(over.repository.cloneTimeoutMs, 900000);
+    // A non-positive / non-numeric override degrades to the registered default rather than emitting
+    // a bogus 0/NaN the harness would treat as "use the 120s default".
+    process.env.NANO_PR_CLONE_TIMEOUT_MS = "0";
+    assertEquals(
+      ((repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"]).repository.cloneTimeoutMs,
+      600000,
+    );
+    process.env.NANO_PR_CLONE_TIMEOUT_MS = "notanumber";
+    assertEquals(
+      ((repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"]).repository.cloneTimeoutMs,
+      600000,
+    );
+  } finally {
+    if (prev === undefined) delete process.env.NANO_PR_CLONE_TIMEOUT_MS;
+    else process.env.NANO_PR_CLONE_TIMEOUT_MS = prev;
+  }
 });
 
 test("repoEnvelopeVars omits baseRef when the base branch is unresolved", () => {
@@ -492,6 +524,8 @@ test("repoEnvelopeVars omits baseRef when the base branch is unresolved", () =>
   assertEquals(env.repository.filter, "blob:none");
   // …but `baseRef` is omitted entirely rather than emitted as null (no key at all).
   assertEquals("baseRef" in env.repository, false);
+  // The clone timeout is still emitted (it's base-ref-independent).
+  assertEquals(env.repository.cloneTimeoutMs, 600000);
 });
 
 test("repoEnvelopeVars emits nothing when the head branch is unresolved", () => {

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.10",
+  "version": "0.172.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/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."
         }
       }
     },