@rubytech/create-maxy-code 0.1.0

package/payload/platform/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "maxy-platform",
+  "version": "0.1.0",
+  "private": true,
+  "workspaces": [
+    "plugins/*/mcp",
+    "services/*"
+  ],
+  "scripts": {
+    "build": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/oauth-llm/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p services/claude-session-manager/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
+    "build:lib": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/oauth-llm/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json",
+    "build:memory": "tsc -p plugins/memory/mcp/tsconfig.json",
+    "build:contacts": "tsc -p plugins/contacts/mcp/tsconfig.json",
+    "build:telegram": "tsc -p plugins/telegram/mcp/tsconfig.json",
+    "build:admin": "tsc -p plugins/admin/mcp/tsconfig.json",
+    "build:cloudflare": "tsc -p plugins/cloudflare/mcp/tsconfig.json",
+    "build:tasks": "tsc -p plugins/tasks/mcp/tsconfig.json",
+    "build:email": "tsc -p plugins/email/mcp/tsconfig.json",
+    "build:outlook": "tsc -p plugins/outlook/mcp/tsconfig.json",
+    "build:workflows": "tsc -p plugins/workflows/mcp/tsconfig.json",
+    "build:stubs": "tsc -p plugins/scheduling/mcp/tsconfig.json",
+    "build:replicate": "tsc -p plugins/replicate/mcp/tsconfig.json",
+    "build:claude-session-manager": "tsc -p services/claude-session-manager/tsconfig.json"
+  }
+}

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

@@ -0,0 +1,81 @@
+---
+name: admin
+description: "Platform administration plugin. Provides system-status, public-hostname (deterministic Cloudflare public-URL resolver — single call returning the operator's canonical hostname so agents never guess property names on :CloudflareHostname nodes), brand-settings, account-manage, account-update, admin-add, admin-remove, admin-list, admin-update-pin, agent-list, agent-config-read, logs-read, plugin-read, skill-load (one-call resolve+read for SKILL.md by skill name — the canonical primitive for loading a named skill; plugin-read remains the reader for references/* and PLUGIN.md), store-skill (deterministic write counterpart to plugin-read; persists operator-authored skills as plugin files under the active account), render-component, session-reset, session-resume, file-attach, wifi, and action-approval tools (action-pending, action-approve, action-reject, action-edit) for managing the Maxy platform."
+tools:
+  - system-status
+  - public-hostname
+  - brand-settings
+  - account-manage
+  - account-update
+  - admin-add
+  - admin-remove
+  - admin-list
+  - admin-update-pin
+  - agent-list
+  - agent-config-read
+  - logs-read
+  - plugin-read
+  - skill-load
+  - store-skill
+  - render-component
+  - session-reset
+  - session-resume
+  - file-attach
+  - action-pending
+  - action-approve
+  - action-reject
+  - action-edit
+hidden:
+  - remote-auth-status
+  - remote-auth-set-password
+  - anthropic-setup
+  - api-key-store
+  - api-key-verify
+  - onboarding-get
+  - onboarding-complete-step
+  - onboarding-step9-mode
+  - qr-generate
+  - wifi
+always: true
+embed: false
+---
+
+# Admin
+
+Platform management tools for both the admin and public agents. The `plugin-read` tool is available to the public agent (read-only) for loading plugin definitions and references. `skill-load skillName=<name>` is the canonical resolver+reader for SKILL.md by skill name — one call returns the body with brand placeholders substituted; `plugin-read` retains exclusive ownership of `references/*` and `PLUGIN.md` reads (both inherently plugin-scoped). All other tools are admin-only.
+
+Tools are available via the `admin` MCP server.
+
+**Three-store admin auth invariant.** `admin-add` writes to all three identity stores (`users.json` PIN auth at the persistent `~/{configDir}/users.json` location , `account.json` `admins[]` role, Neo4j `:AdminUser`/`:Person` graph identity) with per-leg `[admin-auth-store]` log lines plus the `[admins-write]` chokepoint line, and returns `is_error: true` on any leg failure naming what's already written. `admin-update-pin` writes `users.json` only and emits the same `[admin-auth-store]` line. **Single chokepoint:** every `users.json` + `account.json admins[]` mutation routes through `platform/lib/admins-write` (`writeAdminEntry` for admin-add/set-pin, `removeAdminFromAccount` for admin-remove); the static check `grep -rnE 'admins\.push\|config\.admins\s*=' platform/ \| grep -v lib/admins-write` returns 0. Direct `Edit`/`Write` on `account.json` is blocked at the `pre-tool-use` hook — mutations go through `account-update`, `plugin-toggle-enabled`, or the `admin-*` tools. **Install + boot invariants:** the installer and admin-server boot walk every account.json admins[] vs users.json; `[install-invariant]` / `[admin-invariant] direction=… userId=<id8> source=<file>` fires per divergence with a `check complete divergences=<n>` summary. Log-only — does not block. See `.docs/agents.md` § "Three-store admin auth invariant" for the full contract.
+
+**AdminUser graph stamp + boot self-heal.** The seed cypher in `platform/scripts/seed-neo4j.sh` stamps `:AdminUser.accountId` + `:AdminUser.role='owner'` ON CREATE so the graph-write gate's account-scoped MATCH succeeds on the first user-domain write. Admin-server boot additionally runs `platform/ui/app/lib/adminuser-self-heal.ts` to repair legacy nodes whose `accountId` or `role` is null — emits `[adminuser-self-heal] healed=<N> userId=<8> accountId=<8>` once per boot, idempotent. The `graph-write-gate` reject log gains a `subReason=` field (`no-admin-user-node` / `admin-user-no-accountid` / `no-business-or-personal-profile`) for operator diagnosis. See `.docs/agents.md` § "AdminUser graph stamp contract" for the full contract.
+
+`logs-read { type: "agent-stream" }` is the canonical name for the per-conversation tool-use/tool-result archive previously called `system`; both names work and the legacy alias is preserved.
+
+**Stream log is the primary diagnostic surface for an in-progress session.** Every stream log is named by sessionKey and the stream-log file exists from the first token. The single-writer mandate (2026-05-14) mechanically enforces this contract: the single writer module at [`platform/ui/app/lib/claude-agent/stream-log-writer.ts`](../../ui/app/lib/claude-agent/stream-log-writer.ts) owns every open of `claude-agent-stream-*.log`, opens the file lazily on the first SDK token byte (via `streamLog.writeToken`), and buffers pre-token markers in memory while duplicating them to `server.log` via `console.error` so zero-token sessions retain observability. The build gate `platform/ui/scripts/check-stream-log-writer.mjs` rejects any external `appendFileSync`/`createWriteStream` against the `claude-agent-stream-*` pattern outside the writer module, plus any `claude-agent-stream-${conversationId}` literal (the pre-1013 wrong-identifier signature that produced two files for one session on the Beacons Pi 2026-05-14). The first-token invariant is bound by `platform/scripts/__tests__/first-token-creates-stream-log.test.sh`: one operator turn, one token, `claude-agent-stream-<sessionKey>.log` exists and contains the token bytes after the byte returns to the operator. The parent-process console fan-out tee in [`platform/ui/app/lib/claude-agent/logging.ts`](../../ui/app/lib/claude-agent/logging.ts) appends every `[<tag>]`-prefixed `console.error` / `console.log` line to every active session's stream log alongside `server.log`. For diagnosing an in-session issue (WhatsApp inbound, Cloudflare action, persist write, baileys error), call `logs-read { sessionKey: "<…>" }` first — the stream log carries both the agent lifecycle AND the parent-process events that occurred during the session window. The `conversationId` parameter remains a legacy alias resolving to the same sessionKey-named file. `logs-read { type: "server" }` is the cross-session escape hatch for events outside any single session window.
+
+## Skills
+
+| Task | When to use | Reference |
+|------|-------------|-----------|
+| Manage public agents | User asks to create, edit, clone, list, preview, or delete a public agent | `skills/public-agent-manager/SKILL.md` |
+| Create a new skill | User asks to create, add, or teach the agent a new capability | `skills/skill-builder/SKILL.md` |
+| Review stream logs | Admin asks to review, diagnose, or analyse a Claude agent stream log | `skills/stream-log-review/SKILL.md` |
+| Set up business profile | Admin asks to set up, complete, or update business operational data | `skills/business-profile/SKILL.md` |
+| Generate a QR code | User asks to generate, create, or make a QR code from a URL, Wi-Fi details, contact, or text | `skills/qr-code/SKILL.md` |
+| Timezone queries | User asks for the time in another city, timezone conversion, UTC offset, or DST status | `skills/datetime/SKILL.md` |
+| Manage access grants | Admin asks to invite visitors, revoke or extend access, list who has access, or set an agent's access mode | `skills/access-manager/SKILL.md` |
+| Manage plugins and settings | User asks to install, enable, disable, or configure plugins, or change account settings | `skills/plugin-management/SKILL.md` |
+| Manage specialists | User asks to install or remove a specialist subagent, or activate/deactivate premium plugin agents | `skills/specialist-management/SKILL.md` |
+| Generate print-quality PDF | User asks to create a PDF document, one-pager, brochure, or any HTML intended for print/download | `skills/a4-print-documents/SKILL.md` |
+| Plain-English explanation | User asks to explain, define, or pre-empts ("explain in plain English", "what does X mean", "define X", "I don't understand", "what is this"), or admin is about to return a reply containing a term not in the operator's prior turn | `skills/plainly/SKILL.md` |
+
+## Hooks
+
+- `hooks/pre-tool-use.sh` — enforces admin agent write boundaries
+- `hooks/playwright-file-guard.sh` — rewrites file:// URLs to a backgrounded loopback http.server before Playwright sees them
+- `hooks/webfetch-preflight.mjs` — short-circuits WebFetch on JS-SPA shells with a structured `WEBFETCH_CANNOT_READ_JS_SPA` error so the agent surfaces a loud failure to the owner instead of paying the 60s extraction timeout. Fail-open on any internal error.
+
+## Failure-report breadcrumbs
+
+`POST /api/admin/sse-telemetry` and `POST /api/admin/failure-report` write `[sse-client]` and `[failure-report]` lines to `claude-agent-stream-<sessionKey>.log` so one grep against that file reconstructs the failing turn. The admin agent reads these via `logs-read`; the operator surfaces them by clicking "Report this turn" in the chat menu.

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 conversation-archive-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/memory/mcp/src/lib/conversation-normalisers/whatsapp-text.ts → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Edit","tool_input":{"file_path":"/Users/x/repo/platform/plugins/memory/mcp/src/lib/conversation-normalisers/whatsapp-text.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/memory/mcp/src/lib/conversation-normalisers/whatsapp-text.ts","old_string":"file_path:/safe/path","new_string":"x"}}' \
+  2
+
+run_case "PreToolUse Bash invoking conversation-archive-ingest.sh → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"bash platform/plugins/memory/bin/conversation-archive-ingest.sh /tmp/chat.zip --source whatsapp --owner-element-id 4:abc:1 --participant-person-ids 4:abc:2 --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/__tests__/playwright-file-guard.test.sh

@@ -0,0 +1,278 @@
+#!/usr/bin/env bash
+# Regression test for playwright-file-guard.sh (Task 944).
+#
+# Covers:
+#   1. file:// URL → hook emits hookSpecificOutput.updatedInput.url JSON,
+#      starts a backgrounded python3 -m http.server on a free port rooted
+#      at the file's parent dir, writes /tmp/playwright-file-guard.<port>.pid,
+#      and the rewritten URL responds 200.
+#   2. https:// URL → silent passthrough, exit 0, no stdout JSON.
+#   3. Free-port under contention: hold 8080, run hook on file://, assert
+#      chosen port != 8080.
+#   4. Stale-PID cleanup mode: pre-create stale PID file pointing at a real
+#      http.server we control, run `cleanup`, assert process killed + file
+#      removed.
+#   5. Reused-PID guard: PID file points at non-http.server process,
+#      cleanup leaves the process alone.
+#   6. Fail-open on missing python3 (PATH override).
+#   7. Malformed stdin → exit 0 silent passthrough.
+#   8. Terminal stdin guard preserved.
+#   9. Hook source contains no copy of the old menu phrase.
+
+set -u
+
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/playwright-file-guard.sh"
+if [[ ! -x "$HOOK" ]]; then
+  echo "FAIL: $HOOK not executable" >&2
+  exit 1
+fi
+
+# Track every PID we spawn so we can reap on EXIT.
+TRACKED_PIDS=()
+TMPFILES=()
+
+cleanup_test_state() {
+  for p in "${TRACKED_PIDS[@]:-}"; do
+    [[ -n "$p" ]] && kill -9 "$p" 2>/dev/null || true
+  done
+  for f in "${TMPFILES[@]:-}"; do
+    [[ -n "$f" ]] && rm -f "$f" 2>/dev/null || true
+  done
+  rm -f /tmp/playwright-file-guard.*.pid 2>/dev/null || true
+}
+trap cleanup_test_state EXIT
+
+PASS=0
+FAIL=0
+
+pass() { echo "PASS: $1"; PASS=$((PASS + 1)); }
+fail() { echo "FAIL: $1" >&2; FAIL=$((FAIL + 1)); }
+
+# Sweep stale PID files BEFORE running tests so prior runs don't poison the
+# fixture. The hook's opportunistic cleanup also triggers on every call, but
+# a clean slate makes assertions deterministic.
+rm -f /tmp/playwright-file-guard.*.pid 2>/dev/null || true
+
+# ---- Test 1: file:// rewrite happy path -------------------------------------
+
+TEST_HTML=$(mktemp -t playwright-file-guard-XXXXXX).html
+echo "<html><body>hello</body></html>" > "$TEST_HTML"
+TMPFILES+=("$TEST_HTML")
+TEST_BASENAME=$(basename "$TEST_HTML")
+
+INPUT_JSON=$(printf '{"hook_event_name":"PreToolUse","tool_name":"mcp__plugin_playwright_playwright__browser_navigate","tool_input":{"url":"file://%s"}}' "$TEST_HTML")
+STDOUT_FILE=$(mktemp); STDERR_FILE=$(mktemp); TMPFILES+=("$STDOUT_FILE" "$STDERR_FILE")
+
+printf '%s' "$INPUT_JSON" | bash "$HOOK" >"$STDOUT_FILE" 2>"$STDERR_FILE"
+RC=$?
+
+if [[ "$RC" -ne 0 ]]; then
+  fail "Test 1: hook exited $RC on file:// rewrite (expected 0)"
+elif ! grep -q '"hookSpecificOutput"' "$STDOUT_FILE"; then
+  fail "Test 1: stdout missing hookSpecificOutput JSON. Got: $(cat "$STDOUT_FILE")"
+elif ! grep -q '"updatedInput"' "$STDOUT_FILE"; then
+  fail "Test 1: stdout missing updatedInput field. Got: $(cat "$STDOUT_FILE")"
+elif ! grep -qE '"url":\s*"http://127.0.0.1:[0-9]+/'"$TEST_BASENAME"'"' "$STDOUT_FILE"; then
+  fail "Test 1: stdout url not rewritten as expected. Got: $(cat "$STDOUT_FILE")"
+elif ! grep -q '\[playwright-file-guard\] action=rewrite' "$STDERR_FILE"; then
+  fail "Test 1: stderr missing rewrite log line. Got: $(cat "$STDERR_FILE")"
+else
+  PORT=$(grep -oE 'http://127\.0\.0\.1:[0-9]+/' "$STDOUT_FILE" | head -1 | grep -oE ':[0-9]+/' | tr -d ':/')
+  PID_FILE="/tmp/playwright-file-guard.${PORT}.pid"
+  if [[ ! -f "$PID_FILE" ]]; then
+    fail "Test 1: PID file $PID_FILE not created"
+  else
+    SERVER_PID=$(cat "$PID_FILE")
+    TRACKED_PIDS+=("$SERVER_PID")
+    HTTP_BODY=$(curl -s --max-time 2 "http://127.0.0.1:${PORT}/${TEST_BASENAME}" 2>/dev/null || true)
+    if echo "$HTTP_BODY" | grep -q "hello"; then
+      pass "Test 1: file:// → rewrite + spawned server responds 200"
+    else
+      fail "Test 1: spawned server at port $PORT did not return file content. Body: $HTTP_BODY"
+    fi
+  fi
+fi
+
+# ---- Test 2: https:// passthrough -------------------------------------------
+
+INPUT_JSON='{"hook_event_name":"PreToolUse","tool_name":"mcp__plugin_playwright_playwright__browser_navigate","tool_input":{"url":"https://example.com"}}'
+STDOUT_FILE=$(mktemp); STDERR_FILE=$(mktemp); TMPFILES+=("$STDOUT_FILE" "$STDERR_FILE")
+printf '%s' "$INPUT_JSON" | bash "$HOOK" >"$STDOUT_FILE" 2>"$STDERR_FILE"
+RC=$?
+
+if [[ "$RC" -ne 0 ]]; then
+  fail "Test 2: hook exited $RC on https:// passthrough"
+elif [[ -s "$STDOUT_FILE" ]]; then
+  fail "Test 2: stdout should be empty on passthrough. Got: $(cat "$STDOUT_FILE")"
+elif ! grep -q '\[playwright-file-guard\] action=passthrough scheme=https' "$STDERR_FILE"; then
+  fail "Test 2: stderr missing passthrough log line. Got: $(cat "$STDERR_FILE")"
+else
+  pass "Test 2: https:// → silent passthrough"
+fi
+
+# ---- Test 3: free port under :8080 contention -------------------------------
+
+python3 -c "
+import socket, time, sys
+s = socket.socket()
+try:
+  s.bind(('127.0.0.1', 8080))
+  s.listen(1)
+  print('READY', flush=True)
+  time.sleep(15)
+except OSError as e:
+  print('SKIP', e, flush=True)
+  sys.exit(0)
+" >/tmp/playwright-file-guard-test-blocker.stdout 2>&1 &
+BLOCKER_PID=$!
+TRACKED_PIDS+=("$BLOCKER_PID")
+TMPFILES+=("/tmp/playwright-file-guard-test-blocker.stdout")
+
+for _ in 1 2 3 4 5 6 7 8 9 10; do
+  if grep -qE 'READY|SKIP' /tmp/playwright-file-guard-test-blocker.stdout 2>/dev/null; then break; fi
+  sleep 0.1
+done
+
+if grep -q SKIP /tmp/playwright-file-guard-test-blocker.stdout 2>/dev/null; then
+  echo "SKIP: Test 3 — port 8080 already held by another process; cannot run contention test"
+else
+  TEST_HTML2=$(mktemp -t playwright-file-guard-XXXXXX).html
+  echo "<html>2</html>" > "$TEST_HTML2"
+  TMPFILES+=("$TEST_HTML2")
+  INPUT_JSON=$(printf '{"hook_event_name":"PreToolUse","tool_name":"mcp__plugin_playwright_playwright__browser_navigate","tool_input":{"url":"file://%s"}}' "$TEST_HTML2")
+  STDOUT_FILE=$(mktemp); TMPFILES+=("$STDOUT_FILE")
+  printf '%s' "$INPUT_JSON" | bash "$HOOK" >"$STDOUT_FILE" 2>/dev/null
+  CHOSEN_PORT=$(grep -oE 'http://127\.0\.0\.1:[0-9]+/' "$STDOUT_FILE" | head -1 | grep -oE ':[0-9]+/' | tr -d ':/')
+  if [[ -z "$CHOSEN_PORT" ]]; then
+    fail "Test 3: hook did not produce a rewrite under contention. Stdout: $(cat "$STDOUT_FILE")"
+  elif [[ "$CHOSEN_PORT" == "8080" ]]; then
+    fail "Test 3: hook picked 8080 even though it was bound"
+  else
+    SERVER_PID=$(cat "/tmp/playwright-file-guard.${CHOSEN_PORT}.pid" 2>/dev/null || echo "")
+    [[ -n "$SERVER_PID" ]] && TRACKED_PIDS+=("$SERVER_PID")
+    pass "Test 3: free-port under :8080 contention picked $CHOSEN_PORT"
+  fi
+fi
+
+# ---- Test 4: stale-PID cleanup mode (explicit argv) -------------------------
+
+STALE_DIR=$(mktemp -d); TMPFILES+=("$STALE_DIR")
+( cd "$STALE_DIR" && exec python3 -u -m http.server 0 >/tmp/playwright-file-guard-stale.stdout 2>&1 ) &
+STALE_PID=$!
+TRACKED_PIDS+=("$STALE_PID")
+TMPFILES+=("/tmp/playwright-file-guard-stale.stdout")
+# Wait up to 2s for the http.server banner to flush.
+for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20; do
+  if grep -qE 'port [0-9]+' /tmp/playwright-file-guard-stale.stdout 2>/dev/null; then break; fi
+  sleep 0.1
+done
+STALE_PORT=$(grep -oE 'port [0-9]+' /tmp/playwright-file-guard-stale.stdout 2>/dev/null | head -1 | grep -oE '[0-9]+' || echo "")
+if [[ -z "$STALE_PORT" ]]; then
+  fail "Test 4 setup: could not extract port from python3 http.server"
+else
+  STALE_PID_FILE="/tmp/playwright-file-guard.${STALE_PORT}.pid"
+  echo "$STALE_PID" > "$STALE_PID_FILE"
+  TMPFILES+=("$STALE_PID_FILE")
+  touch -t "$(date -u -v-2H +%Y%m%d%H%M.%S 2>/dev/null || date -u -d '2 hours ago' +%Y%m%d%H%M.%S)" "$STALE_PID_FILE"
+
+  bash "$HOOK" cleanup >/dev/null 2>&1
+
+  # SIGTERM is asynchronous — wait up to 1s for the process to actually die.
+  for _ in 1 2 3 4 5 6 7 8 9 10; do
+    if ! kill -0 "$STALE_PID" 2>/dev/null; then break; fi
+    sleep 0.1
+  done
+
+  if kill -0 "$STALE_PID" 2>/dev/null; then
+    fail "Test 4: stale PID $STALE_PID still alive after cleanup"
+    kill -9 "$STALE_PID" 2>/dev/null || true
+  elif [[ -f "$STALE_PID_FILE" ]]; then
+    fail "Test 4: stale PID file $STALE_PID_FILE not removed after cleanup"
+  else
+    pass "Test 4: stale-PID cleanup killed http.server + removed PID file"
+  fi
+fi
+
+# ---- Test 5: reused-PID guard ----------------------------------------------
+
+REUSED_PID_FILE="/tmp/playwright-file-guard.59999.pid"
+echo "$$" > "$REUSED_PID_FILE"
+TMPFILES+=("$REUSED_PID_FILE")
+touch -t "$(date -u -v-2H +%Y%m%d%H%M.%S 2>/dev/null || date -u -d '2 hours ago' +%Y%m%d%H%M.%S)" "$REUSED_PID_FILE"
+
+bash "$HOOK" cleanup >/dev/null 2>&1
+
+if ! kill -0 "$$" 2>/dev/null; then
+  fail "Test 5: reused-PID guard killed our own bash process — fatal"
+elif [[ -f "$REUSED_PID_FILE" ]]; then
+  fail "Test 5: reused-PID file $REUSED_PID_FILE not removed (hook should drop the stale ref)"
+else
+  pass "Test 5: reused-PID guard left process alive, dropped stale PID file"
+fi
+
+# ---- Test 6: missing python3 fails open ------------------------------------
+
+EMPTY_PATH_DIR=$(mktemp -d); TMPFILES+=("$EMPTY_PATH_DIR")
+ln -s "$(command -v bash)" "$EMPTY_PATH_DIR/bash"
+ln -s "$(command -v grep)" "$EMPTY_PATH_DIR/grep"
+ln -s "$(command -v cat)" "$EMPTY_PATH_DIR/cat"
+ln -s "$(command -v rm)" "$EMPTY_PATH_DIR/rm"
+ln -s "$(command -v mktemp)" "$EMPTY_PATH_DIR/mktemp"
+
+INPUT_JSON='{"hook_event_name":"PreToolUse","tool_name":"mcp__plugin_playwright_playwright__browser_navigate","tool_input":{"url":"file:///tmp/missing-python.html"}}'
+STDOUT_FILE=$(mktemp); STDERR_FILE=$(mktemp); TMPFILES+=("$STDOUT_FILE" "$STDERR_FILE")
+PATH="$EMPTY_PATH_DIR" printf '%s' "$INPUT_JSON" | PATH="$EMPTY_PATH_DIR" bash "$HOOK" >"$STDOUT_FILE" 2>"$STDERR_FILE"
+RC=$?
+
+if [[ "$RC" -ne 0 ]]; then
+  fail "Test 6: missing python3 should fail open (exit 0), got $RC"
+elif [[ -s "$STDOUT_FILE" ]]; then
+  fail "Test 6: stdout should be empty on fail-open. Got: $(cat "$STDOUT_FILE")"
+elif ! grep -q '\[playwright-file-guard\] action=fail reason=python3-missing' "$STDERR_FILE"; then
+  fail "Test 6: stderr missing python3-missing log line. Got: $(cat "$STDERR_FILE")"
+else
+  pass "Test 6: missing python3 → fail open with diagnostic"
+fi
+
+# ---- Test 7: malformed stdin → silent passthrough ---------------------------
+
+STDOUT_FILE=$(mktemp); STDERR_FILE=$(mktemp); TMPFILES+=("$STDOUT_FILE" "$STDERR_FILE")
+printf '%s' 'not json at all { ' | bash "$HOOK" >"$STDOUT_FILE" 2>"$STDERR_FILE"
+RC=$?
+
+if [[ "$RC" -ne 0 ]]; then
+  fail "Test 7: malformed stdin should fail open (exit 0), got $RC"
+elif [[ -s "$STDOUT_FILE" ]]; then
+  fail "Test 7: stdout should be empty on malformed stdin"
+else
+  pass "Test 7: malformed stdin → silent passthrough"
+fi
+
+# ---- Test 8: terminal stdin guard preserved --------------------------------
+
+if ! grep -q '\[ -t 0 \]' "$HOOK"; then
+  fail "Test 8: terminal stdin guard ([ -t 0 ]) missing from hook"
+else
+  pass "Test 8: terminal stdin guard present"
+fi
+
+# ---- Test 9: zero-grep-hits for old menu copy in this hook ------------------
+
+# The pattern uses [l] to break self-match: this file's bytes contain "[l]ocal"
+# but the hook source contains "local" if the menu copy was reintroduced. The
+# extended-regex bracket class matches "local" without our query containing
+# the literal string we're forbidding.
+OLD_MENU_PATTERN='Start a [l]ocal HTTP server'
+if grep -qE "$OLD_MENU_PATTERN" "$HOOK"; then
+  fail "Test 9: hook still contains the old menu copy"
+else
+  pass "Test 9: hook does not contain the old menu copy"
+fi
+
+echo
+echo "──────── playwright-file-guard test summary ────────"
+echo "PASS: $PASS"
+echo "FAIL: $FAIL"
+
+[[ "$FAIL" -gt 0 ]] && exit 1
+exit 0