@nanobpm/nano-workforce 0.172.1 → 0.174.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.174.0](https://github.com/nanobpm/nano-workforce/compare/v0.173.0...v0.174.0) (2026-09-02)
+
+### Features
+
+* **merge-loop:** auto-recover PRs evicted from the merge queue by CI failure, not just conflicts ([#703](https://github.com/nanobpm/nano-workforce/issues/703)) ([45a3051](https://github.com/nanobpm/nano-workforce/commit/45a3051e37767195c75940347af7197f999c3d30)), closes [#556](https://github.com/nanobpm/nano-workforce/issues/556) [#702](https://github.com/nanobpm/nano-workforce/issues/702)
+
+## [0.173.0](https://github.com/nanobpm/nano-workforce/compare/v0.172.1...v0.173.0) (2026-09-01)
+
+### Features
+
+* **mcp:** add a deployed "Connect over MCP" console page ([#701](https://github.com/nanobpm/nano-workforce/issues/701)) ([dd2b998](https://github.com/nanobpm/nano-workforce/commit/dd2b99861ec4e2c8d46fc7e69397ac71954cf27c)), closes [#698](https://github.com/nanobpm/nano-workforce/issues/698) [#698](https://github.com/nanobpm/nano-workforce/issues/698) [#699](https://github.com/nanobpm/nano-workforce/issues/699)
+
 ## [0.172.1](https://github.com/nanobpm/nano-workforce/compare/v0.172.0...v0.172.1) (2026-09-01)
 
 ### Bug Fixes

package/app/github.test.ts

@@ -446,6 +446,7 @@ function prState(over: Partial<PrState>): PrState {
     totalChecks: 0,
     isDraft: false,
     headRefOid: null,
+    mergeQueueEntry: null,
     ...over,
   };
 }
@@ -493,6 +494,7 @@ function mergePrState(over: Partial<PrState> & { rollup?: { name: string; conclu
     checkConclusions: {},
     isDraft: false,
     headRefOid: "abc123",
+    mergeQueueEntry: null,
   };
   if (rollup) {
     const bad = new Set(["FAILURE", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED", "STARTUP_FAILURE", "ERROR"]);

package/app/github.ts

@@ -522,6 +522,20 @@ export interface PrState {
   isDraft: boolean;
   /** Current head commit. Used to scope one-shot merge-protocol nudges to a landing attempt. */
   headRefOid: string | null;
+  /** GROUND-TRUTH native-merge-queue membership, populated only when `fetchPrState` is called with
+   * `{ withMergeQueue: true }` (the block-4 queued-PR reconciliation) — otherwise `null`. It lets the
+   * poller OBSERVE a queue eviction instead of inferring "still queued" from `mergeStateStatus`
+   * alone (which cannot see a CI-on-`merge_group` eviction — the head reverts to BLOCKED/UNSTABLE/
+   * CLEAN, never DIRTY). Tri-state:
+   *   • `true`  — the PR is currently enrolled in the repo's native GitHub merge queue.
+   *   • `false` — the base branch HAS a native merge queue but the PR is NO LONGER in it (a genuine
+   *     eviction: CI failed on the speculative `merge_group` commit, the base moved, or a manual
+   *     dequeue). `queuedVerdict` turns this into `evicted` → `arm-merge` re-drives the mergeable gate.
+   *   • `null`  — indeterminate: not probed, no usable transport, a transport error, OR the base
+   *     branch has no native merge queue at all (a Mergify/plain-merge repo — see #556). A
+   *     perpetually-null entry on such a repo must NOT read as an eviction, so the classifier stays
+   *     conservative and leaves the `landedWaitTimeout` human backstop to cover a never-lands wedge. */
+  mergeQueueEntry: boolean | null;
 }
 
 /** Map GitHub's REST `mergeable_state` (lower-case) onto the GraphQL `mergeStateStatus`
@@ -686,10 +700,96 @@ export function isNotAPullRequestError(err: unknown): boolean {
   return /could not resolve to a pullrequest/i.test(msg) || /\bgithub 404\b/i.test(msg);
 }
 
+/** GraphQL response for the merge-queue membership probe. Both transports (`gh api graphql` and the
+ * raw GraphQL endpoint) wrap the payload in a top-level `data`. */
+interface MergeQueueMembershipResponse {
+  data?: {
+    repository?: {
+      mergeQueue?: { id?: string } | null;
+      pullRequest?: { mergeQueueEntry?: { id?: string } | null } | null;
+    } | null;
+  } | null;
+}
+
+/** Read GROUND-TRUTH native-merge-queue membership for a PR the merge loop enqueued (parked at
+ * `wait-landed`), so an eviction is OBSERVED rather than inferred from `mergeStateStatus` (which
+ * cannot see a CI-on-`merge_group` eviction — the head reverts to BLOCKED/UNSTABLE/CLEAN, never
+ * DIRTY). Returns:
+ *   • `true`  — the PR is currently enrolled in the base branch's native GitHub merge queue.
+ *   • `false` — the base branch HAS a native merge queue but the PR is NO LONGER in it (a genuine
+ *     eviction: CI failed on the speculative `merge_group` commit, the base moved, or a manual
+ *     dequeue).
+ *   • `null`  — indeterminate: no usable transport / a transport error, OR the base branch has no
+ *     native merge queue at all (a Mergify/plain-merge repo whose "queued" classification came from
+ *     an ambiguous signal — #556). We gate on `repository.mergeQueue` existing first so a
+ *     perpetually-null `mergeQueueEntry` on such a repo is never mistaken for an eviction; the
+ *     `landedWaitTimeout` human backstop covers the genuinely-never-lands case there.
+ * Never throws — any failure degrades to `null` so the poller keeps waiting rather than falsely
+ * evicting a still-legitimately-queuing PR. */
+export async function fetchMergeQueueMembership(
+  repo: string,
+  number: number | string,
+  baseBranch: string,
+  token: string,
+): Promise<boolean | null> {
+  if (!baseBranch) return null; // can't scope `mergeQueue(branch:)` without the base ref → stay conservative
+  const [owner, name] = repo.split("/");
+  const query =
+    "query($o:String!,$r:String!,$n:Int!,$b:String!){repository(owner:$o,name:$r){" +
+    "mergeQueue(branch:$b){id}pullRequest(number:$n){mergeQueueEntry{id}}}}";
+  const mode = githubTransport();
+  const useGhHere = mode === "gh" || (mode === "auto" && (await isGhAvailable()));
+  if (!useGhHere && !token) return null;
+  try {
+    let payload: MergeQueueMembershipResponse;
+    if (useGhHere) {
+      const out = await runGh([
+        "api",
+        "graphql",
+        "-f",
+        `query=${query}`,
+        "-f",
+        `o=${owner}`,
+        "-f",
+        `r=${name}`,
+        "-F",
+        `n=${number}`,
+        "-f",
+        `b=${baseBranch}`,
+      ]);
+      // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+      payload = JSON.parse(out) as MergeQueueMembershipResponse;
+    } else {
+      const r = await fetch("https://api.github.com/graphql", {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify({ query, variables: { o: owner, r: name, n: Number(number), b: baseBranch } }),
+      });
+      if (!r.ok) return null;
+      // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+      payload = (await r.json()) as MergeQueueMembershipResponse;
+    }
+    const repository = payload.data?.repository;
+    if (!repository) return null; // unreadable / GraphQL error → indeterminate
+    // No native merge queue on this base branch → an eviction is unobservable here (Mergify/plain).
+    if (!repository.mergeQueue) return null;
+    // A missing `pullRequest` (partial GraphQL `data` alongside `errors`, or an unreadable PR) is
+    // NOT an eviction — treat it as indeterminate so a transport hiccup can't thrash `arm-merge`.
+    const pr = repository.pullRequest;
+    if (pr == null) return null;
+    // Native queue exists and the PR is readable: enrolled iff it still carries a live queue entry.
+    return pr.mergeQueueEntry != null;
+  } catch {
+    // A transport/parse failure must not falsely evict — stay conservative.
+    return null;
+  }
+}
+
 export async function fetchPrState(
   repo: string,
   number: number | string,
   token: string,
+  opts?: { withMergeQueue?: boolean },
 ): Promise<PrState | null> {
   if (await useGh()) {
     const out = await runGh([
@@ -699,7 +799,7 @@ export async function fetchPrState(
       "--repo",
       repo,
       "--json",
-      "state,mergedAt,mergeStateStatus,statusCheckRollup,isDraft,headRefOid",
+      "state,mergedAt,mergeStateStatus,statusCheckRollup,isDraft,headRefOid,baseRefName",
     ]);
     // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
     const j = JSON.parse(out) as {
@@ -709,10 +809,16 @@ export async function fetchPrState(
       statusCheckRollup?: RollupEntry[];
       isDraft?: boolean;
       headRefOid?: string | null;
+      baseRefName?: string | null;
     };
     const rollup = j.statusCheckRollup ?? [];
     const names = failingCheckNames(rollup);
     const merged = j.state === "MERGED" || !!j.mergedAt;
+    // Probe native-queue membership only for the queued-PR reconciliation (block 4) — it is an extra
+    // GraphQL round-trip, so every other caller leaves `mergeQueueEntry` null (unprobed).
+    const mergeQueueEntry = opts?.withMergeQueue
+      ? await fetchMergeQueueMembership(repo, number, j.baseRefName ?? "", token)
+      : null;
     return {
       merged,
       state: merged ? "merged" : (j.state ?? "").toUpperCase() === "CLOSED" ? "closed" : "open",
@@ -725,6 +831,7 @@ export async function fetchPrState(
       checkConclusions: checkConclusions(rollup),
       isDraft: !!j.isDraft,
       headRefOid: j.headRefOid ?? null,
+      mergeQueueEntry,
     };
   }
   if (!token) return null;
@@ -740,8 +847,12 @@ export async function fetchPrState(
     mergeable_state?: string;
     draft?: boolean;
     head?: { sha?: string | null };
+    base?: { ref?: string | null };
   };
   const restMerged = !!j.merged || !!j.merged_at;
+  const mergeQueueEntry = opts?.withMergeQueue
+    ? await fetchMergeQueueMembership(repo, number, j.base?.ref ?? "", token)
+    : null;
   return {
     // The single-PR GET returns a `merged` boolean (unlike the list endpoint); we also honour
     // `merged_at` so this mirrors the gh branch's `state === "MERGED" || mergedAt` rule.
@@ -758,6 +869,7 @@ export async function fetchPrState(
     checkConclusions: {}, // …no per-check conclusions → protocol-aware gate falls through in token mode
     isDraft: !!j.draft,
     headRefOid: j.head?.sha ?? null,
+    mergeQueueEntry, // native-queue membership (GraphQL), probed only for block-4 reconciliation
   };
 }
 

package/app/mergeQueueEviction.test.ts

@@ -0,0 +1,223 @@
+// #702: the merge-loop must auto-recover a PR EVICTED from the GitHub merge queue for ANY reason —
+// not only a merge conflict (`DIRTY`). A PR dropped because required checks FAILED on the
+// speculative `merge_group` commit (the ALLGREEN-batch invalidation) is NOT `DIRTY` — its head
+// reverts to BLOCKED/UNSTABLE/CLEAN — so the old `mergeStateStatus`-only classifier kept it parked
+// at `wait-landed` until the PT1H `landedWaitTimeout` escalated to a human. The poller now reads
+// GROUND-TRUTH native-queue membership (GraphQL `mergeQueueEntry`) so a clean eviction publishes
+// `merge-evicted` (→ `arm-merge` → the mergeable gate re-drives `fix-ci`/`rebase`).
+//
+// These are poller-level tests: they drive `pollMerges` over a `queued` PR row against a
+// token-transport GitHub stub that serves BOTH the REST PR view and the GraphQL merge-queue probe.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import { fetchMergeQueueMembership } from "./github.ts";
+import { pollMerges } from "./service.ts";
+
+function memData(): { data: DataLayer; stores: Record<string, any[]> } {
+  const stores: Record<string, any[]> = {};
+  function tbl(name: string, pk = "id") {
+    const rows = (stores[name] ??= [] as any[]);
+    const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
+    return {
+      async all() {
+        return rows.slice();
+      },
+      async get(id: any) {
+        return rows.find((r) => r[pk] === id);
+      },
+      async find(where: any = {}) {
+        return rows.filter((r) => match(r, where));
+      },
+      async insert(row: any) {
+        rows.push({ ...row });
+        return row[pk];
+      },
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+      },
+      async delete(id: any) {
+        for (let i = rows.length - 1; i >= 0; i--) if (rows[i][pk] === id) rows.splice(i, 1);
+      },
+    };
+  }
+  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
+  return { data, stores };
+}
+
+function recordingEngine(): { engine: EngineClient; messages: any[] } {
+  const messages: any[] = [];
+  const engine = {
+    async publishMessage(msg: any) {
+      messages.push(msg);
+    },
+  } as any as EngineClient;
+  return { engine, messages };
+}
+
+// A token-transport GitHub stub serving BOTH the REST `GET …/pulls/{n}` (the PR's merge state) and
+// the GraphQL merge-queue membership probe. `mergeableState` is the head's `mergeable_state`;
+// `hasQueue` says the base branch has a native merge queue; `enrolled` says the PR still holds a
+// live `mergeQueueEntry`.
+interface Fixture {
+  mergeableState: string; // e.g. "blocked" | "unstable" | "clean" | "dirty"
+  hasQueue: boolean;
+  enrolled: boolean;
+}
+function githubFetch(fx: Fixture) {
+  return (url: string | URL | Request, _init?: RequestInit): Promise<Response> => {
+    const u = new URL(String(url));
+    const json = (obj: unknown, status = 200) =>
+      Promise.resolve(new Response(JSON.stringify(obj), { status, headers: { "content-type": "application/json" } }));
+    if (u.pathname === "/graphql") {
+      return json({
+        data: {
+          repository: {
+            mergeQueue: fx.hasQueue ? { id: "MQ_1" } : null,
+            pullRequest: { mergeQueueEntry: fx.enrolled ? { id: "MQE_1" } : null },
+          },
+        },
+      });
+    }
+    const m = u.pathname.match(/\/repos\/[^/]+\/[^/]+\/pulls\/(\d+)$/);
+    if (m) {
+      return json({
+        merged: false,
+        merged_at: null,
+        state: "open",
+        mergeable_state: fx.mergeableState,
+        draft: false,
+        head: { sha: "deadbeef" },
+        base: { ref: "main" },
+      });
+    }
+    return Promise.resolve(new Response(`unexpected ${u.pathname}`, { status: 500 }));
+  };
+}
+
+async function withGithub<T>(fx: Fixture, fn: () => Promise<T>): Promise<T> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  globalThis.fetch = githubFetch(fx) as typeof fetch;
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = prevFetch;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+  }
+}
+
+function queuedRow(prKey: string, number: number) {
+  const ts = "2026-08-20T00:00:00Z";
+  return {
+    pr_key: prKey,
+    repo: "o/r",
+    number,
+    url: `https://github.com/o/r/pull/${number}`,
+    title: "t",
+    status: "queued",
+    current_round: 0,
+    process_key: null,
+    waiting_since: null,
+    last_review_id: null,
+    outcome: null,
+    created_at: ts,
+    updated_at: ts,
+    converged_at: null,
+    merged_at: null,
+  };
+}
+
+test("#702 poller: a queued PR dropped from the queue (not DIRTY) publishes merge-evicted", async () => {
+  // The exact CI-on-merge_group eviction: head is BLOCKED (not DIRTY), native queue exists, but the
+  // PR is no longer enrolled. The old DIRTY-only classifier stayed silent here.
+  const { data, stores } = memData();
+  const { engine, messages } = recordingEngine();
+  stores["pull_requests"] = [queuedRow("o/r#100", 100)];
+
+  await withGithub({ mergeableState: "blocked", hasQueue: true, enrolled: false }, () =>
+    pollMerges(data, engine, "tok"),
+  );
+
+  assertEquals(messages.length, 1, "an evicted queued PR must publish exactly one escape message");
+  assertEquals(messages[0].name, "merge-evicted");
+  assertEquals(messages[0].correlationKey, "o/r#100");
+  // Flipped onto the transient `merging` status so a slow next pass can't double-signal.
+  assertEquals(stores["pull_requests"][0].status, "merging");
+});
+
+test("#702 regression: a queued PR still ENROLLED (BLOCKED pending queue check) stays parked", async () => {
+  const { data, stores } = memData();
+  const { engine, messages } = recordingEngine();
+  stores["pull_requests"] = [queuedRow("o/r#100", 100)];
+
+  await withGithub({ mergeableState: "blocked", hasQueue: true, enrolled: true }, () =>
+    pollMerges(data, engine, "tok"),
+  );
+
+  assertEquals(messages.length, 0, "a still-enrolled queuing PR must not be falsely evicted");
+  assertEquals(stores["pull_requests"][0].status, "queued");
+});
+
+test("#702: a repo with NO native merge queue (Mergify/plain) never falsely evicts a queued PR", async () => {
+  // `mergeQueueEntry` is perpetually null there — the #556 `landedWaitTimeout` backstop, not a false
+  // eviction, must cover a never-lands wedge. So the poller stays silent and the PR stays queued.
+  const { data, stores } = memData();
+  const { engine, messages } = recordingEngine();
+  stores["pull_requests"] = [queuedRow("o/r#100", 100)];
+
+  await withGithub({ mergeableState: "blocked", hasQueue: false, enrolled: false }, () =>
+    pollMerges(data, engine, "tok"),
+  );
+
+  assertEquals(messages.length, 0, "no native queue → indeterminate membership → keep waiting");
+  assertEquals(stores["pull_requests"][0].status, "queued");
+});
+
+// #703 (suppressed-advisory follow-up): `fetchMergeQueueMembership` must stay conservative when the
+// GraphQL payload carries a native `mergeQueue` but the `pullRequest` node is missing (partial
+// `data` alongside `errors`, or an unreadable PR). A null `pullRequest` is INDETERMINATE (`null`),
+// never a definitive eviction (`false`) — otherwise a transport hiccup would thrash `arm-merge`.
+async function withProbeFetch<T>(body: unknown, fn: () => Promise<T>): Promise<T> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  globalThis.fetch = ((): Promise<Response> =>
+    Promise.resolve(
+      new Response(JSON.stringify(body), { status: 200, headers: { "content-type": "application/json" } }),
+    )) as typeof fetch;
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = prevFetch;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+  }
+}
+
+test("#703: a native queue with a MISSING pullRequest node reads indeterminate (null), not evicted", async () => {
+  const membership = await withProbeFetch(
+    { data: { repository: { mergeQueue: { id: "MQ_1" }, pullRequest: null } } },
+    () => fetchMergeQueueMembership("o/r", 100, "main", "tok"),
+  );
+  assertEquals(membership, null, "missing pullRequest must be indeterminate, never a false eviction");
+});
+
+test("#703: a native queue with a live pullRequest entry reads enrolled (true)", async () => {
+  const membership = await withProbeFetch(
+    { data: { repository: { mergeQueue: { id: "MQ_1" }, pullRequest: { mergeQueueEntry: { id: "MQE_1" } } } } },
+    () => fetchMergeQueueMembership("o/r", 100, "main", "tok"),
+  );
+  assertEquals(membership, true);
+});
+
+test("#703: a native queue with a present PR but no entry reads a genuine eviction (false)", async () => {
+  const membership = await withProbeFetch(
+    { data: { repository: { mergeQueue: { id: "MQ_1" }, pullRequest: { mergeQueueEntry: null } } } },
+    () => fetchMergeQueueMembership("o/r", 100, "main", "tok"),
+  );
+  assertEquals(membership, false);
+});

package/app/queuedVerdict.test.ts

@@ -2,7 +2,11 @@
 // decision drives what the poller does next from the PR's live GitHub state. The regression it
 // guards: a PR that develops a merge CONFLICT after being enqueued (#727/instance 729) must be
 // EVICTED back to the mergeable gate, not left waiting forever — while a PR still legitimately in
-// the queue (reported BLOCKED/UNSTABLE by GitHub) must keep waiting, never be falsely evicted.
+// the queue (reported BLOCKED/UNSTABLE by GitHub) must keep waiting, never be falsely evicted. It
+// also guards #702: a PR EVICTED because required checks failed on the speculative `merge_group`
+// commit is NOT `DIRTY`, so a ground-truth `mergeQueueEntry === false` must classify it `evicted`
+// (the old `DIRTY`-only classifier left it waiting out the full `landedWaitTimeout`, then escalated
+// to a human, instead of auto-re-driving `fix-ci`).
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
 import type { PrState } from "./github.ts";
@@ -19,6 +23,7 @@ function st(over: Partial<PrState>): PrState {
     totalChecks: 0,
     isDraft: false,
     headRefOid: null,
+    mergeQueueEntry: null,
     ...over,
   };
 }
@@ -34,8 +39,39 @@ test("a DIRTY (conflicting) PR is evicted — this is the #727 wedge", () => {
 });
 
 test("a PR still legitimately in the queue keeps waiting (never falsely evicted)", () => {
-  // Queuing PRs commonly report these; none is a conflict, so none may evict.
+  // Queuing PRs commonly report these; none is a conflict, and with an unprobed/indeterminate
+  // membership (`mergeQueueEntry: null`) none may evict.
   for (const s of ["CLEAN", "BLOCKED", "UNSTABLE", "BEHIND", "HAS_HOOKS", "UNKNOWN", "DRAFT"]) {
     assertEquals(queuedVerdict(st({ merged: false, mergeStateStatus: s })), "waiting", s);
   }
 });
+
+// ── #702: a merge-queue eviction caused by a red `merge_group` build leaves the head NOT `DIRTY`
+// (it reverts to BLOCKED/UNSTABLE/CLEAN). Inferring from `mergeStateStatus` alone kept such a PR
+// "waiting" until the PT1H `landedWaitTimeout` escalated to a human, instead of auto-re-driving
+// `fix-ci`. Ground-truth `mergeQueueEntry === false` now classifies it `evicted`.
+
+test("#702: a queued PR dropped from the queue (mergeQueueEntry=false) evicts even when not DIRTY", () => {
+  // The exact CI-on-merge_group eviction shapes: no conflict, but no longer enrolled.
+  for (const s of ["BLOCKED", "UNSTABLE", "CLEAN", "BEHIND", "HAS_HOOKS", "UNKNOWN"]) {
+    assertEquals(queuedVerdict(st({ merged: false, mergeStateStatus: s, mergeQueueEntry: false })), "evicted", s);
+  }
+});
+
+test("#702 regression: a PR still ENROLLED (mergeQueueEntry=true) but BLOCKED keeps waiting", () => {
+  // A pending queue check reports BLOCKED/UNSTABLE while genuinely still in the queue — must NOT
+  // evict, or every legitimately-queuing PR would thrash `arm-merge`.
+  for (const s of ["BLOCKED", "UNSTABLE", "CLEAN"]) {
+    assertEquals(queuedVerdict(st({ merged: false, mergeStateStatus: s, mergeQueueEntry: true })), "waiting", s);
+  }
+});
+
+test("#702: indeterminate membership (mergeQueueEntry=null, e.g. Mergify/token GraphQL error) keeps waiting", () => {
+  // A repo with no native merge queue (or an unreadable probe) leaves the #556 `landedWaitTimeout`
+  // backstop to handle a never-lands wedge — we must not falsely evict on a perpetually-null entry.
+  for (const s of ["BLOCKED", "UNSTABLE", "CLEAN"]) {
+    assertEquals(queuedVerdict(st({ merged: false, mergeStateStatus: s, mergeQueueEntry: null })), "waiting", s);
+  }
+  // …but a real conflict still evicts regardless of an unprobed membership (token-mode path).
+  assertEquals(queuedVerdict(st({ merged: false, mergeStateStatus: "DIRTY", mergeQueueEntry: null })), "evicted");
+});

package/app/readiness.test.ts

@@ -624,6 +624,7 @@ function prObs(over: Partial<PrObservation> = {}): PrObservation {
     headRefOid: "abc123",
     mergedSha: null,
     pendingChecks: 0,
+    mergeQueueEntry: null,
     ...over,
   };
 }

package/app/readiness.ts

@@ -704,6 +704,7 @@ export function parsePrView(payload: unknown): PrObservation {
     checkConclusions: checkConclusions(rollup),
     isDraft: j.isDraft === true,
     headRefOid: str(j.headRefOid).trim() || null,
+    mergeQueueEntry: null, // readiness probe doesn't read native-queue membership (merge-loop-only signal)
     mergedSha,
     pendingChecks: pending.length,
   };

package/app/service.ts

@@ -1316,35 +1316,41 @@ export async function pollMerges(data: DataLayer, engine: EngineClient, token: s
   //
   // A PR enqueued by `attempt-merge` (mergeStatus="queued") parks the process at `wait-landed`.
   // Two things can end that wait: the queue lands the PR (→ `merge-landed`), or the PR is EVICTED
-  // from the queue because its base moved under it and it now conflicts (`DIRTY`). Without the
-  // eviction path a conflicted-after-enqueue PR waits forever (nothing ever publishes
-  // `merge-landed`), which is exactly how #727/instance 729 wedged. We must NOT treat a merely
-  // "not yet landed" PR as evicted: while it is legitimately queuing GitHub often reports it as
-  // BLOCKED (a pending queue check) or UNSTABLE, which `classifyMergeability` calls not-ready. Only
-  // a genuine merge CONFLICT (`DIRTY`) means it has dropped out — evict on that alone and re-arm the
-  // merge poller (`merge-evicted` → `arm-merge`), which re-runs the mergeable gate so the existing
-  // auto-rebase / escalate machinery resolves the conflict.
+  // from the queue. An eviction has two observable flavours: a merge CONFLICT after its base moved
+  // (`DIRTY` — how #727/instance 729 wedged), OR — the #702 wedge — required checks FAILED on the
+  // speculative `merge_group` commit (the ALLGREEN-batch invalidation), which leaves the
+  // conflict-free head NOT `DIRTY` (it reverts to BLOCKED/UNSTABLE/CLEAN). The latter is invisible to
+  // `mergeStateStatus` alone, so we read GROUND-TRUTH native-queue membership (`withMergeQueue: true`
+  // → GraphQL `mergeQueueEntry`) and let `queuedVerdict` evict on a definitive drop. Without an
+  // eviction path an evicted PR waits out the full `landedWaitTimeout` (default PT1H) then escalates
+  // to a human instead of auto-re-driving `fix-ci`/`rebase`. We must NOT treat a merely "not yet
+  // landed" PR as evicted: while it is legitimately queuing GitHub reports it BLOCKED/UNSTABLE and
+  // `mergeQueueEntry` stays `true`, so `queuedVerdict` keeps waiting. Eviction re-arms the merge
+  // poller (`merge-evicted` → `arm-merge`), re-running the mergeable gate so the existing
+  // auto-rebase / fix-ci / re-enqueue machinery resolves whatever dropped it.
   for (const pr of await prs(data).find({ status: "queued" })) {
     const { repo, number, pr_key: prKey } = pr;
     try {
-      const st = await fetchPrState(repo, number, token);
+      const st = await fetchPrState(repo, number, token, { withMergeQueue: true });
       if (st === null) continue; // no transport → skip this PR (others may still advance)
       // Out-of-band terminal FIRST (reusing `st`): a queued PR merged out-of-band lands
       // (`merge-landed` → mark-merged); one CLOSED out-of-band without merging can never land, so the
       // pre-check re-arms it (`merge-evicted` → arm-merge) and block 2 abandons it — a closed queued
       // PR would otherwise wedge, since `queuedVerdict` calls a non-DIRTY closed PR merely "waiting"
-      // (#368). The DIRTY-while-open eviction below still handles a live-but-conflicted queue drop.
+      // (#368). The eviction check below still handles a live queue drop (conflict or CI-on-merge_group).
       if (await advanceIfTerminalOutOfBand(data, engine, pr, token, st)) continue;
       // Terminal states (merged/closed) are handled by the shared pre-check above; here the PR is
-      // still open, so the only remaining reason to leave `wait-landed` is a live queue DROP — a real
-      // merge CONFLICT (`DIRTY`). `queuedVerdict` stays the canonical classifier for that.
+      // still open, so the only remaining reason to leave `wait-landed` is a live queue DROP — a merge
+      // CONFLICT (`DIRTY`) or a ground-truth `mergeQueueEntry === false`. `queuedVerdict` is the
+      // canonical classifier for both.
       if (queuedVerdict(st) === "evicted") {
         await flipToMergingThenPublish(data, engine, prKey, "queued", {
           name: "merge-evicted",
           correlationKey: prKey,
           variables: {},
         });
-        console.log(`[poller] queued PR evicted (conflict) -> ${prKey}`);
+        const reason = st.mergeStateStatus === "DIRTY" ? "conflict" : "dropped from queue";
+        console.log(`[poller] queued PR evicted (${reason}) -> ${prKey}`);
       }
       // otherwise: still legitimately in the queue — keep waiting.
     } catch (err) {
@@ -1356,14 +1362,27 @@ export async function pollMerges(data: DataLayer, engine: EngineClient, token: s
 /** Decide what to do with a PR the process enqueued (parked at `wait-landed`), from its current
  *  GitHub merge state:
  *   • `landed`  — the queue merged it → publish `merge-landed` (advance to mark-merged).
- *   • `evicted` — it fell out of the queue with a real merge CONFLICT (`DIRTY`) → publish
- *     `merge-evicted` so the process re-arms the merge poller and the mergeable gate re-runs
- *     (auto-rebase / escalate). Without this a conflicted-after-enqueue PR waits forever.
- *   • `waiting` — still legitimately in the queue. Crucially, a queuing PR is frequently reported
- *     BLOCKED/UNSTABLE (a pending queue check), which is NOT eviction — only `DIRTY` is. */
+ *   • `evicted` — it fell out of the queue → publish `merge-evicted` so the process re-arms the
+ *     merge poller and the mergeable gate re-runs (auto-rebase for a conflict, `fix-ci` for a red
+ *     required check, re-enqueue otherwise). Two independent signals mean "evicted": a live merge
+ *     CONFLICT (`DIRTY`) — observable even in token mode — OR ground-truth `mergeQueueEntry === false`,
+ *     i.e. the base branch has a native GitHub merge queue but the PR is no longer enrolled in it.
+ *     The latter is what catches the #702 wedge: a PR evicted because required checks FAILED on the
+ *     speculative `merge_group` commit is NOT `DIRTY` (its head reverts to BLOCKED/UNSTABLE/CLEAN),
+ *     so inferring from `mergeStateStatus` alone kept it waiting out the full `landedWaitTimeout`
+ *     then pulled in a human, instead of auto-re-driving `fix-ci`.
+ *   • `waiting` — still legitimately in the queue. A queuing PR is frequently reported
+ *     BLOCKED/UNSTABLE (a pending queue check) — that is NOT eviction. `mergeQueueEntry` is only
+ *     `false` when the queue definitively dropped it; `null` (unprobed / token GraphQL error / a
+ *     Mergify/plain repo with no native queue) leaves the #556 `landedWaitTimeout` backstop to
+ *     handle a genuinely-never-lands wedge, so we never falsely evict there. */
 export function queuedVerdict(st: PrState): "landed" | "evicted" | "waiting" {
   if (st.merged) return "landed";
+  // A live conflict is an eviction (works in token mode, where `mergeQueueEntry` is unprobed).
   if (st.mergeStateStatus === "DIRTY") return "evicted";
+  // Ground-truth: enrolled in a native merge queue and now gone → evicted for ANY reason (a red
+  // `merge_group` build, base moved, manual dequeue), not just a conflict (#702).
+  if (st.mergeQueueEntry === false) return "evicted";
   return "waiting";
 }
 

package/docs/mcp-runbook.md

@@ -24,6 +24,11 @@ MCP is a **third door**, not a replacement: `GET /app/api/agent` (the live guide
 `GET /app/api/agent/skill` are unchanged for agents without MCP — see
 [§5 Fallback](#5-fallback).
 
+> **Served summary:** a running instance also exposes a nav-linked **"Connect over
+> MCP"** console page (`pages/mcp.page.json`) with copyable config recipes rendered
+> for that instance's own address. It is the short, always-reachable digest; this
+> runbook is the deeper source of truth. Keep the two in sync.
+
 ## 1. One MCP server entry per instance
 
 In `~/.copilot/mcp-config.json` (user-wide) or `.mcp.json` (repo-scoped):
@@ -122,16 +127,24 @@ door the UI's Cancel uses), never the record-desyncing engine-level `urban_debug
 
 ## 4. Guard posture
 
-When `NANO_PR_WEBHOOK_SECRET` is **unset**, both reads (status, instances, incidents,
-projections, the operator guide) and mutations (cancel/retry/resolve, `start/*`
-operations, answering escalations) work from loopback with no credential. When it **is
-set**, the guard is not mutation-only: that secret is required as an `x-hook-secret`
-header on **both reads and mutations** — read endpoints like `GET /app/api/agent` and
-`GET /app/api/version` also return `401` without it. Put it in the server entry's
+When `NANO_PR_WEBHOOK_SECRET` is **unset**, the app guard is off entirely: both reads
+(status, instances, incidents, projections, the operator guide) and mutations
+(cancel/retry/resolve, `start/*` operations, answering escalations) work with no
+credential **from wherever this instance is reachable** — with `network.bind: "all"`
+that is the LAN, not just loopback, so leave it unset only where that exposure is
+acceptable. When it **is set**, the guard is not mutation-only: it also covers
+reads, so read endpoints like `GET /app/api/agent` and `GET /app/api/version`
+return `401` without the `x-hook-secret` header, just as guarded mutations do. It
+is not blanket, though — a few doors stay intentionally unguarded even when the
+secret is set (e.g. the declarative Save-to-library page action, which
+structurally cannot attach the header). Put it in the server entry's
 `headers`, never in chat. For a remote fleet,
-`NANO_WORKFORCE_BASE_URL` reachability rules apply unchanged, and LAN exposure of
-`/app/mcp` follows the same `network.bind` manifest setting as the rest of the app's
-HTTP surface.
+`NANO_WORKFORCE_BASE_URL` reachability rules apply unchanged. The rest of the app's
+HTTP surface follows the `network.bind` manifest setting, but the runtime-served
+`/app/mcp` surface is an exception: it is **loopback-only by default** and refuses
+non-loopback peers with a `403` even when `network.bind` is `"all"`, until you
+*also* set `URBAN_MCP_ALLOW_REMOTE=true` (see `e2e/support/mcp-harness.ts`).
+LAN/remote MCP clients therefore need that knob in addition to a wide bind.
 
 ### Framework mutation guard — `urban_debug_*` mutations need `x-hook-secret` too
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.172.1",
+  "version": "0.174.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/_nav.json

@@ -6,6 +6,7 @@
     "title": "Nano Workforce",
     "items": [
       { "label": "Overview", "page": "overview" },
+      { "label": "Connect over MCP", "page": "mcp" },
       { "label": "Lineage", "page": "lineage" },
       { "label": "Convergence", "page": "home" },
       { "label": "Epics", "page": "epic" },

package/pages/board.page.json

@@ -13,6 +13,10 @@
             "label": "Overview",
             "page": "overview"
           },
+          {
+            "label": "Connect over MCP",
+            "page": "mcp"
+          },
           {
             "label": "Lineage",
             "page": "lineage"

package/pages/cockpit.page.json

@@ -13,6 +13,10 @@
             "label": "Overview",
             "page": "overview"
           },
+          {
+            "label": "Connect over MCP",
+            "page": "mcp"
+          },
           {
             "label": "Lineage",
             "page": "lineage"

package/pages/delivery-graph-detail.page.json

@@ -13,6 +13,10 @@
             "label": "Overview",
             "page": "overview"
           },
+          {
+            "label": "Connect over MCP",
+            "page": "mcp"
+          },
           {
             "label": "Lineage",
             "page": "lineage"

package/pages/delivery-graphs.page.json

@@ -13,6 +13,10 @@
             "label": "Overview",
             "page": "overview"
           },
+          {
+            "label": "Connect over MCP",
+            "page": "mcp"
+          },
           {
             "label": "Lineage",
             "page": "lineage"

package/pages/epic-detail.page.json

@@ -13,6 +13,10 @@
             "label": "Overview",
             "page": "overview"
           },
+          {
+            "label": "Connect over MCP",
+            "page": "mcp"
+          },
           {
             "label": "Lineage",
             "page": "lineage"

package/pages/epic.page.json

@@ -13,6 +13,10 @@
             "label": "Overview",
             "page": "overview"
           },
+          {
+            "label": "Connect over MCP",
+            "page": "mcp"
+          },
           {
             "label": "Lineage",
             "page": "lineage"

package/pages/feature.page.json

@@ -13,6 +13,10 @@
             "label": "Overview",
             "page": "overview"
           },
+          {
+            "label": "Connect over MCP",
+            "page": "mcp"
+          },
           {
             "label": "Lineage",
             "page": "lineage"

package/pages/home.page.json

@@ -13,6 +13,10 @@
             "label": "Overview",
             "page": "overview"
           },
+          {
+            "label": "Connect over MCP",
+            "page": "mcp"
+          },
           {
             "label": "Lineage",
             "page": "lineage"

package/pages/lineage.page.json

@@ -13,6 +13,10 @@
             "label": "Overview",
             "page": "overview"
           },
+          {
+            "label": "Connect over MCP",
+            "page": "mcp"
+          },
           {
             "label": "Lineage",
             "page": "lineage"

package/pages/mcp.page.json

@@ -0,0 +1,217 @@
+{
+  "schemaVersion": "1.0",
+  "title": "Connect over MCP",
+  "nodes": [
+    {
+      "type": "nav",
+      "id": "nav",
+      "props": {
+        "variant": "bar",
+        "title": "Nano Workforce",
+        "items": [
+          {
+            "label": "Overview",
+            "page": "overview"
+          },
+          {
+            "label": "Connect over MCP",
+            "page": "mcp"
+          },
+          {
+            "label": "Lineage",
+            "page": "lineage"
+          },
+          {
+            "label": "Convergence",
+            "page": "home"
+          },
+          {
+            "label": "Epics",
+            "page": "epic"
+          },
+          {
+            "label": "Feature",
+            "page": "feature"
+          },
+          {
+            "label": "Delivery Graphs",
+            "page": "delivery-graphs"
+          },
+          {
+            "label": "Tasks",
+            "page": "tasks",
+            "badge": {
+              "source": "app",
+              "table": "user_tasks",
+              "filter": [],
+              "tone": "danger",
+              "refreshMs": 5000,
+              "hideWhenZero": true
+            }
+          },
+          {
+            "label": "Cockpit",
+            "page": "cockpit"
+          },
+          {
+            "label": "Board",
+            "page": "board"
+          },
+          {
+            "label": "Velocity",
+            "page": "velocity"
+          }
+        ],
+        "sticky": true
+      }
+    },
+    {
+      "type": "text",
+      "id": "title",
+      "props": { "text": "Connect over MCP", "variant": "heading" }
+    },
+    {
+      "type": "text",
+      "id": "intro",
+      "props": {
+        "text": "Point a coding agent (Copilot, Claude, Cursor \u2026) at this running instance so the workforce's operations become native tools \u2014 submit work, answer escalations, read status, and debug a wedged instance without curl. The Urban runtime serves a Streamable-HTTP MCP endpoint for this app at the /app/mcp path \u2014 behind a reverse-proxy prefix the reachable URL carries that prefix, as the recipes below render \u2014 and projects its openapi.yaml into tools, with zero MCP code in nwf. Register ONE server entry per instance; its tools are namespaced under the name you give it, so naming the instance targets the right one and makes the wrong-instance mistake very hard to hit (a server pointed at the wrong URL can still misfire). Use the copyable recipes below \u2014 each URL is already rendered for THIS instance's address (including any reverse-proxy prefix).",
+        "variant": "sub"
+      }
+    },
+    {
+      "type": "button",
+      "id": "recipe-config",
+      "props": {
+        "label": "\ud83d\udccb Config recipe \u2014 local / LAN / remote (mcp-config.json)",
+        "variant": "ghost",
+        "modal": {
+          "title": "One server entry per instance",
+          "description": "Add to ~/.copilot/mcp-config.json (user-wide) or .mcp.json (repo-scoped). The workforce-local entry is pre-filled with THIS instance's URL; the merlin/remote entries show the LAN and ngrok shapes \u2014 give each node its own named entry. If THIS instance is guarded (NANO_PR_WEBHOOK_SECRET set), add the same \"headers\": { \"x-hook-secret\": \"$NANO_PR_WEBHOOK_SECRET\" } block to workforce-local too, or its calls 401. MCP servers register at host startup, so add the entry, THEN start a new session for its tools to load.",
+          "copyLabel": "Copy config",
+          "copyText": "{\n  \"mcpServers\": {\n    \"workforce-local\": {\n      \"type\": \"http\",\n      \"url\": \"{{appBase}}app/mcp\",\n      \"tools\": [\"*\"]\n    },\n    \"workforce-merlin\": {\n      \"type\": \"http\",\n      \"url\": \"http://merlin.local:3000/app/mcp\",\n      \"headers\": { \"x-hook-secret\": \"$NANO_PR_WEBHOOK_SECRET\" },\n      \"tools\": [\"*\"]\n    },\n    \"workforce-remote\": {\n      \"type\": \"http\",\n      \"url\": \"https://<subdomain>.ngrok.app/app/mcp\",\n      \"headers\": { \"x-hook-secret\": \"$NANO_PR_WEBHOOK_SECRET\" },\n      \"tools\": [\"*\"]\n    }\n  }\n}"
+        }
+      }
+    },
+    {
+      "type": "button",
+      "id": "recipe-cli",
+      "props": {
+        "label": "\ud83d\udccb CLI form (copilot mcp add)",
+        "variant": "ghost",
+        "modal": {
+          "title": "Add from the terminal",
+          "description": "For a guarded instance (NANO_PR_WEBHOOK_SECRET set), pass the shared-secret header with the --header form (the second command); an unguarded instance needs only the first.",
+          "copyLabel": "Copy commands",
+          "copyText": "# This instance if unguarded (no NANO_PR_WEBHOOK_SECRET set):\ncopilot mcp add --transport http workforce-local {{appBase}}app/mcp\n\n# This instance if guarded (NANO_PR_WEBHOOK_SECRET set) \u2014 present the shared secret header:\ncopilot mcp add --transport http workforce-local {{appBase}}app/mcp \\\n  --header \"x-hook-secret: $NANO_PR_WEBHOOK_SECRET\""
+        }
+      }
+    },
+    {
+      "type": "text",
+      "id": "secret-heading",
+      "props": { "text": "Shared-secret setup (x-hook-secret)", "variant": "heading" }
+    },
+    {
+      "type": "text",
+      "id": "secret-body",
+      "props": {
+        "text": "When this instance sets NANO_PR_WEBHOOK_SECRET, the guard is NOT mutation-only \u2014 it also covers reads, so read endpoints like GET /app/api/agent and GET /app/api/version return 401 without the x-hook-secret header, just as guarded mutations do. It is not blanket, though: a few doors stay intentionally unguarded even when the secret is set (e.g. the declarative Save-to-library page action, which structurally cannot attach the header). The mcp-config.json path takes the shared secret as a headers block, not a flag, so add a headers block alongside url on the server entry (copy it below); omitting it yields 401s. Put the secret in the server entry's headers, never in chat. When NANO_PR_WEBHOOK_SECRET is unset, the app guard is off entirely \u2014 reads and mutations both work with no credential from wherever this instance is reachable (with network.bind \"all\" that is the LAN, not just loopback), so unset it only where that exposure is acceptable. Note the runtime-served /app/mcp surface is an exception to that reachability: it is loopback-only by default and refuses non-loopback peers with a 403 even when network.bind is \"all\", until you also set URBAN_MCP_ALLOW_REMOTE=true \u2014 LAN/remote MCP clients need that knob in addition to a wide bind.",
+        "variant": "sub"
+      }
+    },
+    {
+      "type": "button",
+      "id": "recipe-secret",
+      "props": {
+        "label": "\ud83d\udccb Shared-secret header block",
+        "variant": "ghost",
+        "modal": {
+          "title": "Add the x-hook-secret header",
+          "description": "Drop this headers entry alongside url on the guarded server's config-form entry.",
+          "copyLabel": "Copy headers",
+          "copyText": "\"headers\": { \"x-hook-secret\": \"$NANO_PR_WEBHOOK_SECRET\" }"
+        }
+      }
+    },
+    {
+      "type": "text",
+      "id": "basic-auth-heading",
+      "props": { "text": "Basic-Auth-fronted instances (reverse proxy)", "variant": "heading" }
+    },
+    {
+      "type": "text",
+      "id": "basic-auth-body",
+      "props": {
+        "text": "These are two different layers. x-hook-secret is the app's own guard, checked by nwf. Basic Auth is enforced by whatever fronts the instance (ngrok edge, console proxy) and 401s before the request ever reaches nwf. A Basic-Auth-fronted instance therefore needs BOTH headers on the connection: Authorization: Basic \u2026 for the proxy AND x-hook-secret for the app. Generate the blob with printf '%s' 'user:pass' | base64 (echo appends a newline and yields the wrong value); Base64 is encoding, not encryption \u2014 only use Basic Auth over HTTPS.",
+        "variant": "sub"
+      }
+    },
+    {
+      "type": "button",
+      "id": "recipe-basic-auth",
+      "props": {
+        "label": "\ud83d\udccb Basic-Auth + secret (both headers)",
+        "variant": "ghost",
+        "modal": {
+          "title": "Both headers, two different layers",
+          "description": "Proxy layer (Authorization) plus app layer (x-hook-secret) on the same server entry.",
+          "copyLabel": "Copy headers",
+          "copyText": "\"headers\": {\n  \"Authorization\": \"Basic <base64(user:pass)>\",\n  \"x-hook-secret\": \"$NANO_PR_WEBHOOK_SECRET\"\n}"
+        }
+      }
+    },
+    {
+      "type": "text",
+      "id": "mutation-guard-heading",
+      "props": { "text": "urban_debug_* mutation-guard caveat", "variant": "heading" }
+    },
+    {
+      "type": "text",
+      "id": "mutation-guard-body",
+      "props": {
+        "text": "The framework's mutating engine-debug tools (set_variables / retry_job / resolve_incident / cancel_instance) require the app's shared-secret scheme (or the loopback-only allowMutations opt-in when allowRemote is off). Until issue #698 declares x-nano-secret-env, remote mutations are refused on any allowRemote-on instance even with reads open \u2014 that is the current posture, tracked in #698. The read tools (urban_debug_search_process_instances / _element_instance_wait_states / _incidents, and where projected _jobs / _variables) work under the same x-hook-secret as the rest of the surface. Operator-only doors stay operator-only: the delivery-graph stage / dispatch / dismiss lifecycle is x-mcp-excluded from the tool surface \u2014 the human clicking Dispatch in the cockpit IS the approval \u2014 so an agent cannot dispatch a delivery graph through MCP (it authors graphs through the pure compileDeliveryGraph / previewDeliveryGraph doors, which stay exposed).",
+        "variant": "sub"
+      }
+    },
+    {
+      "type": "text",
+      "id": "fallback-heading",
+      "props": { "text": "Fallback \u2014 no MCP client", "variant": "heading" }
+    },
+    {
+      "type": "text",
+      "id": "fallback-body",
+      "props": {
+        "text": "Agents without an MCP client are unchanged \u2014 fetch and follow this instance's live operator guide over curl (the response is JSON with a skill markdown field). Add -H \"x-hook-secret: <secret>\" (and -u user:pass for a Basic-Auth-fronted instance) if this instance is guarded. That skill bootstraps you to the same live guide MCP exposes as the getAgentInstructions tool \u2014 or, over MCP, its addressable companion getAgentGuide(section?), which the runbook recommends over the ~43KB blob to avoid a tool-result overrun.",
+        "variant": "sub"
+      }
+    },
+    {
+      "type": "button",
+      "id": "recipe-fallback",
+      "props": {
+        "label": "\ud83d\udccb Fallback curl (no MCP client)",
+        "variant": "ghost",
+        "modal": {
+          "title": "The curl door is unchanged",
+          "description": "Fetch this instance's live guide directly; add the header(s) if guarded.",
+          "copyLabel": "Copy curl",
+          "copyText": "curl -sS {{appBase}}app/api/agent/skill\n# guarded instance \u2014 add the shared secret (and Basic Auth if fronted):\ncurl -sS {{appBase}}app/api/agent/skill \\\n  -H \"x-hook-secret: <secret>\""
+        }
+      }
+    },
+    {
+      "type": "text",
+      "id": "runbook-heading",
+      "props": { "text": "Deeper reference", "variant": "heading" }
+    },
+    {
+      "type": "text",
+      "id": "runbook-body",
+      "props": {
+        "text": "This served page is the short, always-reachable summary. The full runbook \u2014 discovery, debugging a wedged instance, guard posture, the projected-tool-schema notes and the regression harness \u2014 lives in the repo at docs/mcp-runbook.md (https://github.com/nanobpm/nano-workforce/blob/main/docs/mcp-runbook.md), with README.md \u00a7\"Configure an agent over MCP\" as its companion. Keep the two in sync: the runbook is the source of truth, this page is the served digest.",
+        "variant": "sub"
+      }
+    }
+  ]
+}

package/pages/overview.page.json

@@ -13,6 +13,10 @@
             "label": "Overview",
             "page": "overview"
           },
+          {
+            "label": "Connect over MCP",
+            "page": "mcp"
+          },
           {
             "label": "Lineage",
             "page": "lineage"

package/pages/tasks.page.json

@@ -9,12 +9,34 @@
         "variant": "bar",
         "title": "Nano Workforce",
         "items": [
-          { "label": "Overview", "page": "overview" },
-          { "label": "Lineage", "page": "lineage" },
-          { "label": "Convergence", "page": "home" },
-          { "label": "Epics", "page": "epic" },
-          { "label": "Feature", "page": "feature" },
-          { "label": "Delivery Graphs", "page": "delivery-graphs" },
+          {
+            "label": "Overview",
+            "page": "overview"
+          },
+          {
+            "label": "Connect over MCP",
+            "page": "mcp"
+          },
+          {
+            "label": "Lineage",
+            "page": "lineage"
+          },
+          {
+            "label": "Convergence",
+            "page": "home"
+          },
+          {
+            "label": "Epics",
+            "page": "epic"
+          },
+          {
+            "label": "Feature",
+            "page": "feature"
+          },
+          {
+            "label": "Delivery Graphs",
+            "page": "delivery-graphs"
+          },
           {
             "label": "Tasks",
             "page": "tasks",
@@ -27,9 +49,18 @@
               "hideWhenZero": true
             }
           },
-          { "label": "Cockpit", "page": "cockpit" },
-          { "label": "Board", "page": "board" },
-          { "label": "Velocity", "page": "velocity" }
+          {
+            "label": "Cockpit",
+            "page": "cockpit"
+          },
+          {
+            "label": "Board",
+            "page": "board"
+          },
+          {
+            "label": "Velocity",
+            "page": "velocity"
+          }
         ],
         "sticky": true
       }

package/pages/velocity.page.json

@@ -13,6 +13,10 @@
             "label": "Overview",
             "page": "overview"
           },
+          {
+            "label": "Connect over MCP",
+            "page": "mcp"
+          },
           {
             "label": "Lineage",
             "page": "lineage"