@rubytech/create-maxy-code 0.1.84 → 0.1.86

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.84",
+  "version": "0.1.86",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

package/payload/platform/config/brand.json

@@ -6,7 +6,7 @@
   "configDir": ".maxy-code",
   "tagline": "AI for Productive People",
   "strapline": "Convenience as standard.",
-  "domain": "getmaxy.com",
+  "marketingUrl": "https://getmaxy.com",
   "neo4jPort": 7687,
   "ttydPort": 7681,
   "vncDisplay": 99,

package/payload/platform/plugins/admin/hooks/__tests__/pre-tool-use-memory-write-passthrough.test.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# Task 225 — passthrough regression test for memory-write / memory-update
+# under the admin agent's pre-tool-use.sh.
+#
+# The Task 213→222 chain previously gated both writers at the top of the
+# admin branch with an exit-2 block (admin direct) and an exit-0 allow
+# (Task-subagent). Task 225 reversed the doctrine: admin holds the
+# writers in its own surface and the case-block was deleted. This test
+# pins the new behaviour so a future re-introduction of the block
+# cannot land silently.
+#
+# Five cases:
+#   1. mcp__plugin_memory_memory__memory-write     admin-direct → exit 0, no rejection stderr
+#   2. mcp__plugin_memory_memory__memory-update    admin-direct → exit 0, no rejection stderr
+#   3. mcp__plugin_memory_memory__memory-search    admin-direct → exit 0, no rejection stderr (read tool control)
+#   4. mcp__memory__memory-write                   admin-direct → exit 0 (pre-209 namespace, falls through harmlessly)
+#   5. malformed JSON stdin                                   → exit 0 (no crash; case-block removal does not break fall-through)
+
+set -u
+
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/pre-tool-use.sh"
+if [[ ! -x "$HOOK" ]]; then
+  echo "FAIL: $HOOK not executable" >&2
+  exit 1
+fi
+
+TMPFILES=()
+cleanup() {
+  for f in "${TMPFILES[@]:-}"; do
+    [[ -n "$f" ]] && rm -f "$f" 2>/dev/null || true
+  done
+}
+trap cleanup EXIT
+
+PASS=0
+FAIL=0
+pass() { echo "PASS: $1"; PASS=$((PASS + 1)); }
+fail() { echo "FAIL: $1" >&2; FAIL=$((FAIL + 1)); }
+
+# Admin-direct calls land with a non-subagent transcript path. A synthetic
+# empty file in a temp dir is enough — the hook no longer reads the path
+# for the deleted writers' case-block, but other gates may still touch it.
+ADMIN_TRANSCRIPT=$(mktemp); TMPFILES+=("$ADMIN_TRANSCRIPT")
+: > "$ADMIN_TRANSCRIPT"
+
+run_with_tool() {
+  local tool="$1"
+  local sid="$2"
+  local transcript_path="${3:-}"
+  local stdout_file; stdout_file=$(mktemp); TMPFILES+=("$stdout_file")
+  local stderr_file; stderr_file=$(mktemp); TMPFILES+=("$stderr_file")
+  python3 -c '
+import json, sys
+payload = {
+  "hook_event_name": "PreToolUse",
+  "session_id": sys.argv[1],
+  "tool_name": sys.argv[2],
+  "tool_input": {"name":"Smalleys","accountId":"acct-x","scope":"shared"},
+}
+if sys.argv[3]:
+  payload["transcript_path"] = sys.argv[3]
+print(json.dumps(payload, separators=(",", ":")))
+' "$sid" "$tool" "$transcript_path" | bash "$HOOK" admin >"$stdout_file" 2>"$stderr_file"
+  HOOK_RC=$?
+  HOOK_STDERR=$(cat "$stderr_file")
+}
+
+assert_passthrough() {
+  local label="$1"
+  if [[ "$HOOK_RC" -ne 0 ]]; then
+    fail "${label}: expected exit 0, got $HOOK_RC stderr: $HOOK_STDERR"
+    return
+  fi
+  if echo "$HOOK_STDERR" | grep -qF "does not write to the graph directly"; then
+    fail "${label}: stderr carries deleted-block rejection message: $HOOK_STDERR"
+    return
+  fi
+  pass "${label}: exit 0, no rejection stderr"
+}
+
+# --- 1. memory-write admin-direct passthrough ---------------------------
+run_with_tool "mcp__plugin_memory_memory__memory-write" "sess-write-1" "$ADMIN_TRANSCRIPT"
+assert_passthrough "admin-direct memory-write"
+
+# --- 2. memory-update admin-direct passthrough --------------------------
+run_with_tool "mcp__plugin_memory_memory__memory-update" "sess-update-1" "$ADMIN_TRANSCRIPT"
+assert_passthrough "admin-direct memory-update"
+
+# --- 3. memory-search admin-direct passthrough (read tool control) -----
+run_with_tool "mcp__plugin_memory_memory__memory-search" "sess-search-1" "$ADMIN_TRANSCRIPT"
+assert_passthrough "admin-direct memory-search (read tool control)"
+
+# --- 4. pre-209 namespace mcp__memory__memory-write ---------------------
+# The bare mcp__memory__ namespace was never in the admin runtime surface
+# after Task 203's plugin_ prefix rename; this case pins that it still
+# falls through harmlessly after the case-block removal.
+run_with_tool "mcp__memory__memory-write" "sess-old-ns-1" "$ADMIN_TRANSCRIPT"
+assert_passthrough "pre-209 namespace mcp__memory__memory-write"
+
+# --- 5. malformed JSON stdin — hook must not crash ----------------------
+stderr_file=$(mktemp); TMPFILES+=("$stderr_file")
+stdout_file=$(mktemp); TMPFILES+=("$stdout_file")
+echo "not-valid-json{{{" | bash "$HOOK" admin >"$stdout_file" 2>"$stderr_file"
+HOOK_RC=$?
+HOOK_STDERR=$(cat "$stderr_file")
+if [[ "$HOOK_RC" -ne 0 ]]; then
+  fail "malformed payload: expected exit 0, got $HOOK_RC stderr: $HOOK_STDERR"
+elif echo "$HOOK_STDERR" | grep -qF "does not write to the graph directly"; then
+  fail "malformed payload: stderr carries deleted-block rejection message: $HOOK_STDERR"
+else
+  pass "malformed payload: exit 0, hook does not crash"
+fi
+
+# --- Summary -----------------------------------------------------------
+echo "---"
+echo "PASSED: $PASS  FAILED: $FAIL"
+[[ "$FAIL" -eq 0 ]] || exit 1
+exit 0

package/payload/platform/plugins/admin/hooks/pre-tool-use.sh

@@ -21,108 +21,6 @@ TOOL_NAME=$(echo "$INPUT" | grep -o '"tool_name":"[^"]*"' | head -1 | cut -d'"'
 # ---------------------------------------------------------------------------
 if [ "$AGENT_TYPE" = "admin" ]; then
 
-  # ── Task 213 (rev. Task 222): memory-write/memory-update gate ────────────
-  # Admin does not write to the graph directly. The contract (Task 214 +
-  # admin IDENTITY.md) is that admin delegates a write to `database-operator`
-  # via the Task tool; database-operator holds the writers in its agent
-  # frontmatter and executes the write inside its own in-window subagent
-  # turn.
-  #
-  # The PreToolUse payload includes `transcript_path`, the JSONL the
-  # invoking session writes turns to. Claude Code stores a subagent's
-  # turns in a separate file at
-  #   <project-key>/<sessionId>/subagents/agent-<agentId>.jsonl
-  # so the path pattern is the deterministic discriminator between admin
-  # direct calls (parent JSONL) and Task subagent calls (subagent JSONL).
-  #
-  # The hook gates the two memory writers per-tool-use:
-  #   * Task-subagent caller (path matches subagent pattern)
-  #       → allow, emit caller=subagent:<subagent_type> source=hook-passthrough result=allowed
-  #   * admin direct caller (any other path)
-  #       → block exit 2, emit caller=admin source=hook result=rejected
-  #   * unparseable payload (no JSON, no transcript_path)
-  #       → fail-closed: block exit 2, emit caller=unknown source=hook result=rejected
-  # The subagent_type enrichment is best-effort: the subagent's own JSONL
-  # does not encode its agent name, so the hook reads the parent transcript
-  # (sibling `<sessionId>.jsonl` to the subagent dir) and extracts the
-  # `subagent_type` from the most recent `Task` tool_use. If that read
-  # fails for any reason the caller is logged as bare `subagent` and the
-  # call is still allowed.
-  case "$TOOL_NAME" in
-    mcp__plugin_memory_memory__memory-write|mcp__plugin_memory_memory__memory-update)
-      VERDICT=$(printf '%s' "$INPUT" | python3 -c '
-import sys, json, os, re
-tool_name = sys.argv[1]
-try:
-    d = json.load(sys.stdin)
-except Exception:
-    print("block|unknown|unknown|" + tool_name)
-    sys.exit(0)
-sid = d.get("session_id") or "unknown"
-tp = d.get("transcript_path") or ""
-m = re.search(r"/subagents/agent-[A-Za-z0-9_-]+\.jsonl$", tp)
-if not m:
-    caller = "admin" if tp else "unknown"
-    print("block|" + sid + "|" + caller + "|" + tool_name)
-    sys.exit(0)
-parent = tp[: m.start()] + ".jsonl"
-subagent_type = None
-if os.path.isfile(parent):
-    try:
-        with open(parent, "r", encoding="utf-8") as f:
-            for ln in f:
-                ln = ln.strip()
-                if not ln:
-                    continue
-                try:
-                    r = json.loads(ln)
-                except Exception:
-                    continue
-                if r.get("type") != "assistant":
-                    continue
-                msg = r.get("message") or {}
-                content = msg.get("content")
-                if not isinstance(content, list):
-                    continue
-                for b in content:
-                    if (isinstance(b, dict) and b.get("type") == "tool_use"
-                            and b.get("name") == "Task"):
-                        st = (b.get("input") or {}).get("subagent_type")
-                        if isinstance(st, str) and st:
-                            subagent_type = st
-    except Exception:
-        subagent_type = None
-caller = "subagent:" + subagent_type if subagent_type else "subagent"
-print("allow|" + sid + "|" + caller + "|" + tool_name)
-' "$TOOL_NAME" 2>/dev/null)
-      [ -z "$VERDICT" ] && VERDICT="block|unknown|unknown|${TOOL_NAME}"
-      DECISION=$(printf '%s' "$VERDICT" | cut -d'|' -f1)
-      SESSION_ID=$(printf '%s' "$VERDICT" | cut -d'|' -f2)
-      CALLER=$(printf '%s' "$VERDICT" | cut -d'|' -f3)
-      if [ "$DECISION" = "allow" ]; then
-        LINE_BODY="role=admin sessionId=${SESSION_ID} tool=${TOOL_NAME} caller=${CALLER} source=hook-passthrough result=allowed"
-      else
-        LINE_BODY="role=admin sessionId=${SESSION_ID} tool=${TOOL_NAME} caller=${CALLER} source=hook result=rejected"
-      fi
-      UI_PORT="${MAXY_UI_INTERNAL_PORT:-}"
-      if [ -n "$UI_PORT" ]; then
-        curl -sS -o /dev/null -X POST \
-          -H 'Content-Type: application/json' \
-          --max-time 2 \
-          --data "$(python3 -c '
-import sys, json
-print(json.dumps({"tag":"admin-tool-revoke","level":"info","line":sys.argv[1]}))
-' "$LINE_BODY")" \
-          "http://127.0.0.1:${UI_PORT}/api/admin/log-ingest" 2>/dev/null || true
-      fi
-      if [ "$DECISION" = "allow" ]; then
-        exit 0
-      fi
-      echo "Blocked: admin agent does not write to the graph directly. Delegate the write to database-operator via the Task tool; database-operator holds the memory-write and memory-update tools and will execute the write on admin's behalf." >&2
-      exit 2
-      ;;
-  esac
-
   # ── Code directory protection ────────────────────────────────────────────
   case "$TOOL_NAME" in
     Write|Edit)

package/payload/platform/plugins/cloudflare/PLUGIN.md

@@ -30,7 +30,7 @@ The plugin registers no agent-facing MCP tools. Every Cloudflare operation is dr
 
 | Script | Purpose |
 |---|---|
-| [`scripts/setup-tunnel.sh`](scripts/setup-tunnel.sh) | Autonomous end-to-end setup: OAuth login, tunnel resolve (operator-supplied identity), DNS route, config + state, service restart, post-restart verification. Invocation: `~/setup-tunnel.sh <brand> <port> <admin-hostname> [<public-hostname>] [<apex-hostname>]`. Required env: `STREAM_LOG_PATH`, `ACCOUNT_DIR`, AND exactly one of `TUNNEL_ID` (operator selected an existing tunnel — the agent enumerates them via `cloudflared tunnel list --output json` and presents the list in chat) or `TUNNEL_NAME` (operator typed a name to create) per the operator-selected-tunnel fix. The pre-fix derivation `${BRAND}-$(hostname -s)` is removed — the operator's logged-in Cloudflare account is the source of truth for which tunnel exists. Apex hostnames print an `ACTION REQUIRED` block for the dashboard record the CLI cannot create. Step 1 (wrappers faithfully relay third-party CLI) spawns `cloudflared tunnel login`, extracts the argotunnel URL from its stdout, mechanically opens it on the brand's VNC chromium using the install-time-resolved binary (`DISPLAY=${DISPLAY:-${BRAND_VNC_DISPLAY}} "${SETUP_TUNNEL_CHROMIUM_BIN}" <url> &` — `SETUP_TUNNEL_CHROMIUM_BIN` is read from `${MAXY_PLATFORM_ROOT}/config/chromium-binary.path` at script start so Ubuntu Noble laptop's snap-replaced Google Chrome is honoured by the install-time chromium resolver), then polls for `~/.cloudflared/cert.pem` while the operator clicks the zone row + Authorize on the VNC. 180 s budget with a 2-second `step=oauth-login result=awaiting-cert` heartbeat. No CDP auto-click, no DOM matcher. |
+| [`scripts/setup-tunnel.sh`](scripts/setup-tunnel.sh) | Autonomous end-to-end setup: OAuth login, tunnel resolve (operator-supplied identity), DNS route, config + state, service restart, post-restart verification. Invocation: `~/setup-tunnel.sh <brand> <port> <admin-hostname> [<public-hostname>] [<apex-hostname>]`. Required env: `STREAM_LOG_PATH`, `ACCOUNT_DIR`, AND exactly one of `TUNNEL_ID` (operator selected an existing tunnel — the agent enumerates them via `cloudflared tunnel list --output json` and presents the list in chat) or `TUNNEL_NAME` (operator typed a name to create) per the operator-selected-tunnel fix. The pre-fix derivation `${BRAND}-$(hostname -s)` is removed — the operator's logged-in Cloudflare account is the source of truth for which tunnel exists. Apex hostnames print an `ACTION REQUIRED` block for the dashboard record the CLI cannot create. Step 1 (wrappers faithfully relay third-party CLI) spawns `cloudflared tunnel login`, extracts the argotunnel URL from its stdout, and prints it as `OAUTH_URL: <url>` on its own stdout — the admin UI's `ActionLogPanel` renders that line as a clickable Authorize link with `target=_blank` so the operator authorizes Cloudflare in a new tab of their own browser. The script does not spawn a browser of its own; cloudflared's OAuth callback writes `~/.cloudflared/cert.pem` regardless of which browser completed the Authorize click. 180 s budget with a 2-second `step=oauth-login result=awaiting-cert` heartbeat. No CDP auto-click, no DOM matcher. |
 | [`scripts/reset-tunnel.sh`](scripts/reset-tunnel.sh) | Deletes every tunnel on the brand's CF account and wipes `${CFG_DIR}`. Does not touch the platform service, stray CNAMEs, or token-mode connectors — those require dashboard cleanup or `pkill`. Invocation: `~/reset-tunnel.sh <brand>`. No polling blocks — every long-wait is bounded by `cloudflared`'s network round-trip, so no heartbeat contract applies. |
 
 ### Skills

package/payload/platform/plugins/cloudflare/scripts/setup-tunnel.sh

@@ -14,14 +14,12 @@
 # hostnames. The script writes the ingress rule for them but prints an
 # explicit ACTION REQUIRED message naming the manual dashboard step.
 #
-# Step 1 owns the browser-spawn deterministically. The wrapper extracts
-# cloudflared's argotunnel URL from its stdout (regex below) and the moment
-# the URL surfaces, mechanically opens it on the Pi's VNC chromium via
-# `DISPLAY=${DISPLAY:-${BRAND_VNC_DISPLAY}} /usr/bin/chromium <url> &` — no reliance on
-# cloudflared's optimistic xdg-open, no CDP auto-click, no DOM matcher.
-# The operator clicks the zone row + Authorize on the VNC themselves.
-# This is the wrappers-faithfully-relay-third-party-cli doctrine;
-# any layer that auto-clicks Authorize for the operator is forbidden.
+# Step 1 surfaces the argotunnel URL on stdout as an `OAUTH_URL:` line.
+# The admin UI renders that line as a clickable link (target=_blank) so the
+# operator authorizes Cloudflare in the same browser they are already using
+# to talk to the admin chat. The script spawns no browser of its own — the
+# operator's local browser is the canonical operator-visible surface; the
+# brand VNC iframe is derived/optional and never the OAuth-completion path.
 # cloudflared's stdout+stderr is teed line-by-line into STREAM_LOG_PATH so
 # the chat UI's server-side tailer renders live progress in-turn.
 
@@ -99,67 +97,12 @@ phase_line setup-tunnel step=start brand="${BRAND}" port="${PORT}" hostnames="${
 CFG_DIR="${HOME}/.${BRAND}/cloudflared"
 mkdir -p "${CFG_DIR}"
 
-# Per-brand X display. Each brand owns its own Xtigervnc display
-# so the Chromium tab opened to drive the OAuth Authorize click lands in
-# THIS brand's isolated VNC, not whichever brand booted first on a shared
-# device. Read from the brand manifest if MAXY_PLATFORM_ROOT is exported
-# (set by the systemd unit and by claude-agent::buildSpawnEnv); fall back
-# to the inherited DISPLAY env var, then to :99 for the default brand.
+# brand.json path resolution. Step 5b reads `.operatorEmail` from this file
+# when OPERATOR_EMAIL is not in env; absent file is a tolerated no-op.
 SETUP_TUNNEL_BRAND_JSON=""
 if [ -n "${MAXY_PLATFORM_ROOT:-}" ] && [ -f "${MAXY_PLATFORM_ROOT}/config/brand.json" ]; then
   SETUP_TUNNEL_BRAND_JSON="${MAXY_PLATFORM_ROOT}/config/brand.json"
 fi
-BRAND_VNC_DISPLAY=":99"
-if [ -n "${SETUP_TUNNEL_BRAND_JSON}" ] && command -v jq >/dev/null 2>&1; then
-  _bvd=$(jq -r '.vncDisplay // empty' "${SETUP_TUNNEL_BRAND_JSON}" 2>/dev/null || true)
-  if [ -n "${_bvd}" ] && [ "${_bvd}" -eq "${_bvd}" ] 2>/dev/null; then
-    BRAND_VNC_DISPLAY=":${_bvd}"
-  fi
-fi
-
-# read the install-time-resolved non-snap Chromium binary path so
-# the OAuth-URL spawn below uses the same binary vnc.sh's start_chrome runs.
-# Hardcoded `/usr/bin/chromium` would re-introduce the snap-AppArmor failure
-# on Ubuntu Noble laptop. The installer writes this file under platform/config/
-# during installSystemDeps; the spawn at step=browser-spawn fails loud if the
-# file is absent rather than silently falling back to /usr/bin/chromium.
-#
-# four discrete branches (env-unset / file-missing / file-empty /
-# binary-not-executable) so the failure message names the actual condition.
-# Pre-957 the four were conflated into one "cannot resolve a non-snap Chromium
-# binary" message, which masked the env-propagation defect that closed three
-# prior tasks (836, 562, 862) and silently re-fired here.
-if [ -z "${MAXY_PLATFORM_ROOT:-}" ]; then
-  phase_line setup-tunnel step=chromium-resolve result=error reason=env-unset var=MAXY_PLATFORM_ROOT
-  echo "ERROR: setup-tunnel.sh: MAXY_PLATFORM_ROOT is unset in the script's env." >&2
-  echo "       The action runner must declare MAXY_PLATFORM_ROOT in the cloudflare-setup" >&2
-  echo "       whitelist env: block (platform/ui/server/lib/action-runner.ts) — systemd-run --user" >&2
-  echo "       does not inherit the parent process env into the transient unit." >&2
-  exit 1
-fi
-SETUP_TUNNEL_CHROMIUM_PATH_FILE="${MAXY_PLATFORM_ROOT}/config/chromium-binary.path"
-if [ ! -r "${SETUP_TUNNEL_CHROMIUM_PATH_FILE}" ]; then
-  phase_line setup-tunnel step=chromium-resolve result=error reason=path-file-missing path="${SETUP_TUNNEL_CHROMIUM_PATH_FILE}"
-  echo "ERROR: setup-tunnel.sh: chromium-binary.path file is missing or unreadable." >&2
-  echo "       Expected: ${SETUP_TUNNEL_CHROMIUM_PATH_FILE}" >&2
-  echo "       Re-run the installer to provision Chromium." >&2
-  exit 1
-fi
-SETUP_TUNNEL_CHROMIUM_BIN="$(head -n1 "${SETUP_TUNNEL_CHROMIUM_PATH_FILE}" | tr -d '[:space:]')"
-if [ -z "${SETUP_TUNNEL_CHROMIUM_BIN}" ]; then
-  phase_line setup-tunnel step=chromium-resolve result=error reason=path-file-empty path="${SETUP_TUNNEL_CHROMIUM_PATH_FILE}"
-  echo "ERROR: setup-tunnel.sh: chromium-binary.path is empty." >&2
-  echo "       File: ${SETUP_TUNNEL_CHROMIUM_PATH_FILE}" >&2
-  echo "       Re-run the installer to provision Chromium." >&2
-  exit 1
-fi
-if [ ! -x "${SETUP_TUNNEL_CHROMIUM_BIN}" ]; then
-  phase_line setup-tunnel step=chromium-resolve result=error reason=binary-not-executable bin="${SETUP_TUNNEL_CHROMIUM_BIN}" path="${SETUP_TUNNEL_CHROMIUM_PATH_FILE}"
-  echo "ERROR: setup-tunnel.sh: ${SETUP_TUNNEL_CHROMIUM_BIN} is not an executable file." >&2
-  echo "       Resolved from: ${SETUP_TUNNEL_CHROMIUM_PATH_FILE}" >&2
-  echo "       Re-run the installer to provision Chromium." >&2
-  exit 1
-fi
 
 # --------------------------------------------------------------------------
 # Step 1: OAuth login. Corresponds to runbook Step 1.
@@ -174,32 +117,26 @@ fi
 #                                                   but failed before the mv;
 #                                                   promote and skip cloudflared.
 #   both missing                                  → spawn cloudflared, surface
-#                                                   the URL on the Pi VNC,
-#                                                   wait for the operator's
-#                                                   click, poll for cert.pem,
-#                                                   mv.
+#                                                   the OAuth URL on stdout for
+#                                                   the admin UI to render as a
+#                                                   clickable link, poll for
+#                                                   cert.pem, mv.
 #
-# Control flow when both certs are missing
-# relay third-party CLI):
+# Control flow when both certs are missing:
 #   1. Spawn cloudflared with stdout+stderr teed line-by-line to
 #      $STREAM_LOG_PATH with prefix [script:setup-tunnel:cloudflared]
 #      (the chat-surface namespace — see _stream-log.sh header).
 #   2. Extract the authorize URL with a tolerant regex as it streams.
-#   3. The instant the URL is extracted, mechanically open it on the Pi
-#      VNC chromium via `DISPLAY=${DISPLAY:-${BRAND_VNC_DISPLAY}} /usr/bin/chromium <url> &`.
-#      Fire-and-forget — chromium is already running with CDP enabled at
-#      :9222, so the invocation IPCs the URL into the running instance as
-#      a new tab. The spawn is intentionally NOT tracked in the EXIT trap:
-#      it is a sibling open, not a child of cloudflared, and an orphaned
-#      late-arriving tab is harmless. Replaces cloudflared's own optimistic
-#      xdg-open which does not reliably target VNC :99 in this environment.
-#   4. Emit `step=browser-spawn` and `step=browser-drive mode=operator-click`
-#      so the stream log records the surface state.
-#   5. Wait for ~/.cloudflared/cert.pem to land (180 s budget — operator
-#      must click the zone row + Authorize on VNC).
-#   6. Move cert.pem into the brand-scoped path.
+#   3. Print the URL on stdout as `OAUTH_URL: <url>` so the admin UI
+#      renders a clickable link. The script does not spawn a browser —
+#      the operator's local browser is the canonical surface; cloudflared's
+#      OAuth callback writes ~/.cloudflared/cert.pem regardless of which
+#      browser completed the Authorize click (it's a server-to-server poll
+#      against login.cloudflareaccess.org).
+#   4. Wait for ~/.cloudflared/cert.pem to land (180 s budget — operator
+#      must click the link and Authorize on Cloudflare).
+#   5. Move cert.pem into the brand-scoped path.
 #
-# No CDP auto-click. No DOM matcher. No consent-page driver of any kind.
 # Every failure branch exits 1 loudly naming the cause.
 # --------------------------------------------------------------------------
 
@@ -237,7 +174,7 @@ if [ ! -f "${CFG_DIR}/cert.pem" ] && [ -f "${HOME}/.cloudflared/cert.pem" ]; the
 fi
 
 if [ ! -f "${CFG_DIR}/cert.pem" ]; then
-  phase_line setup-tunnel step=oauth-login cert_path="${CFG_DIR}/cert.pem" display="${DISPLAY:-${BRAND_VNC_DISPLAY}}"
+  phase_line setup-tunnel step=oauth-login cert_path="${CFG_DIR}/cert.pem"
 
   URL_FILE="$(mktemp -t maxy-setup-tunnel-url.XXXXXX)"
   LAST_LINE_FILE="$(mktemp -t maxy-setup-tunnel-last.XXXXXX)"
@@ -249,16 +186,8 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
   # callback forever; subsequent setup-tunnel runs see a stale cert.pem
   # landing asynchronously and race against the new URL-extraction pass.
   CF_PIPELINE_PID=""
-  CHROMIUM_UNIT=""
   cleanup_oauth() {
     [ -n "${CF_PIPELINE_PID}" ] && kill "${CF_PIPELINE_PID}" 2>/dev/null || true
-    # stop the transient chromium unit on any early exit between
-    # browser-spawn and the explicit step=browser-close site below. Best-
-    # effort: no phase_line here because the EXIT trap fires on every path
-    # (including the happy one where step=browser-close already ran and
-    # auto-collected the unit). The `|| true` masks the inevitable "Unit
-    # not loaded" return on the happy path.
-    [ -n "${CHROMIUM_UNIT}" ] && systemctl --user stop "${CHROMIUM_UNIT}" 2>/dev/null || true
     rm -f "${URL_FILE}" "${LAST_LINE_FILE}"
   }
   trap cleanup_oauth EXIT
@@ -267,7 +196,7 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
   # extracted as it streams. The subshell holds the whole pipeline so
   # PIPESTATUS[0] (cloudflared's exit code) is reachable later.
   (
-    DISPLAY="${DISPLAY:-${BRAND_VNC_DISPLAY}}" stdbuf -oL -eL cloudflared \
+    stdbuf -oL -eL cloudflared \
       --origincert "${CFG_DIR}/cert.pem" tunnel login 2>&1 |
       while IFS= read -r line; do
         ts="$(stream_log_ts)"
@@ -309,71 +238,17 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
   fi
 
   AUTH_URL="$(cat "${URL_FILE}")"
-  phase_line setup-tunnel step=browser-drive url_extracted=1
+  phase_line setup-tunnel step=oauth-url-extracted url_extracted=1
 
   # Emit the URL on stdout in a shape ActionLogPanel's regex captures.
-  # The button is a redundant re-spawn fallback — by the time the chat-side
-  # ActionLogPanel renders, the page is already on the Pi VNC chromium per
-  # the spawn below. Button click POSTs to /api/admin/device-browser/navigate
-  # to re-target the same URL on the VNC; same end-effect as this spawn.
+  # The admin UI renders this line as a clickable link (target=_blank) so
+  # the operator authorizes Cloudflare in the same browser they are using
+  # for the admin chat. The script does not spawn a browser of its own.
   printf 'OAUTH_URL: %s\n' "${AUTH_URL}"
 
-  # Mechanically open the URL on the Pi VNC chromium. Chromium
-  # is already running on this brand's ${BRAND_VNC_DISPLAY} with CDP enabled
-  # (vnc.sh start_chrome at boot); invoking the resolved binary <url> against
-  # a running instance IPCs the URL into it as a new tab. Replaces
-  # cloudflared's own optimistic xdg-open, which does not reliably target
-  # the brand's VNC display in this environment.
-  #
-  # chromium is launched under a transient systemd-user unit so
-  # the full process tree (including any standalone chromium that lands
-  # when no existing instance is running for IPC) lives in its own cgroup.
-  # On cert.pem arrival the unit is stopped, SIGTERMing the whole cgroup
-  # atomically. Pre-Task-982 the spawn was `&` fire-and-forget with no
-  # tracked PID; the resulting orphan chromium on display :101 was the
-  # symptom in maxy-2 2026-05-12T10:06–10:08Z. `step=browser-close
-  # result=ok|orphan` records the teardown outcome at cert.pem mv site
-  # below.
-  #
-  # Binary path: SETUP_TUNNEL_CHROMIUM_BIN is read at startup from
-  # ${MAXY_PLATFORM_ROOT}/config/chromium-binary.path — `/usr/bin/chromium`
-  # on Pi Bookworm and `/usr/bin/google-chrome-stable` on Ubuntu Noble laptop
-  # where the system chromium is snap-confined. Hardcoding
-  # `/usr/bin/chromium` here would re-introduce the AppArmor SingletonLock
-  # failure on the laptop.
-  CHROMIUM_UNIT="maxy-oauth-chromium-${BRAND}-$$.service"
-  CHROMIUM_LAUNCH_DISPLAY="${DISPLAY:-${BRAND_VNC_DISPLAY}}"
-  CHROMIUM_SPAWN_ERR="$(mktemp -t maxy-oauth-chromium-err.XXXXXX)"
-  if systemd-run --user \
-      --unit="${CHROMIUM_UNIT}" \
-      --description="Maxy OAuth chromium for ${BRAND}" \
-      --collect \
-      --setenv=DISPLAY="${CHROMIUM_LAUNCH_DISPLAY}" \
-      "${SETUP_TUNNEL_CHROMIUM_BIN}" "${AUTH_URL}" 2>"${CHROMIUM_SPAWN_ERR}"; then
-    rm -f "${CHROMIUM_SPAWN_ERR}"
-    phase_line setup-tunnel step=browser-spawn result=ok \
-      display="${CHROMIUM_LAUNCH_DISPLAY}" url_extracted=1 unit="${CHROMIUM_UNIT}"
-  else
-    SPAWN_RC=$?
-    SPAWN_STDERR="$(tr '\n' ' ' < "${CHROMIUM_SPAWN_ERR}" | head -c 300 || echo unavailable)"
-    rm -f "${CHROMIUM_SPAWN_ERR}"
-    # Loud-fail rather than fire-and-forget fallback: a systemd-run failure
-    # leaves no teardown handle. Operator should see the bus-not-running
-    # / linger-not-enabled cause.
-    phase_line setup-tunnel step=browser-spawn result=error \
-      reason=systemd-run-failed exit="${SPAWN_RC}" stderr="${SPAWN_STDERR}" \
-      unit="${CHROMIUM_UNIT}"
-    echo "ERROR: systemd-run failed to spawn chromium under transient unit (exit=${SPAWN_RC})." >&2
-    echo "       systemd-run stderr: ${SPAWN_STDERR}" >&2
-    echo "       If stderr mentions 'Failed to connect to bus', enable user-scope" >&2
-    echo "       systemd via 'loginctl enable-linger \$(whoami)' and retry." >&2
-    exit 1
-  fi
-  phase_line setup-tunnel step=browser-drive mode=operator-click url="${AUTH_URL}"
-
   # Wait for cert.pem to land — cloudflared writes to ~/.cloudflared/cert.pem
   # regardless of --origincert, so watch the canonical location. The wait is
-  # human-paced: the operator must click the zone row + Authorize on the VNC.
+  # human-paced: the operator must click the link and Authorize on Cloudflare.
   # 180 s default budget; SETUP_TUNNEL_LOGIN_TIMEOUT overrides for testing.
   # The 2-second heartbeat inside the loop is the observability contract —
   # no form-spawned script is allowed a silent poll of more than ~2 s.
@@ -397,10 +272,10 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
       echo "ERROR: Timed out after ${LOGIN_WAIT}s waiting for cert.pem to land." >&2
       exit 1
     fi
-    # Heartbeat every 2 s after the click. t=0 is the browser-drive
-    # phase line above; the first heartbeat fires at t=2. Without this line
-    # the tailer sees silence for the full 1-20 s round-trip — the exact
-    # state the heartbeat contract forbids.
+    # Heartbeat every 2 s. t=0 is the oauth-url-extracted phase line above;
+    # the first heartbeat fires at t=2. Without this line the tailer sees
+    # silence for the full 1-20 s round-trip — the exact state the heartbeat
+    # contract forbids.
     if [ "${LOGIN_WAIT}" -gt 0 ] && [ $((LOGIN_WAIT % 2)) -eq 0 ]; then
       phase_line setup-tunnel step=oauth-login result=awaiting-cert \
         elapsed="${LOGIN_WAIT}s" timeout="${LOGIN_TIMEOUT}s"
@@ -412,45 +287,6 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
   mv "${HOME}/.cloudflared/cert.pem" "${CFG_DIR}/cert.pem"
   phase_line setup-tunnel step=oauth-login result=ok \
     path="${CFG_DIR}/cert.pem" waited="${LOGIN_WAIT}s"
-
-  # SIGTERM the OAuth chromium cgroup now that cert.pem has
-  # landed. The transient unit was created above at step=browser-spawn; if
-  # chromium IPCs'd to a running brand-VNC instance and exited cleanly, the
-  # unit is already auto-collected and `systemctl stop` returns 0 (no-such-
-  # unit is a benign race, not an orphan). If chromium is still alive (no
-  # pre-existing brand-VNC instance to IPC into), SIGTERM tears the whole
-  # cgroup atomically. `result=ok` covers both clean paths; `result=orphan`
-  # fires only when the stop command itself fails (bus issue, race with
-  # auto-collect that returned non-zero) — operator-visible signal that an
-  # orphan chromium MAY still be alive on the VNC display.
-  CHROMIUM_STOP_ERR="$(mktemp -t maxy-oauth-chromium-stop-err.XXXXXX)"
-  if systemctl --user stop "${CHROMIUM_UNIT}" 2>"${CHROMIUM_STOP_ERR}"; then
-    rm -f "${CHROMIUM_STOP_ERR}"
-    phase_line setup-tunnel step=browser-close result=ok unit="${CHROMIUM_UNIT}"
-  else
-    STOP_RC=$?
-    STOP_STDERR="$(tr '\n' ' ' < "${CHROMIUM_STOP_ERR}" | head -c 300 || echo unavailable)"
-    rm -f "${CHROMIUM_STOP_ERR}"
-    # Distinguish benign "unit already auto-collected" from a true teardown
-    # failure via systemctl's exit-code taxonomy — never via stderr prose
-    # parsing, which breaks on non-English locales (no-stdout-parsing-for-
-    # control-flow doctrine). Exit code 5 is systemd's canonical "Unit not
-    # loaded" return; --collect auto-GCs a terminated unit between the
-    # chromium-side IPC-and-exit and our stop, producing exactly this code.
-    # Any other non-zero exit is a real teardown failure (bus down, permission,
-    # service still alive but stop hung).
-    if [ "${STOP_RC}" -eq 5 ]; then
-      phase_line setup-tunnel step=browser-close result=ok \
-        reason=unit-auto-collected unit="${CHROMIUM_UNIT}"
-    else
-      phase_line setup-tunnel step=browser-close result=orphan \
-        reason=stop-failed exit="${STOP_RC}" stderr="${STOP_STDERR}" \
-        unit="${CHROMIUM_UNIT}"
-      echo "WARNING: failed to stop transient chromium unit ${CHROMIUM_UNIT} (exit=${STOP_RC})." >&2
-      echo "         An orphan chromium may remain on display ${CHROMIUM_LAUNCH_DISPLAY}." >&2
-      echo "         systemctl stderr: ${STOP_STDERR}" >&2
-    fi
-  fi
 fi
 
 # --------------------------------------------------------------------------

package/payload/platform/plugins/cloudflare/skills/setup-tunnel/SKILL.md

@@ -22,7 +22,9 @@ Any Cloudflare action outside these four surfaces is a discipline violation —
 
 Use this when the operator wants Cloudflare set up (or re-set up) end-to-end on the device. The script handles OAuth login, tunnel creation, DNS routing for each subdomain, config.yml + tunnel.state, and dispatches the `${BRAND}.service` restart to a transient `systemd-run` unit — all in one invocation. The restart fires a few seconds after the script exits so the script does not kill its own cgroup when invoked via the Bash tool; the chat UI receives a `server_shutdown` SSE frame and reconnects automatically. Post-restart hostname verification is out of scope for the script (connector is not up when the script exits) — verify via the next admin turn or manually with `curl -I https://<hostname>`. Apex hostnames cannot be routed by the CLI; when one is passed, the script prints an `ACTION REQUIRED` block naming the exact dashboard record to edit.
 
-Step 1's OAuth flow is a state machine over two observable variables: the brand-scoped cert path (`${CFG_DIR}/cert.pem`) and the OAuth-default cert path (`~/.cloudflared/cert.pem`). When the brand-scoped cert is missing but the default-path cert is present from any prior partial run, the wrapper promotes it (`mv`) and emits `step=oauth-login result=ok reason=cert-promoted-from-default-path` without re-spawning cloudflared. When both are missing, the wrapper spawns `cloudflared tunnel login`, extracts the argotunnel URL from its stdout, and the instant the URL surfaces, mechanically opens it on the brand's VNC chromium under a transient `systemd-run --user --unit=maxy-oauth-chromium-${BRAND}-$$.service` so the chromium process tree lives in its own cgroup (earlier the spawn was `&` fire-and-forget and orphaned chromium on display `:101` when no pre-existing brand-VNC chromium was available for IPC). The launch uses the install-time-resolved binary (`SETUP_TUNNEL_CHROMIUM_BIN` from `${MAXY_PLATFORM_ROOT}/config/chromium-binary.path` so Ubuntu Noble laptop's snap-replaced Google Chrome is honoured) — emitting `step=browser-spawn result=ok unit=<transient-unit>` and `step=browser-drive mode=operator-click`. The operator clicks the zone row + Authorize on the VNC; cloudflared's callback writes `~/.cloudflared/cert.pem`; the wrapper's cert-poll (180 s budget) picks it up and `mv`s it to the brand-scoped path; the wrapper then `systemctl --user stop`s the transient unit, emitting `step=browser-close result=ok` (or `result=orphan reason=stop-failed` when SIGTERM didn't reach the cgroup — operator-visible signal that an orphan chromium MAY still be alive). There is no CDP auto-click, no DOM matcher, no consent-page driver — the wrapper's job is to faithfully relay `cloudflared tunnel login`, never to layer automation on top.
+Step 1's OAuth flow is a state machine over two observable variables: the brand-scoped cert path (`${CFG_DIR}/cert.pem`) and the OAuth-default cert path (`~/.cloudflared/cert.pem`). When the brand-scoped cert is missing but the default-path cert is present from any prior partial run, the wrapper promotes it (`mv`) and emits `step=oauth-login result=ok reason=cert-promoted-from-default-path` without re-spawning cloudflared. When both are missing, the wrapper spawns `cloudflared tunnel login`, extracts the argotunnel URL from its stdout, and prints it on its own stdout as `OAUTH_URL: <url>` plus a `step=oauth-url-extracted url_extracted=1` phase line. The admin UI's `ActionLogPanel` renders that `OAUTH_URL` line as a clickable Authorize link with `target=_blank`, opening a new tab in the operator's own browser — the canonical operator-visible OAuth surface. The wrapper does not spawn a browser of its own; cloudflared's OAuth callback polls Cloudflare server-to-server and writes `~/.cloudflared/cert.pem` regardless of which browser completed the Authorize click. The wrapper's cert-poll (180 s budget) picks the cert up and `mv`s it to the brand-scoped path. There is no CDP auto-click, no DOM matcher, no consent-page driver — the wrapper's job is to faithfully relay `cloudflared tunnel login` and surface the URL for the operator to click.
+
+**Operator-visible-surface doctrine.** The operator's visible surface is their local browser — the one already showing the admin UI. The brand VNC iframe is a derived, optional surface that the operator may or may not have open. Any agent claim that ties a UI outcome to a Pi-side surface (a brand VNC chromium tab, a `:N` display) is wrong by construction — the operator may not be watching that surface. Surfaces the agent can trust as operator-visible: the admin chat itself, the admin UI's ActionLogPanel banner, and links the operator clicked from either of those two. Everything else is best-effort.
 
 ### How inputs reach the script
 
@@ -100,6 +102,15 @@ The YAML and JSON rendering live in a pure Node helper at
 
 The agent invokes the script directly via the Bash tool — there is no form, no endpoint relay. Stream the script's stdout into chat verbatim as it arrives; if an `ACTION REQUIRED` block appears, quote it exactly — the operator needs the specific dashboard instructions it contains.
 
+### Narrating OAuth progress
+
+The script tees structured phase lines into the stream log (`[setup-tunnel] step=<phase> <key=value …>`). The admin UI renders the `OAUTH_URL` stdout line as a clickable Authorize link directly above the log panel; the operator clicks it and authorizes in a new tab of their own browser. The agent's narration job is to let that link do the work and not claim where any tab is open.
+
+- **When `step=oauth-url-extracted url_extracted=1` appears,** the URL is already surfaced as a clickable link in the operator's chat. The agent says one short line — "click the Authorize link and I'll pick up the cert once you've authorised" — and waits. No claim about which device or screen the link opens on; the operator's browser handles that.
+- **When `step=oauth-login result=ok reason=cert-promoted-from-default-path` appears,** a prior run already completed OAuth — Step 1 short-circuits to the existing cert. No operator action is needed.
+- **When `step=oauth-login result=error reason=<token>` appears,** the agent restates the literal `reason=…` and any `last_line=…` field and stops per the discipline rule below. The reasons that can fire on this path are `cloudflared-exited-before-url`, `url-not-extracted`, `timeout-waiting-cert`, `cloudflared-exited-no-cert`, and `cert-promote-failed`. `timeout-waiting-cert` specifically means the operator did not click Authorize within 180 s; the remediation is a fresh `~/setup-tunnel.sh` invocation, which will land on the cert-promotion pre-flight if the operator authorised after the timeout.
+- **Stream-log `result=ok` on its own steps is not narration evidence.** The agent narrates from operator-action outcomes — link clicked, cert landed — not from script-internal phase ticks.
+
 ### When the script exits non-zero
 
 Relay the script's stdout to the operator verbatim, name the literal exit code, and cite `references/reset-guide.md` for the next action. Do not attempt a second invocation under a different flag combination, a Playwright-driven dashboard inspection, or an alternative `cloudflared` command sequence. The discipline rule below applies.

package/payload/platform/plugins/docs/references/admin-session.md

@@ -83,7 +83,7 @@ The Hono route `POST /api/admin/claude-sessions` at [`platform/ui/server/routes/
 
 **Forwarded endpoints.** One upstream call per spawn-with-message: `POST {managerBase}/spawn` (enriched body, with `initialMessage` inlined when set). The manager appends `initialMessage` as the trailing positional argv to `claude` so the CLI processes it as the session's first user turn at PTY startup — the JSONL first `role=user` line equals `initialMessage` verbatim. No follow-up `POST {managerBase}/<sessionId>/input` call, no bracketed-paste, no keystroke injection. The HTTP response streams the spawn upstream body straight through. (Task 153.)
 
-**Callers.** `Sidebar.tsx`'s "+ New session" click handler (sends no `initialMessage` — Task 146 made Claude Code's own label canonical, so no UI-side stimulus is injected); the turn-recorder hook (loopback path — see "Turn-recorder" below); future programmatic spawns. Every caller routes through this wrapper. The on-the-wire signal that the contract held is the `[claude-session-manager:wrapper] spawn-request-in surface=<cookie|loopback>` log line followed by `forward-spawn-done`.
+**Callers.** `Sidebar.tsx`'s "+ New session" click opens the `NewSessionModal` (Task 223) — no POST fires on click. Modal submit POSTs `{channel:'browser', permissionMode, model, initialMessage}` where `initialMessage` is the operator's typed text verbatim; `permissionMode` and `model` are per-session overrides local to the modal and never propagate back to the sidebar's seed state. The turn-recorder hook (loopback path — see "Turn-recorder" below) and future programmatic spawns route through the same wrapper. The on-the-wire signal that the contract held is the `[claude-session-manager:wrapper] spawn-request-in surface=<cookie|loopback>` log line followed by `forward-spawn-done`; on the cookie path it now always carries `initialMessage=yes`, which a regressed client gate would flip to `no`.
 
 ## Turn-recorder: a first-class specialist spawn with three body overrides