@nanobpm/nano-workforce 0.169.0 → 0.170.1

package/openapi.yaml

@@ -108,8 +108,31 @@ components:
           type: string
           nullable: true
         openEscalation:
-          type: string
+          type: object
           nullable: true
+          additionalProperties: false
+          description: >-
+            The structured pointer to this PR's OPEN escalation when it is parked awaiting a human/agent
+            answer (issue #666), else null. Derived from the same `user_tasks` read model as
+            `listEscalations`, so `userTaskKey` is the completable key an agent answers via
+            `completeUserTask` / `agentCompleteEscalation` (no `/tasks/api/tasks` curl needed). `kind`
+            is the BPMN escalation elementId (e.g. `wait-answer`, `wait-merge-answer`); `summary` is the
+            raised question/findings (null when none was recorded).
+          required:
+            - userTaskKey
+            - kind
+            - summary
+          properties:
+            userTaskKey:
+              type: string
+              description: The completable engine user-task key (answer via completeUserTask / agentCompleteEscalation).
+            kind:
+              type: string
+              description: The BPMN escalation elementId (the escalation kind).
+            summary:
+              type: string
+              nullable: true
+              description: The raised question / findings, denormalised for display; null when none.
         updatedAt:
           type: string
         activeWorker:
@@ -130,6 +153,85 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/ActivePr"
+    Escalation:
+      type: object
+      description: >-
+        One OPEN native user-task escalation awaiting a human/agent decision (issue #666), projected
+        from the `user_tasks` read model. `userTaskKey` is the completable key an agent answers via
+        `completeUserTask` / `agentCompleteEscalation`; `kind` is the BPMN escalation elementId.
+      additionalProperties: false
+      required:
+        - userTaskKey
+        - kind
+        - kindLabel
+        - prKey
+        - subjectType
+        - subjectKey
+        - subjectTitle
+        - subjectUrl
+        - question
+        - formKey
+        - processKey
+        - formVariables
+      properties:
+        userTaskKey:
+          type: string
+          description: The completable engine user-task key (answer via completeUserTask / agentCompleteEscalation).
+        kind:
+          type: string
+          description: The BPMN escalation elementId (e.g. wait-answer, wait-merge-answer, plan-review-decision, trial-merge-decision, feature-escalation).
+        kindLabel:
+          type: string
+          description: Human-readable kind label (e.g. "PR review", "Plan review", "Trial merge").
+        prKey:
+          type: string
+          nullable: true
+          description: The PR key when this escalation belongs to a PR (review/merge loop); null for feature / plan / delivery / agent subjects.
+        subjectType:
+          type: string
+          description: The domain subject kind — feature | plan | pr | delivery | agent.
+        subjectKey:
+          type: string
+          description: The subject aggregate key (feature_key / plan_key / pr_key).
+        subjectTitle:
+          type: string
+          description: The subject's human-readable title (coalesced to subjectKey when unknown).
+        subjectUrl:
+          type: string
+          nullable: true
+          description: An optional external link (the issue/PR URL); null when none.
+        question:
+          type: string
+          nullable: true
+          description: The raised question / findings / task text the loop or agent recorded; null when none.
+        formKey:
+          type: string
+          nullable: true
+          description: The deployed `.form` key of the parked user task, for rendering/answering; null when unresolved.
+        processKey:
+          type: string
+          nullable: true
+          description: The owning engine process-instance key; null when unknown.
+        formVariables:
+          type: object
+          additionalProperties: true
+          description: >-
+            The denormalised decision/form context the Tasks inbox renders for this task (the same
+            question + subject the deployed form is seeded with). The typed answer fields an agent
+            submits depend on `kind` (e.g. a PR `{ answer }`, a plan-review `{ directive, notes }`).
+    EscalationList:
+      type: object
+      additionalProperties: false
+      required:
+        - count
+        - escalations
+      properties:
+        count:
+          type: integer
+        escalations:
+          type: array
+          items:
+            $ref: "#/components/schemas/Escalation"
     LineagePrView:
       type: object
       description: A member PR of a lineage thread (issue #245).
@@ -3057,6 +3159,36 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /escalations:
+    get:
+      operationId: listEscalations
+      summary: List every OPEN escalation awaiting a human/agent decision, with the completable userTaskKey.
+      description: >-
+        Discovery for the escalation-answer path (epic #664, issue #666): across every surfaced
+        escalation kind (PR review/merge loop, plan-review, empty-plan, trial-merge,
+        conformance-review, delivery human-step, feature/blocked, agent-permission and the shared
+        human-escalation cell), list each currently-open native user-task escalation with the
+        completable `userTaskKey` an agent then answers via `completeUserTask` /
+        `agentCompleteEscalation` — so a tool-aware agent never has to curl the un-projected
+        `/tasks/api/tasks` inbox to find keys. Read-only projection over the ONE `user_tasks` read
+        model the Tasks inbox and Convergence page consume (no second source of truth); a row is
+        present iff its task is open, so the list reflects live pending work.
+      security:
+        - hookSecret: []
+        - {}
+      responses:
+        "200":
+          description: The open escalations.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EscalationList"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /lineage:
     get:
       operationId: getLineage
@@ -3496,7 +3628,7 @@ paths:
             example: delivery-graphs
           description: OPTIONAL stable section id (from the table of contents `getAgentGuide` returns
             with no argument), e.g. `orient`, `submit-pr`, `submit-epic`, `escalations`, `lifecycle`,
-            `debug`, `debug-models`, `unstick`, `raise-issue`, `delivery-graphs`. Omit it to get the
+            `debug`, `debug-models`, `unstick`, `raise-issue`, `delivery-graphs`, `tool-crosswalk`. Omit it to get the
             table of contents. An unknown id yields a 400 listing the valid ids.
       responses:
         "200":

package/operations/listActivePrs.test.ts

@@ -8,14 +8,15 @@ import { noopLog } from "../test/log.ts";
 import { withTrackingViews } from "../test/trackingViews.ts";
 import handler from "./listActivePrs.ts";
 
-function memApp(rows: any[], escalations: any[] = []): AppApi {
+function memApp(rows: any[], userTaskRows: any[] = []): AppApi {
   const table = (name: string) => {
-    if (name === "escalations") {
+    if (name === "user_tasks") {
       return {
+        async all() {
+          return userTaskRows;
+        },
         async find(where: Record<string, unknown>) {
-          return escalations.filter((e) =>
-            Object.entries(where).every(([k, v]) => e[k] === v)
-          );
+          return userTaskRows.filter((t) => Object.entries(where).every(([k, v]) => t[k] === v));
         },
       };
     }
@@ -58,25 +59,42 @@ test("returns 200 with a count + projected active PRs", async () => {
   assertEquals(r.body.prs[0].processKey, "9");
 });
 
-test("surfaces openEscalation for an escalated PR from its open escalations row (both loops)", async () => {
-  // Regression: a merge-loop escalation parks on a message catch (no user task), so deriving
-  // openEscalation from a user-task probe hid it. Deriving from the canonical `escalations` row
-  // surfaces it. Two escalated PRs — one with an open row (visible), one already answered (null).
+test("surfaces the structured openEscalation from the user_tasks read model (both loops)", async () => {
+  // Issue #666: openEscalation is derived from the ONE `user_tasks` read model (the same surface
+  // `listEscalations` and the Convergence page consume), so `/status` carries the completable
+  // userTaskKey. A `user_tasks` row for a PR subject exists iff its review/merge-loop escalation task
+  // is currently open; a PR with no such row derives null. Cover a review-loop and a merge-loop PR.
   const app = memApp(
     [
       { pr_key: "o/r#10", repo: "o/r", number: 10, url: "u10", title: "merge blocked", status: "escalated", current_round: 3, process_key: "m1", updated_at: "2026-02-02" },
-      { pr_key: "o/r#11", repo: "o/r", number: 11, url: "u11", title: "answered", status: "escalated", current_round: 4, process_key: "m2", updated_at: "2026-02-01" },
+      { pr_key: "o/r#11", repo: "o/r", number: 11, url: "u11", title: "no open task", status: "escalated", current_round: 4, process_key: "m2", updated_at: "2026-02-01" },
     ],
     [
-      { id: 1, pr_key: "o/r#10", status: "open", question: "Resolve the conflict on the branch, then retry?" },
-      { id: 2, pr_key: "o/r#11", status: "answered", question: "old question" },
+      {
+        user_task_key: "ut-10",
+        element_id: "wait-merge-answer",
+        kind_label: "PR merge",
+        subject_type: "pr",
+        subject_key: "o/r#10",
+        subject_title: "merge blocked",
+        subject_url: null,
+        question: "Resolve the conflict on the branch, then retry?",
+        process_key: "m1",
+        form_key: null,
+        created_at: "2026-02-02",
+        updated_at: "2026-02-02",
+      },
     ],
   );
   const res = (await handler(input(), app)) as any;
   assertEquals(res.status, 200);
   const p10 = res.body.prs.find((p: any) => p.prKey === "o/r#10");
   const p11 = res.body.prs.find((p: any) => p.prKey === "o/r#11");
-  assertEquals(p10.openEscalation, "Resolve the conflict on the branch, then retry?");
+  assertEquals(p10.openEscalation, {
+    userTaskKey: "ut-10",
+    kind: "wait-merge-answer",
+    summary: "Resolve the conflict on the branch, then retry?",
+  });
   assertEquals(p11.openEscalation, null);
 });
 

package/operations/listEscalations.test.ts

@@ -0,0 +1,215 @@
+// Tests for GET /app/api/escalations operation `listEscalations` (epic #664, issue #666).
+//
+// The read tool that lists EVERY open native user-task escalation with its completable `userTaskKey`,
+// so a tool-aware agent discovers keys on-tool instead of curling the un-projected `/tasks/api/tasks`
+// inbox. It projects the ONE `user_tasks` read model (the same surface the Tasks inbox / Convergence
+// page consume) via the pure `toEscalationView` derivation — no second source of truth.
+//
+// The headline round-trip test proves the acceptance criterion: an open escalation is listed by
+// `listEscalations` with the EXACT `userTaskKey` that `completeUserTask` then resolves.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import completeHandler from "./completeUserTask.ts";
+import listHandler from "./listEscalations.ts";
+
+// biome-ignore lint/suspicious/noExplicitAny: in-memory doubles, mirrors sibling op tests
+function memApp(
+  seedUserTasks: Record<string, unknown>[],
+  openTasks: { userTaskKey: string; elementId?: string }[],
+): {
+  app: AppApi;
+  // biome-ignore lint/suspicious/noExplicitAny: see above
+  stores: Record<string, any[]>;
+  completed: { userTaskKey: string; variables: Record<string, unknown> }[];
+} {
+  // biome-ignore lint/suspicious/noExplicitAny: see above
+  const stores: Record<string, any[]> = { user_tasks: [...seedUserTasks] };
+  const completed: { userTaskKey: string; variables: Record<string, unknown> }[] = [];
+  function tbl(name: string, pk: string) {
+    // biome-ignore lint/suspicious/noExplicitAny: see above
+    const rows = (stores[name] ??= [] as any[]);
+    return {
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async insert(row: any) {
+        rows.push({ ...row });
+        return rows.length;
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async get(id: any) {
+        return rows.find((r) => r[pk] === id);
+      },
+      async all() {
+        return [...rows];
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async find(where: any = {}) {
+        return rows.filter((r) => Object.entries(where).every(([k, v]) => r[k] === v));
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async delete(id: any) {
+        const i = rows.findIndex((r) => r[pk] === id);
+        if (i >= 0) rows.splice(i, 1);
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+      },
+    };
+  }
+  const engine = {
+    openUserTasks: async () => openTasks,
+    searchUserTasks: async () => openTasks,
+    completeUserTask: async (userTaskKey: string, variables: Record<string, unknown>) => {
+      completed.push({ userTaskKey, variables });
+    },
+  };
+  const app = {
+    data: { table: (n: string, pk: string) => tbl(n, pk) },
+    engine,
+    log: noopLog(),
+    // biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+  } as any as AppApi;
+  return { app, stores, completed };
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+async function callList(app: AppApi): Promise<any> {
+  // biome-ignore lint/suspicious/noExplicitAny: see above
+  return (await listHandler({ req: { headers: new Headers() } as any, params: {}, query: {}, body: undefined } as any, app)) as any;
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+async function callComplete(app: AppApi, body: unknown): Promise<any> {
+  // biome-ignore lint/suspicious/noExplicitAny: see above
+  return (await completeHandler({ req: {} as any, params: {}, query: {}, body } as any, app)) as any;
+}
+
+function utRow(over: Record<string, unknown>): Record<string, unknown> {
+  return {
+    user_task_key: "ut-x",
+    element_id: "wait-answer",
+    kind_label: "PR review",
+    subject_type: "pr",
+    subject_key: "acme/repo#7",
+    subject_title: "Add widget",
+    subject_url: "https://github.com/acme/repo/pull/7",
+    question: "Which API version?",
+    process_key: "pi-1",
+    form_key: "form-pr",
+    created_at: "2026-01-01T00:00:00.000Z",
+    updated_at: "2026-01-01T00:00:00.000Z",
+    ...over,
+  };
+}
+
+test("listEscalations: round-trip — the listed userTaskKey is exactly what completeUserTask resolves", async () => {
+  const { app, stores, completed } = memApp(
+    [utRow({ user_task_key: "ut-answer", element_id: "wait-answer" })],
+    [{ userTaskKey: "ut-answer", elementId: "wait-answer" }],
+  );
+
+  const listed = await callList(app);
+  assertEquals(listed.status, 200);
+  assertEquals(listed.body.count, 1);
+  const esc = listed.body.escalations[0];
+  assertEquals(esc.userTaskKey, "ut-answer");
+  assertEquals(esc.kind, "wait-answer");
+  assertEquals(esc.prKey, "acme/repo#7");
+  assertEquals(esc.question, "Which API version?");
+  assertEquals(esc.formKey, "form-pr");
+
+  // Answer the exact key the list handed back — it resolves via the canonical completer.
+  const done = await callComplete(app, { userTaskKey: esc.userTaskKey, variables: { answer: "v2" } });
+  assertEquals(done.status, 200);
+  assertEquals(done.body.ok, true);
+  assertEquals(done.body.elementId, "wait-answer");
+  assertEquals(completed, [{ userTaskKey: "ut-answer", variables: { answer: "v2" } }]);
+  // The answered task's read-model row is dropped, so a re-list no longer shows it.
+  assertEquals(stores.user_tasks, []);
+  const reListed = await callList(app);
+  assertEquals(reListed.body.count, 0);
+});
+
+test("listEscalations: lists across all four escalation kinds, newest-updated first", async () => {
+  const { app } = memApp(
+    [
+      utRow({ user_task_key: "ut-pr", element_id: "wait-answer", updated_at: "2026-01-04T00:00:00.000Z" }),
+      utRow({
+        user_task_key: "ut-plan",
+        element_id: "plan-review-decision",
+        kind_label: "Plan review",
+        subject_type: "plan",
+        subject_key: "acme/repo#99",
+        updated_at: "2026-01-03T00:00:00.000Z",
+      }),
+      utRow({
+        user_task_key: "ut-trial",
+        element_id: "trial-merge-decision",
+        kind_label: "Trial merge",
+        subject_type: "plan",
+        subject_key: "acme/repo#99",
+        updated_at: "2026-01-02T00:00:00.000Z",
+      }),
+      utRow({
+        user_task_key: "ut-feat",
+        element_id: "feature-escalation",
+        kind_label: "Feature escalation",
+        subject_type: "feature",
+        subject_key: "acme/repo#42",
+        updated_at: "2026-01-01T00:00:00.000Z",
+      }),
+    ],
+    [],
+  );
+
+  const res = await callList(app);
+  assertEquals(res.status, 200);
+  assertEquals(res.body.count, 4);
+  assertEquals(
+    res.body.escalations.map((e: { userTaskKey: string }) => e.userTaskKey),
+    ["ut-pr", "ut-plan", "ut-trial", "ut-feat"],
+  );
+  // Non-PR subjects carry a null prKey; the PR subject carries the pr key.
+  const byKey = Object.fromEntries(res.body.escalations.map((e: { userTaskKey: string }) => [e.userTaskKey, e]));
+  assertEquals(byKey["ut-pr"].prKey, "acme/repo#7");
+  assertEquals(byKey["ut-plan"].prKey, null);
+  assertEquals(byKey["ut-feat"].subjectType, "feature");
+});
+
+test("listEscalations: empty when no open escalations", async () => {
+  const { app } = memApp([], []);
+  const res = await callList(app);
+  assertEquals(res.status, 200);
+  assertEquals(res.body, { count: 0, escalations: [] });
+});
+
+// The optional shared-secret guard is captured at module load from NANO_PR_WEBHOOK_SECRET, so
+// cache-bust re-import the handler with the env set to exercise both the rejected (401, missing
+// header) and authorized (200, correct header) paths deterministically — mirrors the read-door
+// guard tests on sibling ops (listActivePrs, listLibrary).
+test("listEscalations: shared-secret guard — 401 without x-hook-secret, 200 with it", async () => {
+  const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+  process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+  try {
+    const mod = await import(`./listEscalations.ts?guard=${Date.now()}`);
+    const guarded = mod.default as typeof listHandler;
+    const { app } = memApp([], []);
+    // biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+    const bad = (await guarded({ req: { headers: new Headers() } as any, params: {}, query: {}, body: undefined } as any, app)) as any;
+    assertEquals(bad.status, 401);
+    const ok = (await guarded(
+      // biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+      { req: { headers: new Headers({ "x-hook-secret": "s3cr3t" }) } as any, params: {}, query: {}, body: undefined } as any,
+      app,
+      // biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+    )) as any;
+    assertEquals(ok.status, 200);
+    assert("count" in ok.body);
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+    else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+  }
+});

package/operations/listEscalations.ts

@@ -0,0 +1,32 @@
+// GET /app/api/escalations → operationId `listEscalations` (epic #664, issue #666). Discovery for the
+// escalation-answer path: list EVERY currently-open native user-task escalation — across every
+// surfaced kind (PR review/merge loop, plan-review, empty-plan, trial-merge, conformance-review,
+// delivery human-step, feature/blocked, agent-permission and the shared human-escalation cell) —
+// with the completable `userTaskKey` an agent then answers via
+// `completeUserTask` / `agentCompleteEscalation`. This closes the fallback where an agent had to curl
+// the un-projected `/tasks/api/tasks` inbox to find keys before answering.
+//
+// Read-only projection over the ONE `user_tasks` read model the Tasks inbox and Convergence page
+// consume (`userTasks` + the pure `toEscalationView` derivation in app/userTasks.ts) — NOT a second
+// source of truth. A row exists iff its task is open, so the list reflects live pending work.
+//
+// The optional shared-secret guard stays HERE (the runtime does not enforce OpenAPI `security`):
+// when NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret header. Unset →
+// open (unchanged default), mirroring `listActivePrs`.
+import { toEscalationView, userTasks } from "../app/userTasks.ts";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("listEscalations", async ({ req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("listEscalations rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  const rows = await userTasks(app.data).all();
+  const escalations = rows
+    .sort((a, b) => (a.updated_at < b.updated_at ? 1 : a.updated_at > b.updated_at ? -1 : 0))
+    .map(toEscalationView);
+  return { status: 200, body: { count: escalations.length, escalations } };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.169.0",
+  "version": "0.170.1",
   "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

@@ -82,9 +82,9 @@
         "variant": "ghost",
         "modal": {
           "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`), 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.",
+          "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, plus the `urban_debug_*` family for inspecting a wedged instance's process instances, wait states, variables, 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`). 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:\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."
         }
       }
     },