@nanobpm/nano-workforce 0.152.0 → 0.154.0

package/.github/workflows/ci.yml

@@ -92,10 +92,11 @@ jobs:
   # blocker, and a self-proving canary asserts the oracle's red path genuinely fires so the gate can
   # never rot into a vacuous green while the corpus is parked. Hermetic (in-process wasm engine, no
   # sockets), so it runs on every PR/push as its own job.
-  # install.sh onboarding script (issue #576): POSIX-sh cleanliness + a hermetic
-  # dry-run smoke test asserting the emitted command sequence. The script is
-  # served from `main` for `curl … | sh`, so a broken change is live the instant
-  # it merges — this gate keeps that surface honest.
+  # install.sh onboarding script (issues #576 + #583): POSIX-sh cleanliness + a
+  # hermetic smoke test asserting the emitted command sequence (phase 1) and the
+  # phase-2 console call flow (dry-run + a stubbed-console live run). The script
+  # is served from `main` for `curl … | sh`, so a broken change is live the
+  # instant it merges — this gate keeps that surface honest.
   install-script:
     name: install.sh (shellcheck + dry-run smoke)
     runs-on: ubuntu-latest
@@ -111,7 +112,7 @@ jobs:
       - name: shellcheck (POSIX sh)
         run: shellcheck -s sh install.sh test/install-smoke.sh
 
-      - name: Dry-run smoke test
+      - name: Smoke test (dry-run sequence + stubbed-console phase 2)
         run: sh test/install-smoke.sh
 
   derivation-parity:

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.154.0](https://github.com/nanobpm/nano-workforce/compare/v0.153.0...v0.154.0) (2026-08-29)
+
+### Features
+
+* **onboarding:** three-state GitHub credential preflight in install.sh ([#599](https://github.com/nanobpm/nano-workforce/issues/599)) ([7e9f592](https://github.com/nanobpm/nano-workforce/commit/7e9f592632fc85cfea9f89843252c0128cec6c8d)), closes [#588](https://github.com/nanobpm/nano-workforce/issues/588)
+
+## [0.153.0](https://github.com/nanobpm/nano-workforce/compare/v0.152.0...v0.153.0) (2026-08-29)
+
+### Features
+
+* **onboarding:** install-script phase 2 — install, scaffold, configure & run the Workforce app ([#598](https://github.com/nanobpm/nano-workforce/issues/598)) ([e86f9ca](https://github.com/nanobpm/nano-workforce/commit/e86f9ca292998481e1fd194859832e9040bf0b51)), closes [nanobpm/nano-workforce#583](https://github.com/nanobpm/nano-workforce/issues/583) [Magikcraft/nano-bpm#1036](https://github.com/Magikcraft/nano-bpm/issues/1036) [#583](https://github.com/nanobpm/nano-workforce/issues/583)
+
 ## [0.152.0](https://github.com/nanobpm/nano-workforce/compare/v0.151.1...v0.152.0) (2026-08-28)
 
 ### Features

package/README.md

@@ -83,41 +83,73 @@ it's the same app and the same behaviour.
 
 If you already have one or more coding-agent CLIs installed (`kimi`, `qwen`,
 `copilot`, `claude`, `pi`), one command takes you from there to a **running Nano
-engine with a supervised workforce of hired agents**:
+Workforce**: engine, a supervised workforce of hired agents, **and the Nano
+Workforce app itself, installed, configured, and running**:
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/nanobpm/nano-workforce/main/install.sh | sh
 ```
 
-It installs `@camunda8/cli` and the `c8ctl-plugin-nano` plugin, installs shell
-completion, detects which of your harnesses are installed, lets you multi-select
-which to hire (with a model and an instance count each), hires each with
-`--rank senior --protocol acp --permission yolo`, composes a declarative
-**workforce manifest** (`c8 nano workforce add`), and brings it up
-(`c8 nano start` then `c8 nano workforce start`).
+**Phase 1 — engine + workforce.** It installs `@camunda8/cli` and the
+`c8ctl-plugin-nano` plugin, installs shell completion, detects which of your
+harnesses are installed, lets you multi-select which to hire (with a model and an
+instance count each), hires each with `--rank senior --protocol acp --permission
+yolo`, composes a declarative **workforce manifest** (`c8 nano workforce add`),
+and brings it up (`c8 nano start` then `c8 nano workforce start`).
+
+**GitHub access preflight.** Because a workforce with no GitHub credential can
+neither review, push, nor merge, the preflight checks for a **usable** credential
+on this host before hiring: a `GITHUB_TOKEN`/`GH_TOKEN` in the environment
+*(validated with `gh api user` / a raw `api.github.com/user` probe, not trusted
+merely for being set — in the rare case where neither `gh` nor `curl` is present
+to probe with, it cannot validate and warns that it is proceeding on trust)*, or
+the `gh` CLI *installed, authenticated, and proven with
+`gh api user`*. It
+distinguishes gh missing, installed-but-unauthenticated, and
+authenticated-but-unusable (expired token, missing `repo` scope, SAML SSO), warns
+(but does not fail) on a missing `workflow` scope, and checks `git` too. It prints
+a platform-aware install hint and the `gh auth login` / `GITHUB_TOKEN` remediation
+— it never runs `gh auth login` for you. Interactive runs let you fix it and
+re-check, or confirm-to-continue (default no); non-interactive runs **fail** unless
+you pass `--allow-no-github`. The check covers **this host only** — remote worker
+hosts each need their own credential.
+
+**Phase 2 — the app.** It then talks to the nano console the engine brought up to
+install the `@nanobpm/nano-workforce` extension, scaffold a **Workforce** project
+from the `nano-workforce` template, write its `ProjectConfig.env` (including
+`NANO_WORKFORCE_BASE_URL` set to the console origin + `/console/app-view/Workforce`
+so the fleet's hooks resolve through the proxy — see [Fleet
+networking](#fleet-networking-remote-workers)), and run it. It confirms readiness
+by polling the app's own `GET /app/api/version` through the proxy, then prints the
+cockpit URL, the Tasks inbox, the Delivery Graphs page, and the `/app/api/agent` +
+`/app/mcp` pointers. Pass `--skip-app` to stop after phase 1.
 
 > ⚠️ The hired agents run **unattended** with `--permission yolo` — full tool
 > access (shell, file writes, network) as your user on this host. The script shows
-> a confirmation summary before it hires anything; pass `--yes` to skip it.
-
-**What it does *not* do:** it stops at "engine up, workforce up, agents polling".
-It does **not** install/deploy/run the Nano Workforce **app** itself — for that,
-use Nano Studio (above) or the manual steps below.
+> a confirmation summary before it hires anything (and before it installs the app);
+> pass `--yes` to skip both.
 
 Prompts read from `/dev/tty`, so the `curl … | sh` pipe works interactively. It is
-also fully scriptable and safe to re-run (it converges rather than duplicating):
+also fully scriptable and safe to re-run (it converges rather than duplicating — an
+existing project is configured and run, never re-scaffolded):
 
 ```sh
 # Non-interactive (CI / re-provisioning); repeatable --harness <name>[:<model>][:<instances>]
 curl -fsSL https://raw.githubusercontent.com/nanobpm/nano-workforce/main/install.sh | sh -s -- --harness copilot:gpt-5.4:5 --harness claude:opus:1 --yes
 
-# Preview every command without changing anything
+# Name the app's project, or stop after phase 1 (engine + workforce only)
+curl -fsSL .../install.sh | sh -s -- --harness copilot:gpt-5.4:5 --yes --project-name Workforce
+curl -fsSL .../install.sh | sh -s -- --harness copilot:gpt-5.4:5 --yes --skip-app
+
+# Preview every command (including the console API calls) without changing anything
 curl -fsSL https://raw.githubusercontent.com/nanobpm/nano-workforce/main/install.sh | sh -s -- --harness copilot:gpt-5.4:1 --dry-run
 ```
 
 `qwen` must always be given an explicit model (it stalls without one). With no
 controlling terminal and no `--harness`, the script exits with usage rather than
-hanging. Because it is served from `main`, a merged change to `install.sh` is live
+hanging. Phase 2 needs the engine's console reachable (the default `c8 nano start`
+`studio` mode); an unreachable console is reported as an early failure that changes
+nothing. Because it is served from `main`, a merged change to `install.sh` is live
 immediately.
 
 ### Prerequisites

package/install.sh

@@ -79,6 +79,10 @@ DRY_RUN=0
 ASSUME_YES=0
 SHELL_OVERRIDE=''
 INSTALL_ADAPTERS=0        # auto-install missing adapters without prompting
+ALLOW_NO_GITHUB=0        # non-interactive: proceed even without usable GitHub access
+GITHUB_DEGRADED=''       # non-empty => the GitHub preflight passed in a degraded state; repeated in the final summary
+SKIP_APP=0               # phase 1 only: bring up engine + workforce, don't install the app
+PROJECT_NAME=''          # console project name for the Nano Workforce app (default: Workforce)
 CLI_HARNESS_SPECS=''      # newline-separated name[:model][:instances] from --harness
 SELECTIONS=''             # newline-separated "name<US>model<US>instances" (US = non-whitespace 0x1f, so an empty model field does not collapse under read)
 FAILURES=''               # newline-separated failure notes (partial-success report)
@@ -95,9 +99,39 @@ ADAPTERS_PRESENT="${NANO_INSTALL_ADAPTERS_PRESENT:-}"
 if [ "${NANO_INSTALL_HARNESSES_OVERRIDE+set}" = set ]; then HARNESS_OVERRIDE_SET=1; else HARNESS_OVERRIDE_SET=0; fi
 if [ "${NANO_INSTALL_ADAPTERS_PRESENT+set}" = set ]; then ADAPTERS_PRESENT_SET=1; else ADAPTERS_PRESENT_SET=0; fi
 
+# Test hooks for the GitHub credential preflight (undocumented; keep the smoke
+# test hermetic on runners that may or may not ship an authenticated gh):
+#   NANO_INSTALL_GH_STATE    — force gh state: missing|unauthed|unusable|ok
+#   NANO_INSTALL_GH_SCOPES   — comma/space list of token scopes gh reports
+#   NANO_INSTALL_GIT_STATE   — force git state: missing|present
+#   NANO_INSTALL_TOKEN_STATE — force env-token validity: ok|bad (skips the real
+#                              gh/api.github.com probe so tests need no network)
+# A set-but-empty override still counts as set, so the probe never falls back to
+# the real command -v / gh and the smoke test stays hermetic.
+if [ "${NANO_INSTALL_GH_STATE+set}" = set ]; then GH_STATE_OVERRIDE_SET=1; else GH_STATE_OVERRIDE_SET=0; fi
+if [ "${NANO_INSTALL_GIT_STATE+set}" = set ]; then GIT_STATE_OVERRIDE_SET=1; else GIT_STATE_OVERRIDE_SET=0; fi
+if [ "${NANO_INSTALL_TOKEN_STATE+set}" = set ]; then TOKEN_STATE_OVERRIDE_SET=1; else TOKEN_STATE_OVERRIDE_SET=0; fi
+
 CLI=''      # resolved c8ctl / c8 binary
 TTY=''      # /dev/tty if usable, else empty
 
+# ---------------------------------------------------------------------------
+# Phase 2 (app install) configuration + test hooks.
+#   NANO_INSTALL_CONSOLE_ORIGIN     — override the console/engine origin (tests).
+#   NANO_INSTALL_APP_POLL_ATTEMPTS  — readiness-poll attempt count (tests).
+#   NANO_INSTALL_APP_POLL_INTERVAL  — seconds between readiness polls (tests).
+# CONSOLE_ORIGIN is the scheme://host:port the nano console+engine listen on
+# (default http://localhost:8080); the console API lives under /console there.
+CONSOLE_ORIGIN=''
+APPVIEW_BASE=''
+PROJECT=''
+APP_POLL_ATTEMPTS="${NANO_INSTALL_APP_POLL_ATTEMPTS:-60}"
+APP_POLL_INTERVAL="${NANO_INSTALL_APP_POLL_INTERVAL:-2}"
+# Results of the last api() call.
+API_STATUS=''
+API_BODY=''
+API_ERR=0
+
 # ---------------------------------------------------------------------------
 # Command runner — honours --dry-run for mutating commands.
 # ---------------------------------------------------------------------------
@@ -200,6 +234,15 @@ Options:
   -y, --yes          Skip the confirmation summary.
   --install-adapters Auto-install a selected harness's missing ACP adapter
                      (claude/pi) instead of prompting/skipping.
+  --allow-no-github  Proceed even when no usable GitHub access is detected. In a
+                     non-interactive run the preflight otherwise fails, since a
+                     workforce with no GitHub credential cannot review, push, or
+                     merge. Interactive runs prompt instead.
+  --project-name <name>
+                     Console project name for the Nano Workforce app
+                     (default: Workforce). [A-Za-z0-9._-] only.
+  --skip-app         Run phase 1 only (engine + workforce); do NOT install,
+                     scaffold, configure, or run the Nano Workforce app.
   --shell <bash|zsh|fish>
                      Override shell-completion detection.
   --dry-run          Print every command that would run; change nothing.
@@ -208,6 +251,13 @@ Options:
 Non-interactive example:
   curl -fsSL .../install.sh | sh -s -- --harness copilot:gpt-5.4:5 --harness claude:opus:1 --yes
 
+Phases:
+  1. (nanobpm/nano-workforce#576) install @camunda8/cli + the nano plugin, hire
+     your harnesses, compose a workforce manifest, bring up engine + workforce.
+  2. (nanobpm/nano-workforce#583) install the @nanobpm/nano-workforce console
+     extension, scaffold + configure + run a Workforce project, and print its
+     app-view URL. Skip it with --skip-app.
+
 With no controlling terminal (/dev/tty) and no --harness, the script exits
 non-zero rather than hanging on a prompt.
 EOF
@@ -230,6 +280,12 @@ parse_args() {
         shift ;;
       --yes|-y) ASSUME_YES=1; shift ;;
       --install-adapters) INSTALL_ADAPTERS=1; shift ;;
+      --allow-no-github) ALLOW_NO_GITHUB=1; shift ;;
+      --skip-app) SKIP_APP=1; shift ;;
+      --project-name)
+        [ $# -ge 2 ] || die "--project-name requires a value"
+        PROJECT_NAME=$2; shift 2 ;;
+      --project-name=*) PROJECT_NAME=${1#--project-name=}; shift ;;
       --dry-run) DRY_RUN=1; shift ;;
       --shell)
         [ $# -ge 2 ] || die "--shell requires a value (bash|zsh|fish)"
@@ -241,6 +297,210 @@ parse_args() {
   done
 }
 
+# ---------------------------------------------------------------------------
+# GitHub credential preflight (nanobpm/nano-workforce#588)
+#
+# Two consumers need GitHub access and fail differently: the nwf app (review
+# poller + merge stage) and each hired agent worker (shells out to gh/git). The
+# real predicate is "a usable credential exists on this host", not "gh is
+# installed" — a token in GITHUB_TOKEN/GH_TOKEN satisfies both without gh.
+#
+# Detection distinguishes three states beyond present/absent: not installed,
+# installed-but-unauthenticated, and authenticated-but-unusable (a push/PR that
+# 403s only later — expired token, missing scope, SAML SSO, fine-grained PAT
+# without repo access). We prove usability with `gh api user`, never trusting
+# `gh auth status` alone.
+# ---------------------------------------------------------------------------
+gh_present() { # 0 if the gh CLI is available (honours the test hook)
+  if [ "$GH_STATE_OVERRIDE_SET" -eq 1 ]; then
+    case "$NANO_INSTALL_GH_STATE" in missing) return 1 ;; *) return 0 ;; esac
+  fi
+  command -v gh >/dev/null 2>&1
+}
+
+gh_authed() { # 0 if gh auth status succeeds (honours the test hook)
+  if [ "$GH_STATE_OVERRIDE_SET" -eq 1 ]; then
+    case "$NANO_INSTALL_GH_STATE" in missing|unauthed) return 1 ;; *) return 0 ;; esac
+  fi
+  gh auth status >/dev/null 2>&1
+}
+
+gh_usable() { # 0 if gh api user actually works — validates token + network + SSO
+  if [ "$GH_STATE_OVERRIDE_SET" -eq 1 ]; then
+    case "$NANO_INSTALL_GH_STATE" in ok) return 0 ;; *) return 1 ;; esac
+  fi
+  gh api user --jq .login >/dev/null 2>&1
+}
+
+gh_token_usable() { # 0 if the env GITHUB_TOKEN/GH_TOKEN actually authenticates
+  # An expired/revoked/underscoped token is the *exact* late failure this
+  # preflight exists to catch, so a non-empty token is not trusted blindly — we
+  # prove it works (gh api user, or a raw api.github.com/user probe when gh is
+  # absent). Honours the test hook so the smoke suite needs no network.
+  if [ "$TOKEN_STATE_OVERRIDE_SET" -eq 1 ]; then
+    case "$NANO_INSTALL_TOKEN_STATE" in ok) return 0 ;; *) return 1 ;; esac
+  fi
+  _tok="${GITHUB_TOKEN:-${GH_TOKEN:-}}"
+  if gh_present; then
+    GITHUB_TOKEN="$_tok" GH_TOKEN="$_tok" gh api user --jq .login >/dev/null 2>&1
+  elif command -v curl >/dev/null 2>&1; then
+    # Pass the token via --config on stdin so it never lands in curl's argv
+    # (readable by other users via `ps` on a multi-user host).
+    printf 'header = "Authorization: Bearer %s"\n' "$_tok" | \
+      curl -fsS --connect-timeout 5 --max-time 10 --config - \
+        -H "User-Agent: nano-workforce-install" \
+        https://api.github.com/user >/dev/null 2>&1
+  else
+    # No gh and no curl to validate with — we cannot prove the token works,
+    # so warn explicitly rather than let an unvalidated token look "usable".
+    warn "cannot validate GITHUB_TOKEN/GH_TOKEN — neither gh nor curl is available on this host; proceeding on trust (an expired or under-scoped token will only fail later)."
+    return 0
+  fi
+}
+
+gh_scopes() { # print space-separated token scopes gh reports (honours the test hook)
+  if [ "$GH_STATE_OVERRIDE_SET" -eq 1 ]; then
+    printf '%s' "${NANO_INSTALL_GH_SCOPES:-}" | tr ',' ' '
+    return 0
+  fi
+  # gh auth status prints e.g.:  - Token scopes: 'gist', 'read:org', 'repo', 'workflow'
+  gh auth status 2>&1 | sed -n "s/.*Token scopes:[ ]*//p" | tr -d "'" | tr ',' ' '
+}
+
+git_present() { # 0 if git is available (honours the test hook)
+  if [ "$GIT_STATE_OVERRIDE_SET" -eq 1 ]; then
+    case "$NANO_INSTALL_GIT_STATE" in missing) return 1 ;; *) return 0 ;; esac
+  fi
+  command -v git >/dev/null 2>&1
+}
+
+# Platform-aware install + remediation hint. We print the command; we NEVER run
+# `gh auth login` for the user (it is an interactive device/OAuth flow that
+# should stay in their hands).
+gh_remediation_hint() {
+  note "GitHub access not detected. The workforce cannot review, push, or merge without it."
+  note ""
+  note "  macOS         brew install gh"
+  note "  Debian/Ubuntu sudo apt install gh"
+  note "  Fedora        sudo dnf install gh"
+  note "  Arch          sudo pacman -S gh"
+  note "  other         https://github.com/cli/cli#installation"
+  note ""
+  note "Then:  gh auth login          (or export GITHUB_TOKEN=…)"
+}
+
+# One probe pass. Sets GH_PROBE_MSG (human summary) and returns 0 when a usable
+# credential exists, 1 otherwise. Warns (non-fatal) when the workflow scope is
+# absent, since that only bites on workflow-file changes.
+probe_github() {
+  GH_PROBE_MSG=''
+  # 1. token in env → validate it (don't trust a non-empty value), skip gh
+  #    scope checks (a raw token exposes no scopes here) once it authenticates.
+  if [ -n "${GITHUB_TOKEN:-${GH_TOKEN:-}}" ]; then
+    if ! gh_token_usable; then
+      GH_PROBE_MSG="a GITHUB_TOKEN/GH_TOKEN is set but it failed validation (gh api user / api.github.com/user) — it is expired, revoked, or lacks access. Fix or unset it."
+      return 1
+    fi
+    if gh_present; then
+      GH_PROBE_MSG="GitHub token detected in the environment (GITHUB_TOKEN/GH_TOKEN); gh CLI also present."
+    else
+      GH_PROBE_MSG="GitHub token detected in the environment (GITHUB_TOKEN/GH_TOKEN)."
+      note "A token is set, so the nwf app is fine (NANO_PR_GITHUB_TRANSPORT=token)."
+      note "But gh is NOT installed on this host — harnesses that shell out to 'gh' still won't work. Install gh too."
+    fi
+    return 0
+  fi
+  # 2. otherwise the host CLI must be present, authenticated, and usable.
+  if ! gh_present; then
+    GH_PROBE_MSG="no gh CLI and no GITHUB_TOKEN/GH_TOKEN in the environment."
+    return 1
+  fi
+  if ! gh_authed; then
+    GH_PROBE_MSG="gh is installed but not authenticated (gh auth status failed)."
+    return 1
+  fi
+  # 3. prove it actually works — don't just trust status.
+  if ! gh_usable; then
+    GH_PROBE_MSG="gh reports authenticated but 'gh api user' failed — the credential is unusable (expired/revoked token, network, or SAML SSO not authorized for the target org)."
+    return 1
+  fi
+  # 4. authenticated + usable: the repo scope is required, workflow only warns.
+  _scopes=$(gh_scopes)
+  case " $_scopes " in
+    *" repo "*) : ;;
+    *)
+      GH_PROBE_MSG="gh is authenticated but the token is missing the 'repo' scope — pushes and PR creation will 403. Re-auth with:  gh auth refresh -s repo"
+      return 1 ;;
+  esac
+  case " $_scopes " in
+    *" workflow "*) : ;;
+    *) warn "gh token is missing the 'workflow' scope — harmless unless agents edit workflow files; add it with:  gh auth refresh -s workflow" ;;
+  esac
+  GH_PROBE_MSG="GitHub access OK via the host gh CLI."
+  return 0
+}
+
+# The full preflight: probe, remediate, and decide whether to continue. Records
+# a degraded state (repeated in the final summary) whenever we proceed without a
+# usable credential, so a degraded install never *looks* complete.
+add_degraded() { # accumulate a degraded reason so a later one never masks an earlier
+  if [ -n "$GITHUB_DEGRADED" ]; then
+    GITHUB_DEGRADED="${GITHUB_DEGRADED}; $1"
+  else
+    GITHUB_DEGRADED="$1"
+  fi
+}
+github_preflight() {
+  info "Checking GitHub access (this host only)"
+
+  # git is needed by every worker (clone/commit/push) — check it alongside gh.
+  if git_present; then
+    ok "git present"
+  else
+    warn "git not found on this host — agents cannot clone, commit, or push without it."
+    note "Install git from https://git-scm.com/downloads, then re-run."
+    add_degraded "git is not installed on this host"
+  fi
+
+  while : ; do
+    if probe_github; then
+      ok "$GH_PROBE_MSG"
+      note "This check covers THIS host only — remote worker hosts each need their own gh auth / token."
+      break
+    fi
+
+    warn "$GH_PROBE_MSG"
+    gh_remediation_hint
+    note "This check covers THIS host only — remote worker hosts each need their own gh auth / token."
+
+    # Non-interactive (--yes, no /dev/tty, or --dry-run): no prompt is possible.
+    if [ "$ASSUME_YES" -eq 1 ] || [ "$DRY_RUN" -eq 1 ] || [ -z "$TTY" ]; then
+      if [ "$ALLOW_NO_GITHUB" -eq 1 ]; then
+        warn "continuing without GitHub access (--allow-no-github) — the agents will not be able to do GitHub work."
+        add_degraded "$GH_PROBE_MSG"
+        break
+      fi
+      # Dry-run changes nothing, so never fail on it — just report what a real run would do.
+      if [ "$DRY_RUN" -eq 1 ]; then
+        note "dry-run: not blocking on GitHub access (a real run would fail here without --allow-no-github)."
+        break
+      fi
+      die "GitHub access not detected and running non-interactively — fix it (see above) and re-run, or pass --allow-no-github to proceed anyway."
+    fi
+
+    # Interactive: let the user fix it and re-check without re-running the whole
+    # script, else confirm-to-continue (default no).
+    if confirm "I've set up GitHub access (installed gh / ran gh auth login / exported a token). Re-check now?"; then
+      continue
+    fi
+    if confirm "Continue anyway? The agents won't be able to do GitHub work."; then
+      add_degraded "$GH_PROBE_MSG"
+      break
+    fi
+    die "aborted — set up GitHub access (see above) and re-run."
+  done
+}
+
 # ---------------------------------------------------------------------------
 # Step 1 — Preflight
 # ---------------------------------------------------------------------------
@@ -254,18 +514,10 @@ preflight() {
   fi
   ok "node $_nv (>= ${MIN_NODE}), npm present"
 
-  # Non-fatal: agents need GitHub access to do useful work.
-  if [ -z "${GITHUB_TOKEN:-}" ] && [ -z "${GH_TOKEN:-}" ]; then
-    if command -v gh >/dev/null 2>&1; then
-      if ! gh auth status >/dev/null 2>&1; then
-        warn "gh is installed but not authenticated, and no GITHUB_TOKEN/GH_TOKEN is set."
-        note "Agents need GitHub access — run 'gh auth login' or export GITHUB_TOKEN before they start pulling work."
-      fi
-    else
-      warn "no gh CLI and no GITHUB_TOKEN/GH_TOKEN in the environment."
-      note "Agents need GitHub access — install gh (https://cli.github.com) and 'gh auth login', or export GITHUB_TOKEN."
-    fi
-  fi
+  # GitHub access — a workforce with no usable credential can do nothing useful,
+  # so this is a real three-state check with remediation (nanobpm/nano-workforce#588),
+  # not a passing mention. Covers this host only; remote worker hosts need their own.
+  github_preflight
 }
 
 # ---------------------------------------------------------------------------
@@ -438,7 +690,7 @@ live_models() { # $1 harness -> newline list on stdout
 # Step 4/5 — interactive selection + model + instances
 # ---------------------------------------------------------------------------
 add_selection() { # $1 harness $2 model $3 instances
-  if [ -n "$2" ] && ! printf '%s' "$2" | grep -Eq '^[A-Za-z0-9._/@+-]+$'; then
+  if [ -n "$2" ] && ! printf '%s' "$2" | LC_ALL=C grep -Eq '^[A-Za-z0-9._/@+-]+$'; then
     die "refusing model id '$2' for $1: only [A-Za-z0-9._/@+-] are allowed (':' is reserved as the --harness field separator, so it must not appear in a model id; guards against shell-metacharacter injection into the hire --command)."
   fi
   SELECTIONS="${SELECTIONS}$1${SEP}$2${SEP}$3
@@ -725,23 +977,418 @@ print_status_and_hints() {
   $CLI nano supervisor logs <worker> --follow       tail one worker's logs
   $CLI nano workforce stop   /   $CLI nano stop      shut the fleet / engine down
   $CLI nano hire --list                             the hired profiles
+EOF
+}
+
+# ---------------------------------------------------------------------------
+# Phase 2 — install & run the Nano Workforce app via the nano console API
+# (nanobpm/nano-workforce#583). Everything below talks to the console that
+# `c8 nano start` brought up (default http://localhost:8080, console under
+# /console). Under --dry-run, all live console calls are avoided — including
+# read-only GETs: --dry-run prints the exact calls and mutates (and reads) nothing.
+# ---------------------------------------------------------------------------
+
+# scheme://host:port of a URL (drops any path), e.g. http://localhost:8080/v2
+# -> http://localhost:8080.
+origin_of() {
+  _u=$1
+  case "$_u" in
+    *://*) : ;;
+    *) die "invalid console origin '$_u': expected a URL with a scheme, e.g. http://localhost:8080 (set NANO_INSTALL_CONSOLE_ORIGIN or NANOBPMN_BASE_URL accordingly)." ;;
+  esac
+  _scheme=${_u%%://*}
+  _rest=${_u#*://}
+  _auth=${_rest%%/*}
+  printf '%s://%s' "$_scheme" "$_auth"
+}
+
+# True (exit 0) iff $1 contains a control character (newline, tab, CR, …). Such
+# characters cannot appear literally in a JSON string without full \uXXXX
+# escaping, so we reject them at the config gate (see build_config_body) rather
+# than emit invalid JSON that fails the console API opaquely.
+has_control_chars() { [ "$(printf '%s' "$1" | LC_ALL=C tr -cd '[:cntrl:]' | wc -c)" -ne 0 ]; }
+
+# Minimal JSON string escaper (backslash + double-quote). Control characters are
+# rejected up front by build_config_body via has_control_chars(), so the values
+# reaching here (URLs, ports, tokens) are already control-char-free.
+json_str() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'; }
+
+# Print the path of a freshly created, private (0600) temp file on stdout, or
+# return non-zero if none could be made. Prefers mktemp; when mktemp is absent
+# it falls back to a noclobber (set -C) create loop so a pre-existing path — a
+# symlink/clobber attack on a shared /tmp — can never be followed or reused, and
+# the file we read back is always the empty one we just created (never stale).
+mktemp_safe() {
+  _mt=$(mktemp 2>/dev/null) && { printf '%s' "$_mt"; return 0; }
+  _dir=${TMPDIR:-/tmp}; _n=0
+  while [ "$_n" -lt 20 ]; do
+    _cand="${_dir%/}/nwf-install.$$.${_n}.$(_rand)"
+    # `set -C` makes `>` fail if the target exists (regular file OR symlink), so
+    # the create is atomic and cannot clobber/follow an attacker-planted path.
+    if ( set -C; umask 077; : >"$_cand" ) 2>/dev/null; then
+      printf '%s' "$_cand"; return 0
+    fi
+    _n=$((_n + 1))
+  done
+  return 1
+}
+
+# Best-effort small random token for the mktemp fallback path (entropy only —
+# security rests on the noclobber create, not on this being unguessable; the
+# per-iteration counter in the candidate path guarantees uniqueness regardless).
+_rand() {
+  awk 'BEGIN{srand();printf "%d", rand()*1000000}' 2>/dev/null && return 0
+  date +%s 2>/dev/null || printf '%s' "$$"
+}
+
+# api METHOD PATH [BODY] [DISPLAY]
+#   Sets API_STATUS (HTTP code, "000" on transport failure), API_BODY, API_ERR
+#   (curl exit code, 0 on success). Under --dry-run nothing is sent: the call is
+#   printed (DISPLAY overrides BODY in the printout, e.g. to redact a token).
+api() {
+  _method=$1; _path=$2; _body=${3:-}; _display=${4:-}
+  _url="${CONSOLE_ORIGIN}${_path}"
+  if [ "$DRY_RUN" -eq 1 ]; then
+    _shown=${_display:-$_body}
+    if [ -n "$_shown" ]; then
+      printf '+ %s %s  %s\n' "$_method" "$_url" "$_shown" >&2
+    else
+      printf '+ %s %s\n' "$_method" "$_url" >&2
+    fi
+    API_STATUS='000'; API_BODY=''; API_ERR=0
+    return 0
+  fi
+  # Bound every request so a stalled endpoint (SYN/DNS/proxy hang) can't wedge
+  # the otherwise-bounded phase-2 poll loop: --connect-timeout caps the connect
+  # phase, --max-time caps the whole request. A timeout surfaces as a non-zero
+  # curl exit (API_ERR) → API_STATUS='000', handled like any transport failure.
+  _tmp=$(mktemp_safe) || { API_STATUS='000'; API_BODY=''; API_ERR=1; return 0; }
+  # Assemble curl's argument list with `set --` inside a SUBSHELL so it stays
+  # local to that subshell and never touches the script's own positional
+  # parameters ($1, $2, …) — keeping api() free of any $@ side effect. (POSIX
+  # already saves/restores positionals across a function call, but scoping the
+  # `set --` here makes that independent of shell quirks and future edits.)
+  API_STATUS=$(
+    set -- -sS --connect-timeout 10 --max-time 30 -X "$_method" -H 'Accept: application/json'
+    if [ -n "$_body" ]; then
+      set -- "$@" -H 'Content-Type: application/json' --data "$_body"
+    fi
+    curl "$@" -o "$_tmp" -w '%{http_code}' "$_url" 2>/dev/null
+  ) && API_ERR=0 || API_ERR=$?
+  [ "$API_ERR" -ne 0 ] && API_STATUS='000'
+  API_BODY=$(cat "$_tmp" 2>/dev/null || true)
+  rm -f "$_tmp"
+  return 0
+}
+
+# Human-readable outcome of the last api() call, for a user-facing error. On a
+# transport failure api() forces API_STATUS='000' (curl couldn't complete the
+# request — DNS/connect/timeout), which as a bare "HTTP 000" is meaningless and
+# hides the real cause; describe it as a transport failure (with curl's exit
+# code) instead. Otherwise report the actual HTTP status. One source so every
+# phase-2 console call site renders 000 the same way (no drift).
+api_outcome() {
+  if [ "$API_STATUS" = '000' ]; then
+    printf 'transport failure (curl exit %s) — could not reach %s' "$API_ERR" "$CONSOLE_ORIGIN"
+  else
+    printf 'HTTP %s' "$API_STATUS"
+  fi
+}
+
+# The env map written into ProjectConfig.env (step 5). Real body + a token-
+# redacted display are built the same way so they never drift.
+build_config_body() { # $1 = redact? ("redact" to mask the token)
+  _tok="${GITHUB_TOKEN:-${GH_TOKEN:-}}"
+  # json_str() only escapes \ and " — it does NOT escape control characters — so
+  # a stray newline/tab (from a mis-set env var or trailing whitespace) in ANY
+  # interpolated value would corrupt the JSON body and fail the console API
+  # opaquely. The config gate, not the escaper, is the single place that rejects
+  # them, so validate every value that flows into the body, not just the token.
+  for _cc in "GITHUB_TOKEN/GH_TOKEN=$_tok" \
+             "NANOBPMN_BASE_URL=$CONSOLE_ORIGIN" \
+             "NANO_WORKFORCE_BASE_URL=$APPVIEW_BASE" \
+             "PR_REVIEW_PORT=${PR_REVIEW_PORT:-3000}"; do
+    if has_control_chars "${_cc#*=}"; then
+      err "${_cc%%=*} contains control characters (e.g. a stray newline or tab); refusing to build an invalid JSON config body — check the value for trailing whitespace."
+      return 1
+    fi
+  done
+  if [ -n "$_tok" ]; then
+    if [ "${1:-}" = redact ]; then _tokval='***'; else _tokval=$(json_str "$_tok"); fi
+    _gh="\"GITHUB_TOKEN\":\"${_tokval}\""
+  else
+    # No token in the environment: rely on the host `gh` CLI transport instead.
+    _gh="\"NANO_PR_GITHUB_TRANSPORT\":\"auto\""
+  fi
+  printf '{"env":{%s,"NANOBPMN_BASE_URL":"%s","NANO_WORKFORCE_BASE_URL":"%s","PR_REVIEW_PORT":"%s"}}' \
+    "$_gh" "$(json_str "$CONSOLE_ORIGIN")" "$(json_str "$APPVIEW_BASE")" "$(json_str "${PR_REVIEW_PORT:-3000}")"
+}
+
+# Step 9 — the console must be reachable before we mutate anything.
+app_preflight() {
+  info "Preflighting the console at ${CONSOLE_ORIGIN}/console"
+  api GET /console/api/projects
+  if [ "$DRY_RUN" -eq 1 ]; then
+    note "dry-run: assuming the console is reachable."
+    return 0
+  fi
+  if [ "$API_ERR" -ne 0 ] || [ "$API_STATUS" = '000' ]; then
+    err "console unreachable at ${CONSOLE_ORIGIN}/console/api (curl exit ${API_ERR})."
+    note "The engine was likely started with NANOBPMN_CONSOLE=off/observe."
+    note "'c8 nano start' defaults to 'studio' (console on) — check your engine config."
+    note "Nothing was changed; phase 1 (engine + workforce) is intact."
+    record_failure "app: console unreachable — no changes made"
+    return 1
+  fi
+  case "$API_STATUS" in
+    2*) ok "console reachable" ;;
+    *) err "console preflight GET /console/api/projects -> HTTP $API_STATUS"
+       record_failure "app: console preflight HTTP $API_STATUS"
+       return 1 ;;
+  esac
+}
+
+# Step 10 — confirm (keys, never values).
+confirm_app() {
+  info "About to install the Nano Workforce app"
+  note "console extension : @nanobpm/nano-workforce"
+  note "project           : ${PROJECT} (from template 'nano-workforce')"
+  if [ -n "${GITHUB_TOKEN:-${GH_TOKEN:-}}" ]; then _ghkey='GITHUB_TOKEN'; else _ghkey='NANO_PR_GITHUB_TRANSPORT'; fi
+  note "env keys written  : ${_ghkey}, NANOBPMN_BASE_URL, NANO_WORKFORCE_BASE_URL, PR_REVIEW_PORT (values not shown)"
+  if [ -z "${GITHUB_TOKEN:-${GH_TOKEN:-}}" ]; then
+    note "no token in env   : the app relies on the host gh CLI (NANO_PR_GITHUB_TRANSPORT=auto)."
+  fi
+  note "app-view URL      : ${APPVIEW_BASE}/"
+  if [ "$ASSUME_YES" -eq 1 ] || [ "$DRY_RUN" -eq 1 ]; then
+    [ "$DRY_RUN" -eq 1 ] && note "dry-run: not asking for confirmation."
+    return 0
+  fi
+  if [ -z "$TTY" ]; then
+    die "refusing to install the app without confirmation and no /dev/tty — re-run with --yes."
+  fi
+  if confirm "Install and run the Nano Workforce app now?"; then
+    return 0
+  fi
+  note "skipping app install at user request (phase 1 is up and usable)."
+  SKIP_APP=1   # keep report_and_exit honest: the app was explicitly skipped
+  return 1
+}
+
+# Steps 11.1–11.6 — install extension, scaffold, configure, run.
+app_provision() {
+  # 11.1 — ensure the Urban toolkit (idempotent no-op when urban resolves).
+  # Do NOT gate on urbanAvailable: a live instance can report false while a
+  # Workforce project runs happily — treat the response as informational.
+  info "Installing the Urban toolkit"
+  api POST /console/api/urban/install
+  if [ "$DRY_RUN" -eq 0 ]; then
+    case "$API_STATUS" in
+      2*) ok "urban toolkit ensured" ;;
+      *) warn "urban install returned $(api_outcome) (informational — continuing)" ;;
+    esac
+  fi
+
+  # 11.2 — install the console extension. Idempotent: an existing extension is
+  # upgraded (2xx) or already present (409/2xx) — either way, continue.
+  info "Installing the @nanobpm/nano-workforce console extension"
+  api POST /console/api/extensions/install '{"pkg":"@nanobpm/nano-workforce"}'
+  if [ "$DRY_RUN" -eq 0 ]; then
+    case "$API_STATUS" in
+      2*)  ok "extension installed/upgraded" ;;
+      409) note "extension already installed — continuing." ;;
+      *)   err "extension install -> $(api_outcome)"
+           [ -n "$API_BODY" ] && note "$API_BODY"
+           record_failure "app: extension install $(api_outcome)"
+           return 1 ;;
+    esac
+  fi
+
+  # 11.3 — confirm the pack contributed template id 'nano-workforce'. NB the
+  # templates come from GET /console/api/projects, NOT GET /console/api/config/ide
+  # (which returns {} live); the npm pkg name is not the template id.
+  info "Confirming the 'nano-workforce' template is available"
+  api GET /console/api/projects
+  if [ "$DRY_RUN" -eq 1 ]; then
+    note "dry-run: would confirm template 'nano-workforce' in the projects listing."
+  else
+    case "$API_STATUS" in
+      2*) : ;;
+      *)  err "listing projects/templates -> $(api_outcome)"
+          record_failure "app: list projects $(api_outcome)"
+          return 1 ;;
+    esac
+    if printf '%s' "$API_BODY" | grep -Eq '"id"[[:space:]]*:[[:space:]]*"nano-workforce"'; then
+      ok "template 'nano-workforce' present"
+    else
+      err "the extension did not contribute template 'nano-workforce'."
+      note "Install may be mid-flight; re-run, or check the console extensions list."
+      record_failure "app: template 'nano-workforce' missing after extension install"
+      return 1
+    fi
+  fi
+
+  # 11.4 — scaffold the project. 409 => it already exists: DO NOT re-scaffold
+  # (app.db lives in the project); fall through to configure + run.
+  info "Scaffolding project '$PROJECT' from template 'nano-workforce'"
+  _create_body=$(printf '{"name":"%s","template":"nano-workforce"}' "$(json_str "$PROJECT")")
+  api POST /console/api/projects "$_create_body"
+  if [ "$DRY_RUN" -eq 1 ]; then
+    note "dry-run: on 409 (project exists) we skip scaffolding and continue to configure + run."
+  else
+    case "$API_STATUS" in
+      2*)  ok "project '$PROJECT' created" ;;
+      409) note "project '$PROJECT' already exists — configuring and running it (not re-scaffolding)." ;;
+      *)   err "createProject -> $(api_outcome)"
+           [ -n "$API_BODY" ] && note "$API_BODY"
+           record_failure "app: createProject $(api_outcome)"
+           return 1 ;;
+    esac
+  fi
 
-  Note: the Nano Workforce APP itself is not installed by this script yet — this
-  brings up the engine + a workforce of hired agents. See the README's "Run from
-  the CLI" section for installing/running the app.
+  # 11.5 — write ProjectConfig.env (token redacted in dry-run output).
+  info "Configuring project '$PROJECT' (ProjectConfig.env)"
+  _cfg_body=$(build_config_body) || {
+    record_failure "app: invalid ProjectConfig.env value (control characters)"
+    return 1
+  }
+  _cfg_show=$(build_config_body redact) || {
+    record_failure "app: invalid ProjectConfig.env value (control characters)"
+    return 1
+  }
+  api PUT "/console/api/projects/${PROJECT}/config" "$_cfg_body" "$_cfg_show"
+  if [ "$DRY_RUN" -eq 0 ]; then
+    case "$API_STATUS" in
+      2*) ok "config written (NANO_WORKFORCE_BASE_URL=${APPVIEW_BASE})" ;;
+      *)  err "PUT project config -> $(api_outcome)"
+          [ -n "$API_BODY" ] && note "$API_BODY"
+          record_failure "app: PUT config $(api_outcome)"
+          return 1 ;;
+    esac
+  fi
+
+  # 11.6 — run. Running an already-running project is a no-op that returns its
+  # current RunState, so this is safe to re-run (converges, never force-restarts).
+  info "Running project '$PROJECT'"
+  api POST "/console/api/projects/${PROJECT}/run"
+  if [ "$DRY_RUN" -eq 0 ]; then
+    case "$API_STATUS" in
+      2*) ok "run requested" ;;
+      *)  err "runProject -> $(api_outcome)"
+          [ -n "$API_BODY" ] && note "$API_BODY"
+          record_failure "app: runProject $(api_outcome)"
+          return 1 ;;
+    esac
+  fi
+}
+
+# Step 12 — assert readiness by polling the app's OWN /app/api/version through
+# the proxy. The runProject response reports the supervisor's state, not the
+# app's readiness, so never trust it alone.
+app_verify() {
+  info "Waiting for the app to answer /app/api/version"
+  if [ "$DRY_RUN" -eq 1 ]; then
+    note "dry-run: would poll GET ${APPVIEW_BASE}/app/api/version until HTTP 200."
+    return 0
+  fi
+  # APP_POLL_ATTEMPTS/APP_POLL_INTERVAL come from env hooks and feed `test`
+  # arithmetic + `sleep`. A non-integer value would make `set -e` abort with an
+  # opaque shell error mid-loop; validate them as non-negative integers up front
+  # and record a clear failure instead.
+  case "$APP_POLL_ATTEMPTS" in
+    ''|*[!0-9]*) record_failure "app: NANO_INSTALL_APP_POLL_ATTEMPTS must be a non-negative integer (got '${APP_POLL_ATTEMPTS}')"; return 1 ;;
+  esac
+  case "$APP_POLL_INTERVAL" in
+    ''|*[!0-9]*) record_failure "app: NANO_INSTALL_APP_POLL_INTERVAL must be a non-negative integer (got '${APP_POLL_INTERVAL}')"; return 1 ;;
+  esac
+  _n=0
+  while [ "$_n" -lt "$APP_POLL_ATTEMPTS" ]; do
+    api GET "/console/app-view/${PROJECT}/app/api/version"
+    case "$API_STATUS" in
+      2*) ok "app is up ($(printf '%s' "$API_BODY" | tr -d '[:space:]' | cut -c1-80))"; return 0 ;;
+    esac
+    _n=$((_n + 1))
+    [ "$_n" -lt "$APP_POLL_ATTEMPTS" ] && sleep "$APP_POLL_INTERVAL"
+  done
+  err "the app did not answer 200 on /app/api/version within $((APP_POLL_ATTEMPTS * APP_POLL_INTERVAL))s (last HTTP ${API_STATUS})."
+  note "It may have booted but not finished self-healing its Urban surface (deps + codegen)."
+  note "Verify your nano-bpm build carries the self-heal-on-Run fix (Magikcraft/nano-bpm#1036); check: ${APPVIEW_BASE}/app/api/version"
+  record_failure "app: readiness poll timed out (last HTTP ${API_STATUS})"
+  return 1
+}
+
+# Step 13 — the operator surfaces.
+app_surfaces() {
+  if [ "$DRY_RUN" -eq 1 ]; then
+    info "dry-run: no calls were made — the following surfaces would be available once installed:"
+  else
+    info "Nano Workforce is up"
+  fi
+  cat >&2 <<EOF
+  App (cockpit)   : ${APPVIEW_BASE}/
+  Tasks inbox     : ${APPVIEW_BASE}/tasks
+  Delivery Graphs : ${APPVIEW_BASE}/delivery-graphs
+  Agent guide     : ${APPVIEW_BASE}/app/api/agent
+  MCP endpoint    : ${APPVIEW_BASE}/app/mcp
+
+  Drive it by pointing a coding agent at the agent guide (GET /app/api/agent),
+  or add the instance's /app/mcp as an MCP server, e.g.:
+    copilot mcp add --transport http workforce ${APPVIEW_BASE}/app/mcp
 EOF
 }
 
+# Phase 2 entrypoint. Returns non-zero on a genuine failure (recorded) so the
+# final report exits non-zero; a benign user decline returns 1 WITHOUT recording.
+install_app() {
+  info "Phase 2 — install & run the Nano Workforce app (nanobpm/nano-workforce#583)"
+
+  PROJECT=${PROJECT_NAME:-Workforce}
+  case "$PROJECT" in
+    ''|*[!ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0-9._-]*) die "invalid --project-name '$PROJECT': only [A-Za-z0-9._-] are allowed." ;;
+  esac
+  CONSOLE_ORIGIN=$(origin_of "${NANO_INSTALL_CONSOLE_ORIGIN:-${NANOBPMN_BASE_URL:-http://localhost:8080}}")
+  APPVIEW_BASE="${CONSOLE_ORIGIN}/console/app-view/${PROJECT}"
+
+  if [ "$DRY_RUN" -eq 0 ] && ! command -v curl >/dev/null 2>&1; then
+    err "curl not found — phase 2 needs curl to talk to the console API."
+    note "Install curl and re-run (phase 1 is up and usable), or use --skip-app."
+    record_failure "app: curl missing — phase 2 skipped"
+    return 1
+  fi
+
+  app_preflight  || return 1
+  confirm_app    || return 1
+  app_provision  || return 1
+  app_verify     || return 1
+  app_surfaces
+}
+
 # ---------------------------------------------------------------------------
 # Partial-success report
 # ---------------------------------------------------------------------------
 report_and_exit() {
+  # A degraded GitHub-access install must never *look* complete — repeat the
+  # warning here and exit non-zero so the failure is visible, not deferred.
+  if [ -n "$GITHUB_DEGRADED" ] && [ "$DRY_RUN" -eq 0 ]; then
+    record_failure "GitHub/git preflight degraded (this host only): ${GITHUB_DEGRADED} — the workforce cannot review, push, or merge until it is fixed"
+  fi
   if [ -n "$FAILURES" ]; then
     warn "Completed with some steps skipped or failed:"
     printf '%s\n' "$FAILURES" | sed '/^$/d' | while IFS= read -r _f; do note "- $_f"; done
     exit 1
   fi
-  ok "Done — engine up, workforce of hired agents up."
+  if [ "$SKIP_APP" -eq 1 ]; then
+    if [ "$DRY_RUN" -eq 1 ]; then
+      ok "Dry-run complete — no changes were made (app install skipped via --skip-app)."
+    else
+      ok "Done — engine up, workforce of hired agents up (app install skipped)."
+    fi
+  else
+    if [ "$DRY_RUN" -eq 1 ]; then
+      ok "Dry-run complete — no changes were made; the above is what would run."
+    else
+      ok "Done — engine + workforce up, and the Nano Workforce app is running."
+    fi
+  fi
   exit 0
 }
 
@@ -776,7 +1423,23 @@ main() {
   compose_workforce
   bring_up || true
   print_status_and_hints
+  if [ "$SKIP_APP" -eq 1 ]; then
+    info "Phase 2 skipped (--skip-app)"
+    note "The Nano Workforce app was NOT installed — re-run without --skip-app to"
+    note "install the console extension, scaffold + configure + run the app."
+  else
+    install_app || true
+  fi
   report_and_exit
 }
 
+# Undocumented test hook: exercise phase 2 in isolation against a stub console
+# (no CLI install, no engine), used by the hermetic readiness/convergence tests.
+if [ "${NANO_INSTALL_TEST_PHASE2_ONLY:-0}" = 1 ]; then
+  parse_args "$@"
+  init_tty
+  install_app || true
+  report_and_exit
+fi
+
 main "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.152.0",
+  "version": "0.154.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/test/install-smoke.sh

@@ -7,6 +7,11 @@
 # NANO_INSTALL_ADAPTERS_PRESENT. Only `node` and `npm` are required (the
 # preflight probe still runs), so run it where both are available.
 #
+# The phase-2 (app install, nano-workforce#583) scenarios also drive the real
+# curl-backed console flow against an in-process node stub console via the
+# NANO_INSTALL_TEST_PHASE2_ONLY hook — those need `node` + `curl`, and are
+# skipped (still PASS) if either is missing.
+#
 # Run from the repo root:  sh test/install-smoke.sh
 set -eu
 
@@ -94,6 +99,347 @@ assert_contains "s5: later selection defaults to 1 instance" \
 assert_contains "s5: default model => bare adapter command, empty --model" \
   "--command 'claude-code-acp' --model ''" "$OUT"
 
+# ===========================================================================
+# GitHub credential preflight — three-state check (nano-workforce#588)
+# ===========================================================================
+# The probe is stubbed hermetically via NANO_INSTALL_GH_STATE / NANO_INSTALL_GH_SCOPES
+# / NANO_INSTALL_GIT_STATE so no real gh/git auth is needed. All run under
+# --dry-run (never blocks) unless a scenario specifically exercises the
+# non-interactive fail path.
+
+# --- Scenario G1: token in env is usable, gh absent → app-fine caveat -------
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="missing" \
+  NANO_INSTALL_TOKEN_STATE="ok" GITHUB_TOKEN="fake-usable-token" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run 2>&1)
+assert_contains "sG1: token detected treated as usable" \
+  "GitHub token detected in the environment" "$OUT"
+assert_contains "sG1: token+no-gh caveat about harnesses shelling out to gh" \
+  "harnesses that shell out to 'gh' still won't work" "$OUT"
+
+# --- Scenario G1b: a set-but-invalid token FAILS validation (not trusted) ---
+# A non-empty token is not trusted blindly: an expired/revoked/underscoped
+# token is the exact late failure this preflight exists to surface early.
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="missing" \
+  NANO_INSTALL_TOKEN_STATE="bad" GITHUB_TOKEN="fake-invalid-token" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run 2>&1)
+assert_contains "sG1b: invalid token reported as failing validation" \
+  "failed validation" "$OUT"
+assert_contains "sG1b: invalid token names remediation (fix or unset)" \
+  "expired, revoked, or lacks access" "$OUT"
+
+# --- Scenario G2: gh missing, no token → not-detected + platform hint -------
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="missing" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run 2>&1)
+assert_contains "sG2: no gh + no token reported" \
+  "no gh CLI and no GITHUB_TOKEN/GH_TOKEN" "$OUT"
+assert_contains "sG2: not-detected headline" \
+  "GitHub access not detected" "$OUT"
+assert_contains "sG2: Debian/Ubuntu install hint" "sudo apt install gh" "$OUT"
+assert_contains "sG2: macOS install hint" "brew install gh" "$OUT"
+assert_contains "sG2: gh auth login remediation printed" "gh auth login" "$OUT"
+assert_contains "sG2: this-host-only caveat" "covers THIS host only" "$OUT"
+# The script must NEVER run gh auth login itself — only print it.
+assert_not_contains "sG2: never runs gh auth login (no 'Running' style exec)" \
+  "would run: gh auth login" "$OUT"
+
+# --- Scenario G3: gh present but unauthenticated ---------------------------
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="unauthed" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run 2>&1)
+assert_contains "sG3: installed-but-unauthenticated state" \
+  "gh is installed but not authenticated" "$OUT"
+
+# --- Scenario G4: gh authenticated but unusable (gh api user fails) ---------
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="unusable" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run 2>&1)
+assert_contains "sG4: authenticated-but-unusable state (gh api user failed)" \
+  "'gh api user' failed" "$OUT"
+assert_contains "sG4: names SAML SSO as a likely cause" "SAML SSO" "$OUT"
+
+# --- Scenario G5: authenticated + usable, missing repo scope FAILS ----------
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="ok" \
+  NANO_INSTALL_GH_SCOPES="gist,read:org" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run 2>&1)
+assert_contains "sG5: missing repo scope fails the check" \
+  "missing the 'repo' scope" "$OUT"
+
+# --- Scenario G6: usable with repo but missing workflow scope only WARNS ----
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="ok" \
+  NANO_INSTALL_GH_SCOPES="repo,read:org" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run 2>&1)
+assert_contains "sG6: missing workflow scope warns (non-fatal)" \
+  "missing the 'workflow' scope" "$OUT"
+assert_contains "sG6: repo+ passes the check" "GitHub access OK via the host gh CLI" "$OUT"
+
+# --- Scenario G7: git absence is flagged -----------------------------------
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="ok" \
+  NANO_INSTALL_GH_SCOPES="repo,workflow" NANO_INSTALL_GIT_STATE="missing" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run 2>&1)
+assert_contains "sG7: git presence checked alongside gh" \
+  "git not found on this host" "$OUT"
+
+# --- Scenario G8: non-interactive (--yes) FAILS without --allow-no-github ----
+if NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="missing" \
+     sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes >/dev/null 2>&1; then
+  fail "sG8: non-interactive run with no GitHub access should exit non-zero"
+else
+  pass "sG8: non-interactive run with no GitHub access exits non-zero"
+fi
+
+# --- Scenario G9: --allow-no-github lets a non-interactive run proceed -------
+# Under --dry-run this exercises the --allow-no-github *continue* decision (the
+# preflight records GITHUB_DEGRADED and breaks instead of dying). The final
+# summary's degraded-failure line is intentionally NOT emitted here: dry-run
+# makes no changes, so report_and_exit() only records the degraded failure when
+# DRY_RUN=0 — that real-run summary path is a deliberate no-op under --dry-run.
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="missing" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run --allow-no-github 2>&1)
+assert_contains "sG9: --allow-no-github continues" \
+  "continuing without GitHub access" "$OUT"
+
+# --- Scenario G9b: git-missing AND github-missing both surface (no masking) --
+# The GitHub-degraded reason must ACCUMULATE onto the earlier git-missing one,
+# not overwrite it — so a host lacking both never loses the git problem behind
+# the GitHub message. Both warnings must appear in the same run.
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="missing" \
+  NANO_INSTALL_GIT_STATE="missing" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run --allow-no-github 2>&1)
+assert_contains "sG9b: git-missing warning still shown alongside github" \
+  "git not found on this host" "$OUT"
+assert_contains "sG9b: github-missing continue also shown" \
+  "continuing without GitHub access" "$OUT"
+
+# ===========================================================================
+# Phase 2 — install & run the Nano Workforce app (nano-workforce#583)
+# ===========================================================================
+
+# --- Scenario 6: phase-2 dry-run emits the full console call sequence -------
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run 2>&1)
+assert_contains "s6: urban toolkit install" \
+  "POST http://localhost:8080/console/api/urban/install" "$OUT"
+assert_contains "s6: extension install with pkg" \
+  'POST http://localhost:8080/console/api/extensions/install  {"pkg":"@nanobpm/nano-workforce"}' "$OUT"
+assert_contains "s6: GET projects to confirm the template" \
+  "GET http://localhost:8080/console/api/projects" "$OUT"
+assert_contains "s6: create project from template nano-workforce" \
+  '{"name":"Workforce","template":"nano-workforce"}' "$OUT"
+assert_contains "s6: 409-exists convergence branch documented" \
+  "on 409 (project exists) we skip scaffolding" "$OUT"
+assert_contains "s6: NANO_WORKFORCE_BASE_URL is console origin + app-view prefix" \
+  '"NANO_WORKFORCE_BASE_URL":"http://localhost:8080/console/app-view/Workforce"' "$OUT"
+assert_contains "s6: NANOBPMN_BASE_URL written" \
+  '"NANOBPMN_BASE_URL":"http://localhost:8080"' "$OUT"
+assert_contains "s6: PR_REVIEW_PORT written" '"PR_REVIEW_PORT":"3000"' "$OUT"
+assert_contains "s6: run the project" \
+  "POST http://localhost:8080/console/api/projects/Workforce/run" "$OUT"
+assert_contains "s6: readiness poll of the app's own /app/api/version" \
+  "poll GET http://localhost:8080/console/app-view/Workforce/app/api/version" "$OUT"
+assert_contains "s6: surface app-view URL" \
+  "http://localhost:8080/console/app-view/Workforce/" "$OUT"
+assert_contains "s6: surface Tasks inbox" \
+  "http://localhost:8080/console/app-view/Workforce/tasks" "$OUT"
+assert_contains "s6: surface Delivery Graphs" \
+  "http://localhost:8080/console/app-view/Workforce/delivery-graphs" "$OUT"
+assert_contains "s6: surface agent guide" \
+  "http://localhost:8080/console/app-view/Workforce/app/api/agent" "$OUT"
+assert_contains "s6: surface MCP endpoint" \
+  "http://localhost:8080/console/app-view/Workforce/app/mcp" "$OUT"
+# Dry-run must not assert readiness: it changed nothing, so it must not claim the
+# app "is up" / "is running" — it states the surfaces are what *would* be available.
+assert_not_contains "s6: dry-run does not falsely claim the app is up" \
+  "Nano Workforce is up" "$OUT"
+assert_not_contains "s6: dry-run does not falsely claim the app is running" \
+  "the Nano Workforce app is running" "$OUT"
+assert_contains "s6: dry-run frames surfaces as would-be-available" \
+  "would be available" "$OUT"
+assert_contains "s6: dry-run final report states no changes were made" \
+  "Dry-run complete — no changes were made" "$OUT"
+
+# --- Scenario 6b: --project-name flows through every URL and body ----------
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run --project-name Fleet 2>&1)
+assert_contains "s6b: project name in the create body" \
+  '{"name":"Fleet","template":"nano-workforce"}' "$OUT"
+assert_contains "s6b: project name in the app-view base" \
+  '"NANO_WORKFORCE_BASE_URL":"http://localhost:8080/console/app-view/Fleet"' "$OUT"
+assert_contains "s6b: project name in the run URL" \
+  "POST http://localhost:8080/console/api/projects/Fleet/run" "$OUT"
+
+# --- Scenario 6c: GITHUB_TOKEN is redacted in dry-run, never printed --------
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" GITHUB_TOKEN="SHOULD-NOT-APPEAR-TOKEN" \
+  NANO_INSTALL_TOKEN_STATE="ok" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run 2>&1)
+assert_contains "s6c: token key present, masked" '"GITHUB_TOKEN":"***"' "$OUT"
+assert_not_contains "s6c: token value never printed" "SHOULD-NOT-APPEAR-TOKEN" "$OUT"
+
+# --- Scenario 7: --skip-app runs phase 1 only, emits no console calls -------
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run --skip-app 2>&1)
+assert_not_contains "s7: no console API calls under --skip-app" "/console/api/" "$OUT"
+assert_contains "s7: skip note shown" "Phase 2 skipped (--skip-app)" "$OUT"
+assert_contains "s7: dry-run + skip-app report states no changes were made" \
+  "Dry-run complete — no changes were made" "$OUT"
+
+# --- Scenarios 8-15: live phase-2 flow against a stubbed node console -------
+if command -v node >/dev/null 2>&1 && command -v curl >/dev/null 2>&1; then
+  STUBDIR=$(mktemp -d "${TMPDIR:-/tmp}/nwf-smoke.XXXXXX")
+  STUB="$STUBDIR/stub-console.cjs"
+  # The repo's package.json sets "type":"module", so the CommonJS stub must be
+  # a .cjs file. It answers just enough of the console API to exercise the flow.
+  cat > "$STUB" <<'CJS'
+const http = require('http');
+const mode = process.env.STUB_MODE || 'happy'; // happy | exists | timeout
+let ran = false;
+const srv = http.createServer((req, res) => {
+  const url = req.url, m = req.method;
+  const json = (c, o) => { res.writeHead(c, { 'content-type': 'application/json' }); res.end(JSON.stringify(o)); };
+  req.on('data', () => {}); req.on('end', () => {
+    if (m === 'GET' && url === '/console/api/projects') {
+      const projects = mode === 'exists' ? [{ name: 'Workforce', template: 'nano-workforce' }] : [];
+      return json(200, { templates: [{ id: 'nano-workforce', pack: 'nano-workforce' }], projects });
+    }
+    if (m === 'POST' && url === '/console/api/urban/install') return json(200, { urbanAvailable: false });
+    if (m === 'POST' && url === '/console/api/extensions/install') return json(201, { id: 'nano-workforce' });
+    if (m === 'POST' && url === '/console/api/projects') return mode === 'exists' ? json(409, { error: 'exists' }) : json(201, { name: 'Workforce' });
+    if (m === 'PUT' && url === '/console/api/projects/Workforce/config') return json(200, { ok: true });
+    if (m === 'POST' && url === '/console/api/projects/Workforce/run') { ran = true; return json(200, { state: 'running' }); }
+    if (m === 'GET' && url === '/console/app-view/Workforce/app/api/version') {
+      if (mode === 'timeout') return json(404, {});
+      return ran ? json(200, { version: '9.9.9' }) : json(404, {});
+    }
+    return json(404, { error: 'nomatch', url });
+  });
+});
+srv.listen(0, '127.0.0.1', () => console.log('PORT ' + srv.address().port));
+setTimeout(() => process.exit(0), 30000); // self-terminate: never leak the stub
+CJS
+
+  # run_phase2 <mode> [extra install.sh args...] -> sets PHASE2_RC, PHASE2_OUT
+  run_phase2() {
+    _mode=$1; shift
+    STUB_MODE="$_mode" node "$STUB" > "$STUBDIR/$_mode.log" 2>&1 &
+    _pid=$!
+    _port=''; _i=0
+    while [ "$_i" -lt 50 ]; do
+      _port=$(sed -n 's/^PORT //p' "$STUBDIR/$_mode.log" 2>/dev/null)
+      [ -n "$_port" ] && break
+      _i=$((_i + 1)); sleep 1
+    done
+    if [ -z "$_port" ]; then
+      kill "$_pid" 2>/dev/null || true
+      wait "$_pid" 2>/dev/null || true
+      PHASE2_OUT="stub console never reported a port for mode '$_mode'"; PHASE2_RC=127
+      return 0
+    fi
+    set +e
+    PHASE2_OUT=$(NANO_INSTALL_TEST_PHASE2_ONLY=1 \
+      NANO_INSTALL_CONSOLE_ORIGIN="http://127.0.0.1:$_port" \
+      NANO_INSTALL_APP_POLL_ATTEMPTS=3 NANO_INSTALL_APP_POLL_INTERVAL=0 \
+      sh "$SCRIPT" --yes "$@" 2>&1)
+    PHASE2_RC=$?
+    set -e
+    kill "$_pid" 2>/dev/null || true
+    wait "$_pid" 2>/dev/null || true
+  }
+
+  if [ -z "$STUBDIR" ] || [ ! -f "$STUB" ]; then
+    fail "s8-s15: could not create the stub console"
+  else
+    # Scenario 8 — happy path: success asserted via /app/api/version, exit 0.
+    run_phase2 happy
+    if [ "$PHASE2_RC" -eq 0 ]; then pass "s8: happy path exits zero"; else
+      fail "s8: happy path should exit zero"; printf '%s\n' "$PHASE2_OUT" | sed 's/^/    | /' >&2; fi
+    assert_contains "s8: readiness asserted via /app/api/version" "app is up" "$PHASE2_OUT"
+    assert_contains "s8: project created (not 409)" "project 'Workforce' created" "$PHASE2_OUT"
+
+    # Scenario 9 — existing project (409): configure + run, never re-scaffold.
+    run_phase2 exists
+    if [ "$PHASE2_RC" -eq 0 ]; then pass "s9: 409-exists converges (exit zero)"; else
+      fail "s9: 409-exists path should exit zero"; printf '%s\n' "$PHASE2_OUT" | sed 's/^/    | /' >&2; fi
+    assert_contains "s9: existing project configured+run, not re-scaffolded" \
+      "already exists — configuring and running it (not re-scaffolding)" "$PHASE2_OUT"
+
+    # Scenario 10 — readiness poll timeout: clear message, exit non-zero.
+    run_phase2 timeout
+    if [ "$PHASE2_RC" -ne 0 ]; then pass "s10: readiness timeout exits non-zero"; else
+      fail "s10: readiness timeout should exit non-zero"; fi
+    assert_contains "s10: timeout is a clear readiness message" \
+      "did not answer 200 on /app/api/version" "$PHASE2_OUT"
+    assert_contains "s10: timeout names the self-heal-on-Run dependency" \
+      "self-heal-on-Run" "$PHASE2_OUT"
+
+    # Scenario 11 — console off/unreachable: early failure that mutates nothing.
+    set +e
+    OFF=$(NANO_INSTALL_TEST_PHASE2_ONLY=1 NANO_INSTALL_CONSOLE_ORIGIN="http://127.0.0.1:1" \
+      sh "$SCRIPT" --yes 2>&1)
+    OFFRC=$?
+    set -e
+    if [ "$OFFRC" -ne 0 ]; then pass "s11: console-off exits non-zero"; else
+      fail "s11: console-off should exit non-zero"; fi
+    assert_contains "s11: console-off is a clear message" "console unreachable" "$OFF"
+    assert_not_contains "s11: console-off mutates nothing (no extension install)" \
+      "extensions/install" "$OFF"
+
+    # Scenario 12 — schemeless console origin: fail early with a clear message,
+    # never emit the "localhost:8080://localhost:8080"-style invalid origin.
+    set +e
+    SCHEMELESS=$(NANO_INSTALL_TEST_PHASE2_ONLY=1 NANO_INSTALL_CONSOLE_ORIGIN="localhost:8080" \
+      sh "$SCRIPT" --yes 2>&1)
+    SCHEMELESSRC=$?
+    set -e
+    if [ "$SCHEMELESSRC" -ne 0 ]; then pass "s12: schemeless origin exits non-zero"; else
+      fail "s12: schemeless origin should exit non-zero"; fi
+    assert_contains "s12: schemeless origin is a clear message" \
+      "expected a URL with a scheme" "$SCHEMELESS"
+    assert_not_contains "s12: schemeless origin never doubles the authority" \
+      "localhost:8080://localhost:8080" "$SCHEMELESS"
+
+    # Scenario 13 — mktemp unavailable: api() must fall back to a safe noclobber
+    # temp file and the happy path must still converge. A PATH-shim `mktemp` that
+    # always fails forces mktemp_safe() down its fallback branch for the script.
+    SHIMDIR="$STUBDIR/shim"
+    mkdir -p "$SHIMDIR"
+    printf '#!/bin/sh\nexit 1\n' > "$SHIMDIR/mktemp"
+    chmod +x "$SHIMDIR/mktemp"
+    _oldpath="$PATH"
+    PATH="$SHIMDIR:$PATH"; export PATH
+    run_phase2 happy
+    PATH="$_oldpath"; export PATH
+    if [ "$PHASE2_RC" -eq 0 ]; then pass "s13: mktemp-unavailable fallback converges (exit zero)"; else
+      fail "s13: mktemp-unavailable fallback should exit zero"; printf '%s\n' "$PHASE2_OUT" | sed 's/^/    | /' >&2; fi
+    assert_contains "s13: fallback still asserts readiness via /app/api/version" "app is up" "$PHASE2_OUT"
+
+    # Scenario 14 — a GITHUB_TOKEN carrying a control character (e.g. a stray
+    # newline) must be rejected with a clear error before any JSON config body
+    # is emitted, never producing invalid JSON that fails the console API
+    # opaquely. The token flows through json_str() unredacted on the live PUT.
+    _ctrl_token="$(printf 'fake-bad\ntoken')"
+    export GITHUB_TOKEN="$_ctrl_token"
+    run_phase2 happy
+    unset GITHUB_TOKEN
+    if [ "$PHASE2_RC" -ne 0 ]; then pass "s14: control-char token rejected (exit non-zero)"; else
+      fail "s14: control-char token should exit non-zero"; printf '%s\n' "$PHASE2_OUT" | sed 's/^/    | /' >&2; fi
+    assert_contains "s14: control-char token has a clear message" \
+      "control characters" "$PHASE2_OUT"
+
+    # Scenario 15 — the control-char gate covers EVERY interpolated config value,
+    # not just the token: a non-token field (here PR_REVIEW_PORT) carrying a
+    # control character must be rejected the same way, naming the offending key.
+    _ctrl_port="$(printf '3000\nbad')"
+    export PR_REVIEW_PORT="$_ctrl_port"
+    run_phase2 happy
+    unset PR_REVIEW_PORT
+    if [ "$PHASE2_RC" -ne 0 ]; then pass "s15: control-char non-token field rejected (exit non-zero)"; else
+      fail "s15: control-char non-token field should exit non-zero"; printf '%s\n' "$PHASE2_OUT" | sed 's/^/    | /' >&2; fi
+    assert_contains "s15: rejection names the offending field" \
+      "PR_REVIEW_PORT contains control characters" "$PHASE2_OUT"
+
+    rm -rf "$STUBDIR"
+  fi
+else
+  pass "s8-s15: skipped (node or curl unavailable for the stubbed-console tests)"
+fi
+
 if [ "$FAILED" -ne 0 ]; then
   printf '\nSMOKE TEST FAILED\n' >&2
   exit 1