fix(bin): prevent Codex visual workspace leaks

[AviKaufman]

Intent

Fix Codex-owned browser leakage from Firstmate visual workflows. The branch adds bin/fm-visual-guard.sh, routes generated briefs/docs to use it, preserves user browser behavior, and hardens guarded launches with dedicated FirstmateVisual identity, legacy CodexVisual/codex-visual-browser coverage, Hyprland client remediation to hidden workspace 99 on CODEX-HEADLESS, post-dispatch client tracking, stable hidden settling before success, numeric monitor resolution, robust client-field parsing, and focused tests for the exact leak and settle regressions. It also includes the narrow session-start missing-node fixture isolation. The required report remains private at /home/avi/dev/tools/firstmate/data/codex-browser-workspace-leak-k8/report.md; no tracked report artifact should be added. The PR diff must stay scoped to the browser-isolation task files.

What Changed

• Add a Hyprland-specific visual guard that launches isolated Firstmate browser sessions, remediates dedicated visual clients to workspace 99 on CODEX-HEADLESS, and fails closed unless placement remains stable.
• Route generated ship/scout briefs and operator documentation through the guard while documenting its platform scope, prerequisites, and commands.
• Add focused coverage for visual placement, remediation, settling, client parsing, and brief guidance, plus isolate missing-node session-start fixtures from the host PATH.

Risk Assessment

✅ Low: Captain, the prior fail-open defect is fixed across all client-query paths, the regression coverage is deterministic, and the complete diff remains scoped to the required browser-isolation files with no tracked report artifact.

Testing

The supplied full baseline and focused regression suites passed; a real guarded Chrome launch appeared as FirstmateVisual on workspace 99 / CODEX-HEADLESS while visible workspaces 1–3 remained unchanged. The locked host caused grim to capture black or the compositor lock surface rather than browser content, so no misleading screenshot is presented; the rendered HTML and exact live placement transcript are retained as evidence.

Evidence: Live visual-guard transcript

Firstmate visual guard end-to-end validation

Command:
  bin/fm-visual-guard.sh doctor

Observed:
  ok: hyprctl
  ok: jq
  ok: grim
  ok: browser=google-chrome-stable
  ok: visual target output=CODEX-HEADLESS workspace=99 geometry=1440x1000@60,0x0,1 class=FirstmateVisual
  ok: workspace rule 99 -> CODEX-HEADLESS
  clients: (none)

Command:
  FM_VISUAL_VERIFY_ATTEMPTS=30 FM_VISUAL_VERIFY_SLEEP=0.2 bin/fm-visual-guard.sh browser file:///tmp/no-mistakes-evidence/01KXQ62Y2EQC3TPM62860V9HZ4/visual-guard-proof.html

Observed:
  launched on workspace 99: 'google-chrome-stable' '--class=FirstmateVisual' '--user-data-dir=/home/avi/.local/state/firstmate-codex-visual-chrome' '--no-first-run' '--no-default-browser-check' '--new-window' 'file:///tmp/no-mistakes-evidence/01KXQ62Y2EQC3TPM62860V9HZ4/visual-guard-proof.html'

Command:
  bin/fm-visual-guard.sh clients

Observed:
  0x5594496dd640  FirstmateVisual  Firstmate Visual Guard End-to-End Proof - Google Chrome  99  CODEX-HEADLESS

Hyprland client readback:
  address=0x5594496dd640
  mapped=true
  hidden=false
  class=FirstmateVisual
  initialClass=FirstmateVisual
  title=Firstmate Visual Guard End-to-End Proof - Google Chrome
  workspace.id=99
  workspace.name=99
  monitor.id=3
  monitor.name=CODEX-HEADLESS

Visible-workspace snapshot before launch:
  eDP-1      active workspace 1
  DVI-I-1    active workspace 2
  DVI-I-2    active workspace 3
  CODEX-HEADLESS active workspace 99

Visible-workspace snapshot after launch:
  eDP-1      active workspace 1
  DVI-I-1    active workspace 2
  DVI-I-2    active workspace 3
  CODEX-HEADLESS active workspace 99

Screenshot attempt:
  bin/fm-visual-guard.sh screenshot /tmp/no-mistakes-evidence/01KXQ62Y2EQC3TPM62860V9HZ4/firstmate-visual-guard-hidden.png

Observed:
  grim succeeded and produced a 1440x1000 PNG, but CODEX-HEADLESS had DPMS off because the host session was locked, so the image was all black. Turning on DPMS for only CODEX-HEADLESS made the compositor lock surface visible rather than the guarded Chrome content. No screenshot is presented as application evidence because the lock surface prevents a truthful browser rendering capture.

Evidence: Rendered browser proof page

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Firstmate Visual Guard End-to-End Proof</title>
  <style>
    :root { color-scheme: dark; font-family: ui-sans-serif, system-ui, sans-serif; }
    body { margin: 0; min-height: 100vh; display: grid; place-items: center; background: #07111f; color: #eaf2ff; }
    main { width: min(920px, calc(100vw - 96px)); padding: 56px; border: 1px solid #2f4b70; border-radius: 28px; background: linear-gradient(145deg, #101f35, #0a1627); box-shadow: 0 28px 90px #0008; }
    .eyebrow { color: #7dd3fc; font-weight: 700; letter-spacing: .13em; text-transform: uppercase; }
    h1 { margin: 16px 0 12px; font-size: clamp(38px, 6vw, 72px); line-height: .98; }
    p { font-size: 23px; line-height: 1.5; color: #c6d7ee; }
    .status { display: inline-flex; align-items: center; gap: 12px; margin-top: 24px; padding: 14px 20px; border-radius: 999px; background: #082f2b; color: #99f6e4; font-weight: 750; }
    .dot { width: 12px; height: 12px; border-radius: 50%; background: #2dd4bf; box-shadow: 0 0 24px #2dd4bf; }
    code { color: #fde68a; }
  </style>
</head>
<body>
  <main>
    <div class="eyebrow">Rendered end-to-end evidence</div>
    <h1>Firstmate visual guard</h1>
    <p>This real Chrome window was launched by <code>bin/fm-visual-guard.sh browser</code> and captured from the hidden <code>CODEX-HEADLESS</code> output.</p>
    <div class="status"><span class="dot"></span>Hidden workspace 99 · FirstmateVisual</div>
  </main>
</body>
</html>

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 1 issue found → auto-fixed ✅

• 🚨 bin/fm-visual-guard.sh:297 - Captain, client_rows is the producer in a pipeline whose final while loop determines the status, while the script enables no pipefail. A failed hyprctl clients -j, monitor query, or jq parse therefore becomes an empty client set; verification can subsequently report success without proving placement, potentially leaving a visible leak. Capture and validate client_rows before iterating, or otherwise propagate producer failures.

🔧 Fix: Fail closed on visual client query errors
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"
• Supplied successful baseline: command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"
• bash tests/fm-visual-guard.test.sh
• bash tests/fm-brief.test.sh
• bash tests/fm-session-start.test.sh
• Scope verification: git diff --name-status 85643eec1f8cbe2136895c7dbe4277899f057348..7dc44534398c7cab0416c57c71daf372e2ee3c87 and tracked-report check
• bin/fm-visual-guard.sh doctor
• FM_VISUAL_VERIFY_ATTEMPTS=30 FM_VISUAL_VERIFY_SLEEP=0.2 bin/fm-visual-guard.sh browser file:///tmp/no-mistakes-evidence/01KXQ62Y2EQC3TPM62860V9HZ4/visual-guard-proof.html
• bin/fm-visual-guard.sh clients plus before/after hyprctl monitor, workspace, and client readbacks
• bin/fm-visual-guard.sh screenshot /tmp/no-mistakes-evidence/01KXQ62Y2EQC3TPM62860V9HZ4/firstmate-visual-guard-hidden.png and visual inspection
• Exact-address browser cleanup and verification that visible workspaces and DPMS state were restored

🔧 **Document** - 1 issue found → auto-fixed ✅

• 🚨 AGENTS.md:145 - The unconditional visual-guard rule conflicts with Firstmate's documented macOS support: the guard requires Hyprland/hyprctl. Resolving this requires either a non-Hyprland fallback/platform gate or intentionally narrowing platform support.

🔧 Fix: Scope visual guard docs to Hyprland workflows
✅ Re-checked - no issues remain.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.