@rubytech/create-maxy 1.0.799 → 1.0.801

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.799",
+  "version": "1.0.801",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy": "./dist/index.js"

package/payload/platform/plugins/admin/hooks/__tests__/archive-ingest-surface-gate.test.sh

@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+# Regression test for archive-ingest-surface-gate.sh (Task 855).
+#
+# Covers:
+#   Preserved-from-Task-846:
+#     1. Edit on /platform/plugins/<x>/lib/* → BLOCKED
+#     2. Edit on benign path → ALLOWED
+#     3. Bash with `npx vitest`/`bun test`/`npm test` → BLOCKED
+#     4. PostToolUse on whatsapp-export-parse with isError:true sets flag
+#     5. Subsequent PreToolUse on ANY tool → BLOCKED
+#     6. UserPromptSubmit clears flag → normal allow resumes
+#     7. PostToolUse with isError:false → flag absent
+#     8. Stale flag (>600s) auto-clears
+#   New (Task 855):
+#     A. PreToolUse mcp__memory__whatsapp-export-parse → BLOCKED
+#     B. PreToolUse mcp__memory__whatsapp-export-insight-write → BLOCKED
+#     C. PreToolUse mcp__memory__memory-archive-write w/ archiveType=whatsapp-export → BLOCKED
+#     D. PreToolUse mcp__memory__memory-archive-write w/ archiveType=linkedin-connections → ALLOWED
+#     E. PreToolUse Bash invoking whatsapp-ingest.sh → ALLOWED
+#     F. Default-allow emits a [archive-ingest-gate] decision=allow log line
+
+set -u
+
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/archive-ingest-surface-gate.sh"
+if [[ ! -x "$HOOK" ]]; then
+  echo "FAIL: $HOOK not executable" >&2
+  exit 1
+fi
+
+STATE_DIR=$(mktemp -d)
+export ARCHIVE_INGEST_GATE_STATE_DIR="$STATE_DIR"
+FLAG_FILE="$STATE_DIR/archive-ingest-parse-error.flag"
+
+cleanup() { rm -rf "$STATE_DIR"; }
+trap cleanup EXIT
+
+PASS=0
+FAIL=0
+
+run_case() {
+  local name="$1" stdin="$2" expected_exit="$3"
+  local actual_exit
+  printf '%s' "$stdin" | bash "$HOOK" >/dev/null 2>/dev/null
+  actual_exit=$?
+  if [[ "$actual_exit" -eq "$expected_exit" ]]; then
+    echo "PASS: $name (exit=$actual_exit)"
+    PASS=$((PASS + 1))
+  else
+    echo "FAIL: $name (expected exit=$expected_exit, got=$actual_exit)" >&2
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+# Preserved cases ---------------------------------------------------------
+
+run_case "Edit on platform/plugins/whatsapp-import/lib/src/parse-export.ts → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Edit","tool_input":{"file_path":"/Users/x/repo/platform/plugins/whatsapp-import/lib/src/parse-export.ts","old_string":"a","new_string":"b"}}' \
+  2
+
+run_case "Edit on README.md → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Edit","tool_input":{"file_path":"/Users/x/repo/README.md","old_string":"a","new_string":"b"}}' \
+  0
+
+run_case "Bash 'npx vitest run' → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"npx vitest run parse-export.test.ts"}}' \
+  2
+
+run_case "Bash 'ls -la' → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"ls -la"}}' \
+  0
+
+run_case "Bash 'bun test' → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"bun test"}}' \
+  2
+
+run_case "Bash 'npm test' → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"npm test"}}' \
+  2
+
+# New (Task 855) cases ----------------------------------------------------
+
+run_case "PreToolUse mcp__memory__whatsapp-export-parse → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"mcp__memory__whatsapp-export-parse","tool_input":{"filePath":"/tmp/_chat.txt","accountId":"acct1","timezone":"Europe/London"}}' \
+  2
+
+run_case "PreToolUse mcp__memory__whatsapp-export-insight-write → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"mcp__memory__whatsapp-export-insight-write","tool_input":{"kind":"MENTIONS","name":"Joel"}}' \
+  2
+
+run_case "PreToolUse memory-archive-write w/ archiveType=whatsapp-export → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"mcp__memory__memory-archive-write","tool_input":{"archiveType":"whatsapp-export","ownerNodeId":"x","accountId":"a","rows":[]}}' \
+  2
+
+run_case "PreToolUse memory-archive-write w/ archiveType=linkedin-connections → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"mcp__memory__memory-archive-write","tool_input":{"archiveType":"linkedin-connections","ownerNodeId":"x","accountId":"a","rows":[]}}' \
+  0
+
+# Bypass attempts (Task 855 code-review C1): nested archiveType in rows[0]
+# or conversation must NOT defeat the block. The gate must read the
+# top-level tool_input.archiveType, not the first textual occurrence.
+run_case "BYPASS: nested rows[0].archiveType=linkedin + top-level archiveType=whatsapp-export → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"mcp__memory__memory-archive-write","tool_input":{"rows":[{"archiveType":"linkedin-connections"}],"archiveType":"whatsapp-export","ownerNodeId":"x","accountId":"a"}}' \
+  2
+
+run_case "BYPASS: conversation.archiveType=linkedin + top-level archiveType=whatsapp-export → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"mcp__memory__memory-archive-write","tool_input":{"conversation":{"archiveType":"linkedin-connections","conversationId":"x"},"archiveType":"whatsapp-export","ownerNodeId":"x","accountId":"a","rows":[]}}' \
+  2
+
+# Plugin-source-edit path block must read tool_input.file_path top-level,
+# not a nested file_path in old_string/new_string.
+run_case "BYPASS: nested file_path in old_string + top-level file_path in lib/* → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Edit","tool_input":{"file_path":"/repo/platform/plugins/whatsapp-import/lib/src/parse-export.ts","old_string":"file_path:/safe/path","new_string":"x"}}' \
+  2
+
+run_case "PreToolUse Bash invoking whatsapp-ingest.sh → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"bash platform/plugins/whatsapp-import/bin/whatsapp-ingest.sh /tmp/chat.zip --owner-element-id 4:abc:1 --scope admin"}}' \
+  0
+
+# Default-allow log-line check
+LOG=$(printf '%s' '{"hook_event_name":"PreToolUse","tool_name":"Read","tool_input":{"file_path":"/tmp/foo"}}' | bash "$HOOK" 2>&1 1>/dev/null)
+if printf '%s' "$LOG" | grep -q '\[archive-ingest-gate\] decision=allow tool=Read reason=default'; then
+  echo "PASS: default-allow emits decision-log line"
+  PASS=$((PASS + 1))
+else
+  echo "FAIL: default-allow missing decision-log line. Got: $LOG" >&2
+  FAIL=$((FAIL + 1))
+fi
+
+# Block-log line includes command field for Bash
+LOG=$(printf '%s' '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"npx vitest run"}}' | bash "$HOOK" 2>&1 1>/dev/null)
+if printf '%s' "$LOG" | grep -q '\[archive-ingest-gate\] decision=block tool=Bash reason=test-runner'; then
+  echo "PASS: block emits decision-log line with reason"
+  PASS=$((PASS + 1))
+else
+  echo "FAIL: block missing decision-log line. Got: $LOG" >&2
+  FAIL=$((FAIL + 1))
+fi
+
+# Parse-error flag lifecycle (preserved)
+rm -f "$FLAG_FILE"
+run_case "PostToolUse parse-error sets flag (exit 0)" \
+  '{"hook_event_name":"PostToolUse","tool_name":"mcp__memory__whatsapp-export-parse","tool_input":{"filePath":"_chat.txt"},"tool_response":{"isError":true,"content":[{"type":"text","text":"parse-error file=_chat.txt line=1 reason=not-a-_chat.txt"}]}}' \
+  0
+[[ -f "$FLAG_FILE" ]] && { echo "PASS: parse-error flag created"; PASS=$((PASS+1)); } \
+                      || { echo "FAIL: parse-error flag NOT created" >&2; FAIL=$((FAIL+1)); }
+
+run_case "PreToolUse Read after parse-error → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Read","tool_input":{"file_path":"/tmp/foo"}}' \
+  2
+
+run_case "UserPromptSubmit clears flag" \
+  '{"hook_event_name":"UserPromptSubmit","prompt":"retry"}' \
+  0
+[[ ! -f "$FLAG_FILE" ]] && { echo "PASS: UserPromptSubmit cleared flag"; PASS=$((PASS+1)); } \
+                        || { echo "FAIL: UserPromptSubmit did NOT clear flag" >&2; FAIL=$((FAIL+1)); }
+
+run_case "PreToolUse Read after clearance → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Read","tool_input":{"file_path":"/tmp/foo"}}' \
+  0
+
+# Stale flag auto-clears
+PAST=$(( $(date -u +%s) - 700 ))
+echo "$PAST" > "$FLAG_FILE"
+run_case "Stale flag auto-clears, PreToolUse Read → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Read","tool_input":{"file_path":"/tmp/foo"}}' \
+  0
+
+# PostToolUse parse-success leaves flag absent
+rm -f "$FLAG_FILE"
+run_case "PostToolUse parse-success (isError:false) does NOT set flag" \
+  '{"hook_event_name":"PostToolUse","tool_name":"mcp__memory__whatsapp-export-parse","tool_input":{"filePath":"_chat.txt"},"tool_response":{"isError":false,"content":[{"type":"text","text":"{\"parsedLines\":[]}"}]}}' \
+  0
+[[ ! -f "$FLAG_FILE" ]] && { echo "PASS: parse-success leaves flag absent"; PASS=$((PASS+1)); } \
+                        || { echo "FAIL: parse-success incorrectly created flag" >&2; FAIL=$((FAIL+1)); }
+
+# Fail-closed terminal check
+if grep -q '\[ -t 0 \]' "$HOOK"; then
+  echo "PASS: fail-closed terminal check is present"
+  PASS=$((PASS + 1))
+else
+  echo "FAIL: fail-closed terminal check missing" >&2
+  FAIL=$((FAIL + 1))
+fi
+
+echo
+echo "──────── archive-ingest-surface-gate test summary ────────"
+echo "PASS: $PASS"
+echo "FAIL: $FAIL"
+
+[[ "$FAIL" -gt 0 ]] && exit 1
+exit 0

package/payload/platform/plugins/admin/hooks/archive-ingest-surface-gate.sh

@@ -0,0 +1,207 @@
+#!/usr/bin/env bash
+# Archive-ingest surface gate (Task 855; supersedes Task 846).
+#
+# Five enforcements, one script — phase decided by `hook_event_name` on stdin.
+# Task 855 narrows the database-operator subagent's effective surface during
+# WhatsApp archive ingestion to exactly one Bash entry
+# (`whatsapp-import/bin/whatsapp-ingest.sh`) plus read-only neighbours, by
+# blocking the legacy MCP deviation tools mechanically.
+#
+# 1. PreToolUse on the three legacy WhatsApp MCP tools — BLOCK unconditionally.
+#    The single deterministic Bash entry (Task 855) is the only supported path
+#    for `archiveType=whatsapp-export`. The legacy MCP tools' source remains
+#    until cleanup; the gate stops them being invoked.
+#       mcp__memory__whatsapp-export-parse
+#       mcp__memory__whatsapp-export-insight-write
+#       mcp__memory__memory-archive-write           (only when `archiveType` is
+#                                                    `whatsapp-export`; LinkedIn
+#                                                    and other archiveTypes pass
+#                                                    through unchanged.)
+#
+# 2. PreToolUse Edit/Write/NotebookEdit: deny writes under
+#    `*platform/plugins/*/lib/*` (parser/CSV-shape source for any *-import or
+#    *-export plugin). Preserved from Task 846 — defence in depth even though
+#    the database-operator template no longer lists Edit/Write tools.
+#
+# 3. PreToolUse Bash: deny commands invoking JavaScript test runners
+#    (vitest|bun test|npm test|npx jest|node .*vitest). Preserved from Task 846.
+#
+# 4. Parse-error gate: PostToolUse on any `mcp__*__*-export-parse` /
+#    `mcp__*__*-import-parse` tool whose `tool_response.isError == true`
+#    writes a flag file. Subsequent PreToolUse on ANY tool blocks until
+#    UserPromptSubmit clears the flag. A 600s TTL is the cross-session safety
+#    net. Preserved from Task 846 because LinkedIn and future per-source archive
+#    parsers still use the legacy MCP path until they migrate to their own
+#    deterministic Bash entries.
+#
+# 5. Logging: every PreToolUse decision emits one line in the format
+#       [archive-ingest-gate] decision=<allow|block> tool=<name> reason=<r> ...
+#    so the operator can grep the full decision trail for one ingest from
+#    server.log alongside the [whatsapp-ingest] script lines.
+#
+# Exit codes follow Claude Code hook protocol: 0 = allow, 2 = block (stderr
+# message shown to the agent). Fail-closed on terminal stdin to match
+# pre-tool-use.sh.
+
+set -uo pipefail
+
+# Read stdin — fail closed if attached to a terminal (no JSON envelope coming).
+if [ -t 0 ]; then
+  echo "Blocked: archive-ingest-surface-gate received no stdin (cannot inspect tool call). Failing closed." >&2
+  exit 2
+fi
+INPUT=$(cat)
+
+# ----- Resolve account dir for state file ----------------------------------
+HOOK_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
+PLATFORM_ROOT_RESOLVED="${HOOK_DIR}/../../.."
+ACCOUNTS_DIR="${PLATFORM_ROOT_RESOLVED}/../data/accounts"
+ACCOUNT_DIR=""
+if [ -d "$ACCOUNTS_DIR" ]; then
+  ACCOUNT_DIR=$(find "$ACCOUNTS_DIR" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | head -1)
+fi
+STATE_DIR="${ARCHIVE_INGEST_GATE_STATE_DIR:-${ACCOUNT_DIR}/state}"
+FLAG_FILE="${STATE_DIR}/archive-ingest-parse-error.flag"
+TTL_SECONDS=600
+
+# ----- Parse fields from stdin ---------------------------------------------
+HOOK_EVENT=$(printf '%s' "$INPUT" | grep -o '"hook_event_name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
+TOOL_NAME=$(printf '%s' "$INPUT" | grep -o '"tool_name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
+
+# ============================================================================
+# UserPromptSubmit — clear the parse-error flag.
+# ============================================================================
+if [ "$HOOK_EVENT" = "UserPromptSubmit" ]; then
+  if [ -f "$FLAG_FILE" ]; then
+    rm -f "$FLAG_FILE" 2>/dev/null
+    echo "[archive-ingest-gate] cleared reason=user-prompt-submit" >&2
+  fi
+  exit 0
+fi
+
+# ============================================================================
+# PostToolUse — record parse-error from any *-export-parse / *-import-parse.
+# ============================================================================
+if [ "$HOOK_EVENT" = "PostToolUse" ]; then
+  case "$TOOL_NAME" in
+    mcp__*__*-export-parse|mcp__*__*-import-parse)
+      if printf '%s' "$INPUT" | grep -Eq '"isError"[[:space:]]*:[[:space:]]*true'; then
+        mkdir -p "$STATE_DIR" 2>/dev/null
+        date -u +%s > "$FLAG_FILE" 2>/dev/null
+        echo "[archive-ingest-gate] surfaced reason=parse-error tool=${TOOL_NAME}" >&2
+      fi
+      ;;
+  esac
+  exit 0
+fi
+
+# ============================================================================
+# PreToolUse — five independent blocks.
+# ============================================================================
+if [ "$HOOK_EVENT" != "PreToolUse" ]; then
+  exit 0
+fi
+
+# Helper: emit a single decision-log line + remediation message, then exit.
+# Args: $1=decision (allow|block) $2=reason $3=remediation message
+emit_decision() {
+  local decision="$1" reason="$2" remediation="$3" cmd="${4:-}"
+  local cmd_field=""
+  if [ -n "$cmd" ]; then
+    # Sanitise: strip control chars, take first 60 chars.
+    cmd_field=" command=\"$(printf '%s' "$cmd" | tr -d '\000-\037' | cut -c1-60)\""
+  fi
+  echo "[archive-ingest-gate] decision=${decision} tool=${TOOL_NAME} reason=${reason}${cmd_field}" >&2
+  if [ "$decision" = "block" ]; then
+    echo "$remediation" >&2
+    exit 2
+  fi
+}
+
+# --- Block 1: post-parse-error gate (applies to ALL tools) -----------------
+if [ -f "$FLAG_FILE" ]; then
+  FLAG_TS=$(cat "$FLAG_FILE" 2>/dev/null | head -1)
+  NOW=$(date -u +%s)
+  if [ -n "$FLAG_TS" ] && [ "$FLAG_TS" -gt 0 ] 2>/dev/null; then
+    AGE=$(( NOW - FLAG_TS ))
+    if [ "$AGE" -lt "$TTL_SECONDS" ]; then
+      emit_decision "block" "post-parse-error age_s=${AGE}" \
+        "Blocked: an archive-parser MCP tool returned isError=true earlier in this turn. The subagent's next action must be a user-facing message naming the parse-error and yielding back to the operator. Further tool calls are blocked until the operator submits a new prompt."
+    fi
+    rm -f "$FLAG_FILE" 2>/dev/null
+  else
+    rm -f "$FLAG_FILE" 2>/dev/null
+  fi
+fi
+
+# --- Block 2: legacy WhatsApp MCP tools — denied unconditionally ----------
+case "$TOOL_NAME" in
+  mcp__memory__whatsapp-export-parse|mcp__memory__whatsapp-export-insight-write)
+    emit_decision "block" "denied-mcp-legacy" \
+      "Blocked: ${TOOL_NAME} is the Task 804 legacy path. Task 855 ships the deterministic Bash entry — invoke 'bash platform/plugins/whatsapp-import/bin/whatsapp-ingest.sh <archive> --owner-element-id <id> --scope <admin|public>' once. Parse, archive-write, and insight all run in-process; do not call legacy MCP tools."
+    ;;
+esac
+
+# Helper: extract a top-level field from `tool_input` via python3 — never via
+# grep+sed against the raw JSON, which would pick the first textual occurrence
+# including nested-object matches (`rows[0].archiveType`,
+# `conversation.archiveType`, etc.) and let a malicious payload bypass the
+# block. python3 is the project standard for JSON-aware hook parsing
+# (mirrors lane-gate.sh:31-46). On parse failure return empty string —
+# downstream block conditions skip cleanly.
+extract_tool_input_field() {
+  local field="$1"
+  printf '%s' "$INPUT" | python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    print(d.get('tool_input', {}).get('$field', ''))
+except Exception:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+# --- Block 3: memory-archive-write conditional on whatsapp-export -----------
+# LinkedIn and future archiveTypes flow unchanged through memory-archive-write.
+# Only `archiveType=whatsapp-export` is now restricted to the script path.
+if [ "$TOOL_NAME" = "mcp__memory__memory-archive-write" ]; then
+  ARCHIVE_TYPE=$(extract_tool_input_field archiveType)
+  if [ "$ARCHIVE_TYPE" = "whatsapp-export" ]; then
+    emit_decision "block" "denied-mcp-legacy archiveType=whatsapp-export" \
+      "Blocked: memory-archive-write with archiveType='whatsapp-export' is the Task 804 legacy path. Task 855 ships the deterministic Bash entry — invoke 'bash platform/plugins/whatsapp-import/bin/whatsapp-ingest.sh <archive> --owner-element-id <id> --scope <admin|public>' once. Other archiveTypes (linkedin-connections, …) flow through memory-archive-write unchanged."
+  fi
+fi
+
+# --- Block 4: plugin-source path block (Edit/Write/NotebookEdit) -----------
+case "$TOOL_NAME" in
+  Edit|Write|NotebookEdit)
+    FILE_PATH=$(extract_tool_input_field file_path)
+    case "$FILE_PATH" in
+      */platform/plugins/*/lib/*|platform/plugins/*/lib/*)
+        emit_decision "block" "plugin-source-edit path=${FILE_PATH}" \
+          "Blocked: ${TOOL_NAME} on ${FILE_PATH} is a platform plugin lib/ path. The database-operator subagent does not own plugin source; if a parser is broken, surface the parse-error to the operator and let them dispatch a code-edit task instead."
+        ;;
+    esac
+    ;;
+esac
+
+# --- Block 5: shell test-runner block (Bash) -------------------------------
+COMMAND=""
+if [ "$TOOL_NAME" = "Bash" ]; then
+  COMMAND=$(extract_tool_input_field command)
+  if printf '%s' "$COMMAND" | grep -Eq '(^|[[:space:]/])vitest($|[[:space:]])|(^|[[:space:]])bun[[:space:]]+test($|[[:space:]])|(^|[[:space:]])npm[[:space:]]+test($|[[:space:]])|(^|[[:space:]])npx[[:space:]]+jest($|[[:space:]])|node[[:space:]].*vitest'; then
+    emit_decision "block" "test-runner" \
+      "Blocked: Bash command invokes a JavaScript test runner (vitest/bun test/npm test/npx jest). The database-operator subagent does not run plugin tests; surface the parse-error to the operator." \
+      "$COMMAND"
+  fi
+fi
+
+# Default — allow. Emit a single-line decision log so successful invocations
+# leave a grep-able trail too. (Bash gets command field; other tools omit.)
+if [ "$TOOL_NAME" = "Bash" ]; then
+  emit_decision "allow" "default" "" "$COMMAND"
+else
+  emit_decision "allow" "default" ""
+fi
+
+exit 0

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)`;