@rubytech/create-maxy 1.0.798 → 1.0.800

package/dist/index.js

@@ -1765,11 +1765,17 @@ function installTunnelScripts() {
     // $HOME symlink — it's a helper, not a top-level operator command. We do
     // chmod +x defensively so `ls -l` and any ad-hoc `~/setup-tunnel.sh` copy
     // flow sees it as executable (Task 588).
+    //
+    // _cdp-authorize-matcher.mjs is imported by _cdp-authorize.mjs (Task 855)
+    // — the tri-state matcher's MATCH_EXPR + findMatch live in this side
+    // module so JSDOM tests run identical logic to the live page. chmod +x
+    // is defensive symmetry; the file is read by Node, not exec'd.
     const cdpAuthorizeSrc = join(INSTALL_DIR, "platform/plugins/cloudflare/scripts/_cdp-authorize.mjs");
+    const cdpMatcherSrc = join(INSTALL_DIR, "platform/plugins/cloudflare/scripts/_cdp-authorize-matcher.mjs");
     const setupLink = resolve(process.env.HOME ?? "/root", "setup-tunnel.sh");
     const resetLink = resolve(process.env.HOME ?? "/root", "reset-tunnel.sh");
     const listLink = resolve(process.env.HOME ?? "/root", "list-cf-domains.sh");
-    for (const src of [setupSrc, resetSrc, listSrc, cdpAuthorizeSrc]) {
+    for (const src of [setupSrc, resetSrc, listSrc, cdpAuthorizeSrc, cdpMatcherSrc]) {
         try {
             chmodSync(src, 0o755);
         }

package/package.json

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

package/payload/platform/neo4j/schema.cypher

@@ -919,6 +919,40 @@ FOR (c:Component) ON (c.messageId);
 CREATE INDEX component_account IF NOT EXISTS
 FOR (c:Component) ON (c.accountId);
 
+// ----------------------------------------------------------
+// :Attachment — Task 854. Sibling node hung off a :Message via
+// [:HAS_ATTACHMENT] capturing user-side file uploads (image, pdf,
+// text/markdown/csv/html, calendar, zip; see attachments.ts
+// SUPPORTED_MIME_TYPES). Mirrors :Component (Task 815).
+//
+// Properties:
+//   attachmentId   — UUID assigned at storeAttachment time; matches
+//                     the on-disk directory + Neo4j node id.
+//   conversationId — denormalised for filtered scans + cascade delete.
+//   accountId      — account-isolation. Reads MUST scope by this.
+//   messageId      — back-pointer to parent :Message.
+//   filename       — original upload name (kept for chip render).
+//   mimeType       — validated MIME (assertSupportedMime).
+//   sizeBytes      — original byte size at upload.
+//   storagePath    — absolute on-disk path. Server-only — never
+//                     surfaced to the client (chip click resolves
+//                     via attachmentId, not path).
+//   ordinal        — upload-order index within the parent turn (0-based).
+//                     Reader uses it to re-render chips in upload order.
+//   createdAt      — datetime when persisted.
+//
+// (:Message)-[:HAS_ATTACHMENT]->(:Attachment)
+// ----------------------------------------------------------
+
+CREATE CONSTRAINT attachment_id_unique IF NOT EXISTS
+FOR (a:Attachment) REQUIRE a.attachmentId IS UNIQUE;
+
+CREATE INDEX attachment_message IF NOT EXISTS
+FOR (a:Attachment) ON (a.messageId);
+
+CREATE INDEX attachment_account IF NOT EXISTS
+FOR (a:Attachment) ON (a.accountId);
+
 // ----------------------------------------------------------
 // :Trashed — Task 576 soft-delete primitive.
 //

package/payload/platform/plugins/cloudflare/references/manual-setup.md

@@ -131,6 +131,18 @@ ls /tmp/.X11-unix/
 
 You should see `X99`. If not, start VNC before retrying Step 1.
 
+### Three states the consent page can render
+
+The dashboard at `dash.cloudflare.com/argotunnel?...` shows one of three states. The automation script's CDP helper (`_cdp-authorize.mjs`) detects each one; the same triage applies when you walk the flow manually.
+
+1. **Pre-authorize — the Authorize button is visible.** This is the normal first run. Click the zone you want, then click **Authorize**. Cloudflare's callback fires and `~/.cloudflared/cert.pem` lands a second or two later. Continue with the `mv` above.
+
+2. **Post-success — "Cloudflared has installed a certificate" modal.** The bound account already has a cert authorised for the zones the dashboard knows about. The OAuth callback is idempotent — navigating to a fresh `cloudflared tunnel login` URL still fires the callback, so `~/.cloudflared/cert.pem` will land. Wait a second or two, then run the `mv`.
+
+   If the cert *also* exists at `${CFG_DIR}/cert.pem` from a prior partial run, Step 1 is already complete — skip to Step 2.
+
+3. **Blank or button-less — neither the Authorize button nor the success modal is on the page.** The browser may be mid-load, signed out of Cloudflare, blocking on captcha, or showing some other state. Sign in to Cloudflare in the same browser, navigate back to the URL `cloudflared tunnel login` printed, and complete the click manually. If the URL has expired, kill `cloudflared` (`Ctrl+C`) and re-run Step 1 to get a fresh URL.
+
 ---
 
 ## Step 2 — List existing tunnels

package/payload/platform/plugins/cloudflare/scripts/_cdp-authorize-matcher.mjs

@@ -0,0 +1,74 @@
+// Tri-state DOM matcher for the Cloudflare argotunnel consent page (Task 855).
+//
+// `dash.cloudflare.com/argotunnel?...` legitimately renders three observable
+// states for our flow:
+//
+//   1. Pre-authorize — a <button> or <input type="submit"> whose trimmed text
+//      matches /^(authorize|connect)$/i (and is not disabled). Click it; the
+//      callback fires, cloudflared writes ~/.cloudflared/cert.pem.
+//
+//   2. Post-success — the dashboard renders a Success modal containing the
+//      stable substring "Cloudflared has installed a certificate". This shape
+//      is reached when the user already authorised this account before (or
+//      did so manually in VNC between cloudflared spawn and helper poll).
+//      The OAuth callback is idempotent on the cert side: when the helper
+//      sees this state, the running cloudflared subprocess will still write
+//      ~/.cloudflared/cert.pem because the callback URL is exercised by the
+//      navigation. The wrapper drops into the existing cert-poll afterwards.
+//
+//   3. Neither — the page is mid-load, blank, or in some other state. The
+//      caller polls again until BUTTON_POLL_TIMEOUT_MS, then exits 1.
+//
+// The matcher returns a discriminated union from a single DOM read:
+//
+//   { kind: 'button', descriptor: {tag,text,disabled} } | { kind: 'success' } | null
+//
+// PRIORITY: button > success modal. Page transitions can briefly render both
+// (e.g. during the success animation). If a clickable Authorize button exists,
+// click it — the click produces a fresh callback regardless of any leftover
+// modal text. Only when no button is present do we trust the modal as the
+// terminal state.
+//
+// EXPORTED SHAPES:
+//
+//   * findMatch(doc) — JS function form. Used by JSDOM-based unit tests
+//     (platform/ui/scripts/__tests__/cdp-authorize-matcher.test.ts) so future
+//     matcher edits replay against captured DOM fixtures offline (Success
+//     criterion 8 of Task 855).
+//
+//   * MATCH_EXPR — string form, evaluated by Chrome DevTools Protocol's
+//     Runtime.evaluate in _cdp-authorize.mjs's polling loop. Built from
+//     findMatch.toString() so the live page and the tests run identical
+//     logic — single source of truth.
+//
+// CONTRACT — DO NOT loosen the success-modal anchor. Tighter anchors regress
+// on Cloudflare copy edits; "Cloudflared has installed a certificate" is the
+// load-bearing claim of the modal. Wider anchors (e.g. matching just
+// "certificate") would false-positive on the pre-authorize page.
+
+export function findMatch(doc) {
+  const candidates = Array.from(doc.querySelectorAll('button, input[type="submit"]'));
+  const match = candidates.find((el) => {
+    const text = (el.textContent ?? el.value ?? '').trim();
+    return /^(authorize|connect)$/i.test(text) && !el.disabled;
+  });
+  if (match) {
+    const descriptor = {
+      tag: match.tagName.toLowerCase(),
+      text: (match.textContent ?? match.value ?? '').trim().slice(0, 40),
+      disabled: Boolean(match.disabled),
+    };
+    match.click();
+    return { kind: 'button', descriptor };
+  }
+  // textContent over innerText: jsdom's innerText is partial; the dashboard's
+  // success-modal text is plain DOM content (not visibility-gated by CSS for
+  // anyone reading the page) so textContent finds it on both runtimes.
+  const bodyText = doc.body ? doc.body.textContent || '' : '';
+  if (bodyText.includes('Cloudflared has installed a certificate')) {
+    return { kind: 'success' };
+  }
+  return null;
+}
+
+export const MATCH_EXPR = `(${findMatch.toString()})(document)`;

package/payload/platform/plugins/cloudflare/scripts/_cdp-authorize.mjs

@@ -1,33 +1,51 @@
 #!/usr/bin/env node
-// Drive the Cloudflare argotunnel Authorize click via CDP WebSocket (Task 588).
+// Drive the Cloudflare argotunnel consent page to a deterministic terminal
+// state via CDP WebSocket. Originally Task 588 (Authorize click from code,
+// collapsing a 180 s human-latency window). Task 855 widens the contract to
+// three states because the dashboard does not always render a button — once
+// the bound account has authorized this device's zones, navigating the same
+// (or a fresh) consent URL renders a Success modal verbatim, and the
+// pre-855 helper conflated "no button visible yet" with "no button will
+// ever appear" and exited error.
 //
-// Why this exists: setup-tunnel.sh navigates the VNC browser to the argotunnel
-// consent URL via `PUT /json/new?<url>`. That opens the page but does not
-// press the Authorize button. Pre-Task 588 the script then polled for
-// cert.pem for up to 180 seconds, waiting for a human click in VNC. This
-// helper does the click from code, collapsing the wait to ~1-3 seconds.
-//
-// Protocol: Chrome DevTools Protocol over WebSocket (https://chromedevtools.github.io/devtools-protocol/).
+// Protocol: Chrome DevTools Protocol over WebSocket
+// (https://chromedevtools.github.io/devtools-protocol/):
 //   1. GET http://127.0.0.1:9222/json/list → find the target with matching id;
 //      extract webSocketDebuggerUrl.
 //   2. Open WS, enable Page + Runtime domains.
 //   3. Wait for Page.loadEventFired (or observe document.readyState==='complete').
-//   4. Poll Runtime.evaluate every 200 ms for up to ~3 s, looking for a
-//      button or input[type=submit] whose trimmed text/value matches
-//      /^(authorize|connect)$/i. When found, click via JS (click() on the
-//      matched node). Exit 0 on success, 1 with structured stderr otherwise.
+//   4. Poll Runtime.evaluate every 200 ms for up to ~3 s, evaluating the
+//      tri-state matcher from _cdp-authorize-matcher.mjs. The matcher
+//      returns one of:
+//        - { kind:'button', descriptor } — Authorize/Connect button found,
+//                                          click() fired in-page; emit
+//                                          reason=clicked, exit 0.
+//        - { kind:'success' }            — Success modal text detected
+//                                          ("Cloudflared has installed a
+//                                          certificate"); cert is bound to
+//                                          the account. Emit reason=
+//                                          cert-already-installed, exit 0.
+//                                          Caller's existing cert-poll picks
+//                                          up the cert (callback is
+//                                          idempotent on this navigation).
+//        - null                          — Neither anchor matched yet; loop.
+//      After BUTTON_POLL_TIMEOUT_MS with no terminal match, emit
+//      reason=authorize-button-not-found, exit 1.
 //
 // Exit codes:
-//   0 - clicked successfully
-//   1 - authorize-button-not-found (the happy-path loud failure)
+//   0 - terminal success (reason=clicked OR reason=cert-already-installed)
+//   1 - authorize-button-not-found (loud failure — button AND modal absent)
 //   2 - cdp-ws-unreachable or node-websocket-unavailable
 //   3 - target-not-found (the target_id isn't in /json/list)
 //   4 - click-evaluate-threw (Runtime.evaluate returned wasThrown=true)
 //   5 - protocol-error (malformed CDP response)
 //
-// Each structured failure prints ONE line to stdout in phase_line-compatible
-// shape so setup-tunnel.sh's tee_subprocess picks it up into the stream log:
+// Stdout contract (read by setup-tunnel.sh's awk-based reason parser):
 //   cdp-authorize result=<ok|error> reason=<…> elapsed_ms=<…> [detail=<…>]
+// Exactly ONE such line per invocation; the wrapper takes the LAST
+// `result=ok` line via awk so future debug-line additions cannot mis-route.
+
+import { MATCH_EXPR } from './_cdp-authorize-matcher.mjs';
 
 const CDP_HOST = '127.0.0.1';
 const CDP_PORT = 9222;
@@ -211,35 +229,16 @@ try {
   die(1, 'page-load-timeout', { detail: err.message, elapsed_ms: Date.now() - started });
 }
 
-// Poll for the Authorize button. The expression finds the first
-// button/input[type=submit] whose trimmed textContent/value matches
-// /^(authorize|connect)$/i, clicks it, and returns a descriptor. Returns
-// null when no match yet.
-const CLICK_EXPR = `
-(() => {
-  const candidates = Array.from(document.querySelectorAll('button, input[type="submit"]'));
-  const match = candidates.find((el) => {
-    const text = (el.textContent ?? el.value ?? '').trim();
-    return /^(authorize|connect)$/i.test(text) && !el.disabled;
-  });
-  if (!match) return null;
-  const descriptor = {
-    tag: match.tagName.toLowerCase(),
-    text: (match.textContent ?? match.value ?? '').trim().slice(0, 40),
-    disabled: Boolean(match.disabled),
-  };
-  match.click();
-  return descriptor;
-})()
-`;
-
-const clickDeadline = Date.now() + BUTTON_POLL_TIMEOUT_MS;
-let clicked = null;
-while (Date.now() < clickDeadline) {
+// Poll the consent page until one of the three terminal states resolves.
+// MATCH_EXPR is built from _cdp-authorize-matcher.mjs's findMatch so the
+// JSDOM unit tests and the live CDP path execute literally identical logic.
+const matchDeadline = Date.now() + BUTTON_POLL_TIMEOUT_MS;
+let matched = null;
+while (Date.now() < matchDeadline) {
   let r;
   try {
     r = await send('Runtime.evaluate', {
-      expression: CLICK_EXPR,
+      expression: MATCH_EXPR,
       returnByValue: true,
       awaitPromise: false,
     });
@@ -253,22 +252,33 @@ while (Date.now() < clickDeadline) {
     });
   }
   const val = r?.result?.value;
-  if (val && typeof val === 'object') {
-    clicked = val;
+  if (val && typeof val === 'object' && (val.kind === 'button' || val.kind === 'success')) {
+    matched = val;
     break;
   }
   await new Promise((res) => setTimeout(res, BUTTON_POLL_INTERVAL_MS));
 }
 
-if (!clicked) {
+if (!matched) {
   die(1, 'authorize-button-not-found', { elapsed_ms: Date.now() - started });
 }
 
-emit('ok', 'clicked', {
-  tag: clicked.tag,
-  text: clicked.text,
-  elapsed_ms: Date.now() - started,
-});
+if (matched.kind === 'button') {
+  const d = matched.descriptor ?? {};
+  emit('ok', 'clicked', {
+    tag: d.tag,
+    text: d.text,
+    elapsed_ms: Date.now() - started,
+  });
+} else {
+  // matched.kind === 'success' — Success modal text is on the page; the
+  // bound account already has a cert. Caller drops into the cert-poll loop;
+  // the in-flight cloudflared subprocess receives the idempotent callback
+  // and writes ~/.cloudflared/cert.pem.
+  emit('ok', 'cert-already-installed', {
+    elapsed_ms: Date.now() - started,
+  });
+}
 
 try { ws.close(); } catch { /* best-effort */ }
 process.exit(0);

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

@@ -60,22 +60,74 @@ CFG_DIR="${HOME}/.${BRAND}/cloudflared"
 mkdir -p "${CFG_DIR}"
 
 # --------------------------------------------------------------------------
-# Step 1: OAuth login (only if cert.pem missing). Corresponds to runbook Step 1.
+# Step 1: OAuth login. Corresponds to runbook Step 1.
 #
-# Control flow, rewritten per Task 556:
+# Step 1 is a state machine over three observable variables — brand-scoped
+# cert path, default cert path, and the helper's outcome (Task 855):
+#
+#   ${CFG_DIR}/cert.pem present                   → Step 1 already done; skip.
+#   ${CFG_DIR}/cert.pem missing                AND
+#     ~/.cloudflared/cert.pem present             → pre-flight: a prior run
+#                                                   reached the OAuth callback
+#                                                   but failed before the mv;
+#                                                   promote and skip the
+#                                                   helper. Idempotent.
+#   both missing                                  → spawn cloudflared, drive
+#                                                   the consent page via CDP,
+#                                                   poll for cert.pem, mv.
+#
+# Control flow when both certs are missing (Task 556 / 588 / 855):
 #   1. CDP precheck on 127.0.0.1:9222 — loud failure if Chromium isn't up.
 #   2. Spawn cloudflared with stdout+stderr teed line-by-line to
 #      $STREAM_LOG_PATH with prefix [script:setup-tunnel:cloudflared]
 #      (Task 605's chat-surface namespace — see _stream-log.sh header).
 #   3. Extract the authorize URL with a tolerant regex as it streams.
 #   4. Drive the VNC Chromium to that URL via CDP `PUT /json/new?<url>`.
-#   5. Wait for ~/.cloudflared/cert.pem to land with bounded timeout.
-#   6. Move cert.pem into the brand-scoped path.
+#   5. Run _cdp-authorize.mjs — tri-state matcher returns one of:
+#        reason=clicked                  → button matched + clicked
+#        reason=cert-already-installed   → Success modal detected
+#        reason=authorize-button-not-found → loud failure, exit 1
+#      (a)+(b) drop into the cert-pem poll; (c) bubbles up.
+#   6. Wait for ~/.cloudflared/cert.pem to land with bounded timeout.
+#   7. Move cert.pem into the brand-scoped path.
 #
-# Every branch exits 1 loudly naming the failure — no silent retries,
+# Every failure branch exits 1 loudly naming the cause — no silent retries,
 # no xdg-open race, no cloudflared-internal browser-spawn path.
 # --------------------------------------------------------------------------
 
+# Pre-flight cert-promotion (Task 855). When ${CFG_DIR}/cert.pem is missing
+# but the OAuth-default ~/.cloudflared/cert.pem is present, a prior run
+# reached the cloudflared callback but did not survive to the brand-scoped
+# mv at the end of Step 1. The cert is bound to the account already; the
+# only remediation is the move. Doing it before re-spawning cloudflared is
+# what stops Step 1 from looping forever on a dashboard that has moved past
+# a button-bearing state.
+#
+# The mv exit code is checked: if it fails (EACCES, ENOSPC, weird FS state),
+# loud-fail with reason=cert-promote-failed instead of pretending Step 1
+# succeeded — the next steps would die opaquely on the missing brand cert.
+# stderr is captured into the phase_line so the operator sees the actual
+# failure cause (mv exit-code 1 alone cannot disambiguate EACCES from ENOSPC).
+if [ ! -f "${CFG_DIR}/cert.pem" ] && [ -f "${HOME}/.cloudflared/cert.pem" ]; then
+  MV_ERR="$(mktemp -t maxy-cert-promote-err.XXXXXX)"
+  if mv "${HOME}/.cloudflared/cert.pem" "${CFG_DIR}/cert.pem" 2>"${MV_ERR}"; then
+    rm -f "${MV_ERR}"
+    phase_line setup-tunnel step=oauth-login result=ok \
+      reason=cert-promoted-from-default-path waited="0s"
+  else
+    MV_RC=$?
+    MV_STDERR="$(tr '\n' ' ' < "${MV_ERR}" 2>/dev/null | head -c 200 || echo unavailable)"
+    rm -f "${MV_ERR}"
+    phase_line setup-tunnel step=oauth-login result=error \
+      reason=cert-promote-failed mv_rc="${MV_RC}" stderr="${MV_STDERR}" \
+      from="${HOME}/.cloudflared/cert.pem" to="${CFG_DIR}/cert.pem"
+    echo "ERROR: failed to promote ~/.cloudflared/cert.pem to ${CFG_DIR}/cert.pem (mv exit=${MV_RC})." >&2
+    echo "       mv stderr: ${MV_STDERR}" >&2
+    echo "       Step 1 cannot proceed without the cert in the brand-scoped path." >&2
+    exit 1
+  fi
+fi
+
 if [ ! -f "${CFG_DIR}/cert.pem" ]; then
   phase_line setup-tunnel step=oauth-login cert_path="${CFG_DIR}/cert.pem" display="${DISPLAY:-:99}"
 
@@ -215,22 +267,61 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
     echo "ERROR: _cdp-authorize.mjs helper missing or not executable at ${AUTH_HELPER}" >&2
     exit 1
   fi
-  # tee_subprocess pipes the helper's cdp-authorize result= line into the
-  # stream log under the setup-tunnel:cdp-click tag so the chat UI renders
-  # the click outcome in real time. Exit code drives control flow.
-  if tee_subprocess setup-tunnel:cdp-click -- \
-      node "${AUTH_HELPER}" "${CDP_TARGET_ID}"; then
-    phase_line setup-tunnel step=oauth-login result=authorize-clicked \
-      target_id="${CDP_TARGET_ID}"
+  # tee_subprocess_capture pipes the helper's `cdp-authorize result=…` line
+  # into the stream log under the setup-tunnel:cdp-click tag (live-tailable)
+  # AND through this shell's stdout so the wrapper can capture it for the
+  # tri-state reason discriminator (Task 855). The helper writes exactly
+  # one such line per invocation and exits; the shape is its contract:
+  #   `cdp-authorize result=<ok|error> reason=<token> [k=v …]`.
+  # The wrapper's awk takes the LAST `cdp-authorize result=ok ` line so that
+  # any future emit() additions cannot mis-route the discriminator — the
+  # success line is always the last one before exit.
+  HELPER_OUT="$(mktemp -t maxy-cdp-authorize-out.XXXXXX)"
+  if tee_subprocess_capture setup-tunnel:cdp-click -- \
+      node "${AUTH_HELPER}" "${CDP_TARGET_ID}" \
+      > "${HELPER_OUT}"; then
+    HELPER_REASON="$(awk '/^cdp-authorize result=ok / {m=$0} END {if (m) {match(m, /reason=[a-z0-9-]+/); print substr(m, RSTART+7, RLENGTH-7)}}' "${HELPER_OUT}")"
+    rm -f "${HELPER_OUT}"
+    case "${HELPER_REASON}" in
+      clicked)
+        phase_line setup-tunnel step=browser-drive result=ok \
+          reason=clicked target_id="${CDP_TARGET_ID}"
+        ;;
+      cert-already-installed)
+        # The dashboard rendered the Success modal — the bound account
+        # already has a cert. The OAuth callback URL was exercised by this
+        # navigation, so the in-flight cloudflared subprocess receives the
+        # idempotent callback and writes ~/.cloudflared/cert.pem; the poll
+        # below picks it up.
+        phase_line setup-tunnel step=browser-drive result=ok \
+          reason=cert-already-installed target_id="${CDP_TARGET_ID}"
+        ;;
+      *)
+        # Helper exited 0 but emitted a reason this wrapper does not
+        # recognise — protocol drift between helper and wrapper. Loud-fail
+        # rather than silently fall through to the cert-poll, which would
+        # mask the cause if the cert never lands.
+        kill "${CF_PIPELINE_PID}" 2>/dev/null || true
+        phase_line setup-tunnel step=browser-drive result=error \
+          reason=helper-unknown-success-reason raw="${HELPER_REASON:-empty}"
+        echo "ERROR: CDP helper exited 0 with unrecognised reason: ${HELPER_REASON:-empty}" >&2
+        echo "       Expected reason=clicked or reason=cert-already-installed." >&2
+        echo "       Helper / wrapper protocol drift — investigate stream log." >&2
+        exit 1
+        ;;
+    esac
   else
     CLICK_RC=$?
+    rm -f "${HELPER_OUT}"
     kill "${CF_PIPELINE_PID}" 2>/dev/null || true
-    # Helper exit codes: 1=authorize-button-not-found (loud, expected failure
-    # mode when the VNC browser isn't signed into Cloudflare), 2=cdp-ws-unreachable,
-    # 3=target-not-found, 4=click-evaluate-threw, 5=protocol-error. All are
-    # final — no retry, no silent fallback. Map the exit code 1:1 to a reason
-    # string so the stream-log `reason=<…>` is greppable by exact cause; a
-    # single catch-all reason would defeat the observability contract.
+    # Helper exit codes (mapped 1:1 to reason= so stream-log grep is precise;
+    # a catch-all reason would defeat the observability contract):
+    #   1 = authorize-button-not-found (loud — neither button nor success
+    #       modal matched before BUTTON_POLL_TIMEOUT_MS; the form surfaces
+    #       a verbatim quote of references/dashboard-guide.md "Authorise a
+    #       new tunnel" so the operator can recover without SSH).
+    #   2 = cdp-ws-unreachable, 3 = target-not-found, 4 = click-evaluate-threw,
+    #   5 = protocol-error. All are final — no retry, no silent fallback.
     case "${CLICK_RC}" in
       1) CLICK_REASON=authorize-button-not-found ;;
       2) CLICK_REASON=cdp-ws-unreachable ;;
@@ -242,8 +333,13 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
     phase_line setup-tunnel step=browser-drive result=error \
       reason="${CLICK_REASON}" click_rc="${CLICK_RC}"
     echo "ERROR: CDP-driven Authorize click failed (helper exit=${CLICK_RC}, reason=${CLICK_REASON})." >&2
-    echo "       If the VNC browser is not signed into Cloudflare, sign in manually," >&2
-    echo "       close the sign-in tab, and re-run setup — or run ~/reset-tunnel.sh first." >&2
+    if [ "${CLICK_REASON}" = "authorize-button-not-found" ]; then
+      echo "       The dashboard did not present an Authorize button or a Success modal." >&2
+      echo "       The form will surface the dashboard click-path for manual recovery." >&2
+    else
+      echo "       The CDP helper failed before reaching a terminal page state." >&2
+      echo "       Re-run setup — or run ~/reset-tunnel.sh first if state is corrupt." >&2
+    fi
     exit 1
   fi
   fi  # end CDP-available branch (Task 664)
@@ -281,7 +377,7 @@ 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 authorize-clicked
+    # 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 Task 588 forbids.
@@ -294,7 +390,7 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
   done
 
   mv "${HOME}/.cloudflared/cert.pem" "${CFG_DIR}/cert.pem"
-  phase_line setup-tunnel step=oauth-login result=cert-received \
+  phase_line setup-tunnel step=oauth-login result=ok \
     path="${CFG_DIR}/cert.pem" waited="${LOGIN_WAIT}s"
 fi
 

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

@@ -22,6 +22,8 @@ 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 (Task 558) — 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 three observable variables: the brand-scoped cert path (`${CFG_DIR}/cert.pem`), the OAuth-default cert path (`~/.cloudflared/cert.pem`), and the consent-page DOM via the CDP helper `_cdp-authorize.mjs` (Task 855). 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 helper polls `dash.cloudflare.com/argotunnel` and resolves to one of three terminal outcomes — `reason=clicked` (button matched and clicked), `reason=cert-already-installed` (Success modal text detected — the bound account already has a cert, callback is idempotent so the in-flight cloudflared subprocess writes the cert anyway), or `reason=authorize-button-not-found` (neither anchor matched; loud failure, exit 1). The first two paths drop into the existing brand-scoped cert poll; the third surfaces a remediation card in the form so the operator can complete the consent click in their own browser without SSH or `~/reset-tunnel.sh`.
+
 ### How inputs reach the script
 
 Inputs arrive through the `cloudflare-setup-form` component, not agent Q&A. The onboarding skill renders the form, the user submits admin/public/apex labels and the admin password in one action, and the `/api/admin/cloudflare/setup` endpoint runs (in this order):
@@ -50,6 +52,8 @@ The agent does not invoke the script directly during onboarding — the endpoint
 
 The endpoint returns `{ ok: false, field: "script", message, output }` and the form surfaces the error inline. Relay the output to the user, name the exit code, and cite `references/reset-guide.md` for the next action. Offer to re-render the form after any manual steps the script's error output named. Do not attempt a second invocation outside the form, a Playwright-driven dashboard inspection, or an alternative `cloudflared` command sequence. The discipline rule below applies.
 
+When the failure reason is `authorize-button-not-found` (Task 855), the form renders a verbatim quote of `references/dashboard-guide.md` § "Authorise a new tunnel (pick the right zone)" alongside a "Try again" button — the operator completes the consent click in their own browser, then re-submits the same form. No agent action is required; relay the form's chat acknowledgement when it arrives. Do not suggest `~/reset-tunnel.sh` for this reason — the cert path is intact and a fresh consent click is the only remediation needed.
+
 ---
 
 ## 2. Manual fallback — `references/manual-setup.md`