@nanobpm/nano-workforce 0.178.2 → 0.178.4

package/.github/workflows/release.yml

@@ -7,6 +7,16 @@ on:
   workflow_run:
     workflows: ["CI", "Whole-repo invariants (merge-skew guard)"]
     types: [completed]
+  # Manual escape hatch. The automatic path above depends on the post-merge
+  # `push:main` event that normally follows a merge-queue landing. That event can
+  # go MISSING when an out-of-band bypass push to `main` (a `chore(release)
+  # [skip ci]` commit from the release App) races the queue's merge — the merged
+  # commit then lands with only its `merge_group` run and no `push` run, so the
+  # `workflow_run` trigger never sees `event == 'push'` and the release wedges
+  # with no way to retrigger. Dispatching runs the SAME green-gate against
+  # `main`'s HEAD (the merge_group checks are attached to that commit), so a
+  # manual recovery still never ships from a red `main`.
+  workflow_dispatch:
 
 # Prevent overlapping releases from racing on the same branch.
 concurrency:
@@ -26,9 +36,10 @@ jobs:
     name: release gate
     runs-on: ubuntu-latest
     if: >-
-      github.event.workflow_run.event == 'push' &&
-      github.event.workflow_run.head_branch == 'main' &&
-      github.event.workflow_run.conclusion == 'success'
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.workflow_run.event == 'push' &&
+       github.event.workflow_run.head_branch == 'main' &&
+       github.event.workflow_run.conclusion == 'success')
     permissions:
       checks: read
       contents: read
@@ -39,7 +50,7 @@ jobs:
         id: gate
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          SHA: ${{ github.event.workflow_run.head_sha }}
+          SHA: ${{ github.event.workflow_run.head_sha || github.sha }}
           REPO: ${{ github.repository }}
         run: |
           set -euo pipefail
@@ -78,7 +89,7 @@ jobs:
       # done with the release App token below — it is the ruleset bypass actor. The
       # job's own GITHUB_TOKEN only needs OIDC for npm Trusted Publishing.
       contents: read
-      id-token: write # OIDC token for npm Trusted Publishing (no NPM_TOKEN)
+      id-token: write # OIDC for npm Trusted Publishing + provenance (the only auth path)
     steps:
       # Mint a short-lived token for the dedicated release GitHub App. This App is
       # the ruleset's bypass actor, so @semantic-release/git can push the version
@@ -96,7 +107,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
-          ref: ${{ github.event.workflow_run.head_sha }} # release the exact gated commit
+          ref: ${{ github.event.workflow_run.head_sha || github.sha }} # release the exact gated commit
           fetch-depth: 0 # semantic-release needs full history + tags
           persist-credentials: true # let @semantic-release/git push the release commit
           token: ${{ steps.app-token.outputs.token }} # push as the bypass-actor App
@@ -129,8 +140,63 @@ jobs:
         run: npm ci
 
       - name: Release
+        id: release
+        # OIDC Trusted Publishing is the ONLY automated auth path: npm has retired
+        # automation tokens that bypass 2FA, so there is no CI token fallback — it is
+        # OIDC or a human `npm publish` locally. OIDC is intermittently flaky, though:
+        # npm has returned `401 … Failed to generate Web Auth URLs … token is invalid`
+        # mid-publish. @semantic-release/git pushes the tag + release commit in the
+        # `prepare` step BEFORE @semantic-release/npm `publish`, so an OIDC publish
+        # failure orphans a git tag with no npm package (the v0.178.3 phantom).
+        # Don't fail the job here — let the OIDC publish-retry step below recover it.
+        continue-on-error: true
         env:
           GITHUB_TOKEN: ${{ steps.app-token.outputs.token }} # bypass-actor App token
-          # No NPM_TOKEN / NODE_AUTH_TOKEN: publishing uses OIDC Trusted Publishing.
+          # No NPM_TOKEN / NODE_AUTH_TOKEN: publishing is OIDC Trusted Publishing only.
           NPM_CONFIG_PROVENANCE: "true"
         run: npx semantic-release
+
+      # Recovery: if the OIDC publish 401s, semantic-release has already bumped
+      # package.json + pushed the tag/release commit, but npm never got the tarball.
+      # The failure is INTERMITTENT (a prior version published fine), so retry the
+      # OIDC publish of the just-prepared version a few times with backoff — still no
+      # token, still OIDC + provenance via the job's id-token. This step is a NO-OP
+      # when the release step succeeded or when the version is already on npm, so it
+      # can never double-publish. If OIDC stays down through every retry, fail loudly:
+      # a human must `npm publish` the pushed tag locally (npm login with 2FA, then
+      # `git checkout vX.Y.Z && npm ci && npm publish --provenance --access public`).
+      - name: Retry OIDC publish if the release publish failed
+        if: steps.release.outcome == 'failure'
+        env:
+          NPM_CONFIG_PROVENANCE: "true"
+          GH_TOKEN: ${{ steps.app-token.outputs.token }} # to create the skipped GitHub Release
+        run: |
+          set -uo pipefail
+          PKG="$(node -p "require('./package.json').name")"
+          VERSION="$(node -p "require('./package.json').version")"
+          if npm view "${PKG}@${VERSION}" version >/dev/null 2>&1; then
+            echo "${PKG}@${VERSION} is already on npm — nothing to recover."
+            exit 0
+          fi
+          echo "semantic-release prepared + tagged ${PKG}@${VERSION} but the OIDC publish failed; retrying."
+          published=false
+          for attempt in 1 2 3; do
+            echo "OIDC publish attempt ${attempt}/3 for ${PKG}@${VERSION}"
+            if npm publish --provenance --access public; then
+              echo "Published ${PKG}@${VERSION} on retry ${attempt}."
+              published=true
+              break
+            fi
+            sleep $((attempt * 30))
+          done
+          if [ "$published" != true ]; then
+            echo "::error::OIDC publish of ${PKG}@${VERSION} still failing after retries. The git tag v${VERSION} is pushed but npm has no tarball. Publish it locally: 'git fetch --tags && git checkout v${VERSION} && npm ci && npm publish --provenance --access public' (npm login with 2FA first)."
+            exit 1
+          fi
+          # semantic-release aborts before @semantic-release/github when the npm
+          # publish throws, so the GitHub Release was never created — create it now.
+          if ! gh release view "v${VERSION}" >/dev/null 2>&1; then
+            echo "Creating the GitHub Release skipped by the aborted semantic-release run."
+            gh release create "v${VERSION}" --verify-tag --generate-notes --title "v${VERSION}" || \
+              echo "::warning::Published to npm but failed to create GitHub Release v${VERSION}; create it manually."
+          fi

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [0.178.4](https://github.com/nanobpm/nano-workforce/compare/v0.178.3...v0.178.4) (2026-09-03)
+
+### Bug Fixes
+
+* **mcp:** align session-selfheal e2e with urban 0.90.1 spec-conformant 404/-32001 ([#724](https://github.com/nanobpm/nano-workforce/issues/724)) ([5f54f3c](https://github.com/nanobpm/nano-workforce/commit/5f54f3ce42bbcbf30715bf17829e3f9ddd9cf793)), closes [#715](https://github.com/nanobpm/nano-workforce/issues/715)
+
+## [0.178.3](https://github.com/nanobpm/nano-workforce/compare/v0.178.2...v0.178.3) (2026-09-03)
+
+### Bug Fixes
+
+* **ci:** add manual workflow_dispatch escape hatch to the release pipeline ([#723](https://github.com/nanobpm/nano-workforce/issues/723)) ([4d06f25](https://github.com/nanobpm/nano-workforce/commit/4d06f259aee7a5689844ddd0dfe3f68253c9fc37))
+* **ci:** retry OIDC publish when the release publish 401s; reclaim v0.178.3 ([#722](https://github.com/nanobpm/nano-workforce/issues/722)) ([208c02d](https://github.com/nanobpm/nano-workforce/commit/208c02dd1936c70635a5108887f452143a8dbc26))
+
+### Documentation
+
+* refresh stale --version pin example in the upgrade guide ([#721](https://github.com/nanobpm/nano-workforce/issues/721)) ([75dbcec](https://github.com/nanobpm/nano-workforce/commit/75dbcecc93b4adef3bb4d6a05f6010ed44ea74dd))
+
 ## [0.178.2](https://github.com/nanobpm/nano-workforce/compare/v0.178.1...v0.178.2) (2026-09-03)
 
 ### Bug Fixes

package/README.md

@@ -185,7 +185,7 @@ and runs the review-ready poller.
 ```sh
 npm run upgrade                              # dry-run against @latest
 npm run upgrade -- --apply                   # apply the overlay, preserving app.db
-npm run upgrade -- --version 0.26.0 --apply  # pin a specific version
+npm run upgrade -- --version 0.178.2 --apply  # pin a specific version
 npm run upgrade -- --from ./pkg.tgz --apply  # from a local tarball (offline)
 ```
 

package/e2e/mcp-session-selfheal.e2e.ts

@@ -3,20 +3,25 @@
 // WHAT THIS PINS
 // ==============
 // The runtime-served MCP surface (`/app/mcp`, ADR 0067) is a **stateful streamable-HTTP** transport:
-// every `tools/call` MUST carry a valid `mcp-session-id`, and a call with a missing / stale / evicted
-// / deleted session id is refused with JSON-RPC `-32000 "Bad Request: no valid session id, and not an
-// initialize request."` (mcp.ts). In the field (issue #715) a single hiccup — a heavy-tool timeout,
-// an idle drop, a proxy reset, or LRU eviction (`MAX_SESSIONS`) — loses the session and then bricks
-// the ENTIRE surface for a client that does not re-`initialize`: every subsequent tool reads as
-// "tool does not exist". The stateless/resumable transport that would remove the session dependency
-// lives in the urban runtime and is tracked upstream (nano-ide#488); until it lands, the
-// **workforce-visible requirement** (this issue) is that the surface is RECOVERABLE — a client that
-// re-`initialize`s after a `-32000` gets the WHOLE surface back in one round trip, not a degraded one.
+// every `tools/call` MUST carry a valid `mcp-session-id`. Per the MCP Streamable-HTTP spec the runtime
+// distinguishes two refusals (urban ≥ 0.90.1): a session id that is SUPPLIED but unknown / stale /
+// evicted / deleted is a terminated session, answered `404` with JSON-RPC `-32001 "Session not found:
+// unknown or expired mcp-session-id."` so the client transparently re-initializes; only a GENUINELY
+// MISSING id (no header at all) is the `400` / `-32000 "Bad Request: no valid session id, and not an
+// initialize request."` bad-client case (mcp.ts). In the field (issue #715) a single hiccup — a
+// heavy-tool timeout, an idle drop, a proxy reset, or LRU eviction (`MAX_SESSIONS`) — loses the
+// session and then bricks the ENTIRE surface for a client that does not re-`initialize`: every
+// subsequent tool reads as "tool does not exist". The stateless/resumable transport that would remove
+// the session dependency lives in the urban runtime and is tracked upstream (nano-ide#488); until it
+// lands, the **workforce-visible requirement** (this issue) is that the surface is RECOVERABLE — a
+// client that re-`initialize`s after a gone-session refusal gets the WHOLE surface back in one round
+// trip, not a degraded one.
 //
 // This is the acceptance regression: "kill the session mid-flight and assert the next call still
 // works." It kills the session two faithful ways — an unknown/stale id, and a server-side `DELETE`
-// (the spec session-termination verb) of a live id — asserts each bricks a call with the exact
-// `-32000` signature, then asserts a single client `reinitialize()` fully restores the surface
+// (the spec session-termination verb) of a live id — asserts each bricks a call with a session-gone
+// signature (a supplied-unknown id → `404` / `-32001`, a DELETEd id → the SDK transport's `Session
+// not found`), then asserts a single client `reinitialize()` fully restores the surface
 // (a working `tools/call` AND the complete `tools/list`). If a future runtime makes the transport
 // stateless/resumable (nano-ide#488), the stale-id call simply stops erroring — this test then
 // tightens to that stronger contract with a one-line change, never silently passing on a regression.
@@ -27,14 +32,12 @@ import { randomUUID } from "node:crypto";
 import { after, before, describe, test } from "node:test";
 import { bootMcpHarness, type McpHarness } from "./support/mcp-harness.ts";
 
-/** The exact runtime signature of a lost/absent session (mcp.ts). A recovered surface must NOT
- *  answer with this after a re-`initialize`. */
-const NO_SESSION_SIGNATURE = "no valid session id";
-
-/** Any "the session is gone" refusal: the runtime's own `-32000` "no valid session id" (unknown id)
- *  OR the SDK transport's "Session not found" (a terminated/DELETEd id). Either proves the call was
- *  refused because the session no longer exists — the field failure #715 gap 1 is about. */
-const SESSION_GONE = /no valid session id|session not found/i;
+/** Any "the session is gone" refusal, in either faithful form: the runtime's `-32001` "Session not
+ *  found: unknown or expired …" for a SUPPLIED but unknown / stale / evicted / DELETEd id (urban
+ *  ≥ 0.90.1), OR the SDK transport's own "Session not found" for a terminated id. Either proves the
+ *  call was refused because the session no longer exists — the field failure #715 gap 1 is about. A
+ *  recovered surface must NOT answer with this after a re-`initialize`. */
+const SESSION_GONE = /session not found|unknown or expired|no valid session id/i;
 
 /** A safe, side-effect-free read used as the "does the surface answer?" probe. */
 const PROBE_TOOL = "getVersion";
@@ -53,14 +56,22 @@ describe("#715 gap 1 — a lost MCP session self-heals on client re-initialize",
     assert(!res.isError, `baseline ${PROBE_TOOL} should succeed on a live session: ${res.text}`);
   });
 
-  test("an unknown/stale session id bricks a call with -32000, and re-initialize restores the surface", async () => {
+  test("an unknown/stale session id bricks a call with 404 / -32001, and re-initialize restores the surface", async () => {
     // A stale id models an evicted (LRU / idle-dropped) or proxy-reset session the client still holds.
     const staleId = `stale-${randomUUID()}`;
     const bricked = await h.callToolAs(staleId, PROBE_TOOL);
     assert(bricked.isError, "a call carrying a stale session id must be refused, not answered");
+    // A SUPPLIED-but-unknown id is a terminated session: per the MCP Streamable-HTTP spec the runtime
+    // answers 404 / -32001 "Session not found: unknown or expired …" (urban ≥ 0.90.1) so the client
+    // transparently re-initializes, rather than the 400 / -32000 reserved for a genuinely missing id.
+    assert.equal(
+      bricked.httpStatus,
+      404,
+      `a stale (supplied-but-unknown) session id must be refused 404 so the client re-initializes, got HTTP ${bricked.httpStatus}: ${bricked.text}`,
+    );
     assert(
-      bricked.text.includes(NO_SESSION_SIGNATURE),
-      `a stale-session call must fail with the "${NO_SESSION_SIGNATURE}" signature, got: ${bricked.text}`,
+      SESSION_GONE.test(bricked.text),
+      `a stale-session call must fail with a session-gone signature, got: ${bricked.text}`,
     );
 
     // Client self-heal: re-run the handshake. The pinned runtime is stateful, so this is how a real
@@ -72,8 +83,8 @@ describe("#715 gap 1 — a lost MCP session self-heals on client re-initialize",
     const healed = await h.callTool(PROBE_TOOL);
     assert(!healed.isError, `after reinitialize the surface must answer again: ${healed.text}`);
     assert(
-      !healed.text.includes(NO_SESSION_SIGNATURE),
-      "a healed call must not still report a missing session",
+      !SESSION_GONE.test(healed.text),
+      "a healed call must not still report a gone session",
     );
 
     // And the FULL projected catalogue is restored — the field failure was "every tool vanished".
@@ -95,9 +106,10 @@ describe("#715 gap 1 — a lost MCP session self-heals on client re-initialize",
     const status = await h.deleteSession(killedId);
     assert(status < 500, `DELETE session should not server-error, got ${status}`);
 
-    // The now-terminated id bricks a call — the mid-flight hiccup. A terminated session surfaces the
-    // SDK transport's "Session not found"; an unknown id surfaces the runtime's "no valid session id"
-    // — both mean the session is gone and the call was refused, not answered.
+    // The now-terminated id bricks a call — the mid-flight hiccup. Both a DELETEd/terminated id and a
+    // supplied-but-unknown id now surface a "Session not found" gone-signal (the SDK transport's own,
+    // or the runtime's 404 / -32001 "unknown or expired") — either means the session is gone and the
+    // call was refused, not answered.
     const bricked = await h.callToolAs(killedId, PROBE_TOOL);
     assert(bricked.isError, "a call on a DELETEd session id must be refused");
     assert(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.178.2",
+  "version": "0.178.4",
   "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",
@@ -65,7 +65,7 @@
   },
   "dependencies": {
     "@nanobpm/agentic": "^0.12.0",
-    "@nanobpm/urban": "^0.90.0",
+    "@nanobpm/urban": "^0.90.1",
     "bpmn-auto-layout": "^2.0.0-alpha.2"
   },
   "devDependencies": {