@nanobpm/nano-workforce 0.152.0 → 0.153.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,9 @@
+## [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,56 @@ 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`).
+
+**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,8 @@ DRY_RUN=0
 ASSUME_YES=0
 SHELL_OVERRIDE=''
 INSTALL_ADAPTERS=0        # auto-install missing adapters without prompting
+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)
@@ -98,6 +100,23 @@ if [ "${NANO_INSTALL_ADAPTERS_PRESENT+set}" = set ]; then ADAPTERS_PRESENT_SET=1
 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 +219,11 @@ Options:
   -y, --yes          Skip the confirmation summary.
   --install-adapters Auto-install a selected harness's missing ACP adapter
                      (claude/pi) instead of prompting/skipping.
+  --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 +232,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 +261,11 @@ parse_args() {
         shift ;;
       --yes|-y) ASSUME_YES=1; shift ;;
       --install-adapters) INSTALL_ADAPTERS=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)"
@@ -438,7 +474,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,13 +761,388 @@ 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
+}
 
-  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.
+# 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)"
+  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
+
+  # 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
 # ---------------------------------------------------------------------------
@@ -741,7 +1152,19 @@ report_and_exit() {
     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 +1199,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.153.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,237 @@ 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"
 
+# ===========================================================================
+# 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="ghp_SHOULD_NOT_APPEAR" \
+  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" "ghp_SHOULD_NOT_APPEAR" "$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 'ghp_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