feat: integrate PR #47, PR #27, PR #26, profile health & read-only extension inventory

.agents/skills/cloakbrowser-manager-development/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: cloakbrowser-manager-development
+description: Use when continuing, reviewing, testing, deploying, or documenting the CloakBrowser Manager fork, especially its mobile VNC workspace, profile organization, scoped access, harness bridge, redacted profile health, VCVM deployment, or release evidence.
+metadata:
+  category: integration-documentation
+  triggers:
+    - CloakBrowser Manager
+    - mobile VNC
+    - VCVM
+    - Codex Computer Use
+    - profile organization
+    - profile health
+    - BrowserScan
+    - proxychecker
+    - scoped browser access
+---
+
+# Continue CloakBrowser Manager Development
+
+Use this repository-local workflow to continue the fork without losing its security boundaries, mobile constraints, or evidence history.
+
+## Non-negotiable boundaries
+
+- Work in the CloakBrowser Manager fork only: `https://github.com/Martin-Hausleitner/CloakBrowser-Manager`.
+- Treat `https://github.com/CloakHQ/CloakBrowser-Manager` as read-only upstream unless the user explicitly changes that scope.
+- Never push CloakBrowser work, reports, or generated files to `fintaro-ai/Fintaro-Agent`.
+- Keep the Manager and browser runtime on the VCVM. Use the Mac as a client, validation host, and secure tunnel endpoint.
+- Never expose administrator tokens, user passwords, proxy credentials, agent keys, cookies, browser content, raw launch arguments, or host paths in logs, reports, screenshots, commits, or chat.
+- Preserve unrelated dirty files. Stage explicit paths and review the staged diff before every commit.
+- A preferred harness is metadata, not an execution authority. Host-scoped browser actions must continue to require the verified `codex-computer-use` bridge and fail closed otherwise.
+- Profile health is an observation, not an undetectability guarantee. Persist only masked IPs, numeric scores, source states and whitelisted warning/blocker codes; never provider HTML, raw responses or exception text.
+- Keep the optional proxychecker on a trusted VCVM-local boundary. Manager `/health` must not depend on it, and an unavailable proxychecker must degrade to an explicit source state rather than block profile launch.
+- **External agents steer via API/CLI/skill, not UI clicks.** Profile create/update/launch/stop/open-links must remain callable with a scoped `cbm_agent_…` bearer key. See [references/agent-control.md](references/agent-control.md).
+
+## Start every continuation
+
+1. Read the following sources in order:
+   - `README.md`, especially **Fork development status**.
+   - `docs/GOAL-ACCEPTANCE-MATRIX-2026-07-22.md`.
+   - The newest relevant plan in `docs/superpowers/plans/`.
+   - The relevant audit or benchmark document linked by the matrix.
+2. Inspect `git status`, the active branch, both remotes, and recent commits. Do not discard or rewrite unknown changes.
+3. Check that `fork` points to Martin Hausleitner's repository and `origin` points to CloakHQ upstream.
+4. Select the first incomplete acceptance-matrix row whose prerequisites are already proven.
+5. State the exact claim, verification needed, and stop condition before editing.
+
+If the repository's `bd` issue tool is unavailable, record that limitation in the handoff; do not invent issue state.
+
+## Implement one vertical slice at a time
+
+1. Add a failing test for the requested behavior or security boundary.
+2. Make the smallest implementation that passes it; reuse existing types, access checks, redaction helpers, and mobile components.
+3. Run focused backend or frontend tests immediately.
+4. Run the relevant integrated build/gate before widening scope.
+5. Update the acceptance matrix only from fresh evidence.
+6. Commit the slice with explicit staging. Do not mix reports, generated build metadata, benchmark artifacts, or unrelated changes.
+
+## Product rules to preserve
+
+### Mobile UI and VNC
+
+- Keep the live browser as the dominant surface.
+- Use progressive disclosure: persistent controls stay limited to essential session, fullscreen, tools, chat, and send actions.
+- Controls may look compact, but actionable hit areas remain at least 44 by 44 CSS pixels.
+- Text inputs remain at least 16 px on iOS to prevent focus zoom.
+- Derive keyboard-open layout from `visualViewport`; keep both VNC and composer visible and non-overlapping.
+- Keep Fit, Width, Height, Phone fit, viewer zoom, editable framebuffer viewport, fullscreen session switcher, and grid behavior reachable.
+- Do not add benchmark controls or diagnostic clutter to the mobile workspace.
+
+### Profiles and access
+
+- Keep `sandbox_id` as the authorization key. `project_id` and `folder_path` are organization metadata only.
+- Preserve deterministic ordering: pinned, project, folder, name, newest creation time, then id.
+- Redact proxy, fingerprint, filesystem, and launch-argument details from access summaries.
+- Preserve indistinguishable `404` behavior for missing and unauthorized profiles.
+- Treat viewer, interaction, operation, and automation permissions as distinct capabilities.
+
+### Harnesses and automation
+
+- Keep Codex Computer Use as the execution boundary for browser-visible host actions.
+- Saved preferences for Antigravity, Claude Code, OpenCode, or Browser Use may be displayed and propagated as metadata, but must not bypass bridge verification.
+- Keep quick actions typed and capability-checked. Reject unknown commands.
+- Server-side task history is persistence and conversation state; it is not proof that an agent executed a browser task.
+- External agents authenticate with opaque `cbm_agent_…` keys and sandbox grants (`view` / `interact` / `operate` / `automate`). `operate` covers profile create/update/delete/launch/stop inside granted sandboxes; `automate` is separate for CDP. Prefer `scripts/cbm_agent_ctl.py` and [references/agent-control.md](references/agent-control.md) over UI workflows.
+
+### Profile health and external observations
+
+- Schedule the automatic probe only after the first successful launch and never await it in the launch response.
+- Keep manual reruns behind `operate`; keep stored reads behind `view`; preserve indistinguishable `404` behavior outside scope.
+- Mask IPv4 and IPv6 before persistence. Never store or return the raw outbound address.
+- Treat saved-versus-runtime fingerprint consistency, proxy risk/authenticity and BrowserScan authenticity as separate measurements. Never substitute one score for another.
+- BrowserScan challenge, consent, timeout or unsupported markup returns an unavailable score with a whitelisted blocker. Do not click consent or CAPTCHA controls.
+- Do not interpret labels such as `WebDriver` as a detection by themselves; require an explicit negative result.
+- Keep health disclosure off the persistent mobile workspace. A compact desktop summary with progressive detail is sufficient.
+
+## Current verified checkpoint
+
+Snapshot from 23 July 2026 (late night) on `integrate-pr-47-27-26`:
+
+- Agent/extension control plane: `GET/POST /api/extension/catalog`, `POST /api/extension/sessions/open`, `GET/PUT /api/extension/defaults`, templates, open-links (`mode=cdp|vnc|shell`), CDP live `/session/{id}/live`, and live-metrics.
+- Reuse `GET /api/profiles/{id}/open-links` for VNC/CDP fullscreen URLs — do not invent parallel link builders in UI/extension.
+- CDP live root cause + fix: Cloak/Chromium screencast stalls after one frame on static pages; `/session/{id}/live` injects a canvas/rAF compositor pulse (2s keepalive) and keeps real `Page.startScreencast` (screenshot-poll is stall fallback only). VCVM tunnel proof: **blank ~12 fps cast**, **example.com ~21 fps**, Live Dev **~22 fps**.
+- Backend suites for session links / extension sessions / defaults / session_views are green locally; VCVM redeployed after this fix.
+- Prior 23 July evening checkpoints still hold for proxy inventory, Browser-Use shell, and profile health (fingerprint scores not re-probed in this stream-only slice).
+- Safari Remote Automation remains an external blocker.
+- Note: Mac tunnel for Manager must forward to VCVM `MANAGER_PORT` (currently **18115**); a stale forward to 18116 breaks client checks.
+
+Refresh these numbers and claims after any relevant change; this is a dated handoff, not permanent proof.
+
+## Evidence rules
+
+Use the release checklist in [references/release-checklist.md](references/release-checklist.md).
+
+Classify every claim as one of:
+
+- **Proven**: fresh test or live evidence directly covers the full claim.
+- **Implemented; scoped verification passed**: code and focused tests pass, but the required VCVM/device proof is not fresh.
+- **Partial**: only part of the requirement is implemented or measured.
+- **Blocked externally**: product code is ready, but an external prerequisite such as Safari Remote Automation, Tailnet policy, or physical-device access is unavailable.
+- **Missing**: no acceptable implementation or evidence exists.
+
+Never convert Chromium emulation into a Safari claim, a visual canvas-change proxy into encoded FPS, a WebSocket handshake into touch-to-pixel latency, or a persisted benchmark report into live diagnostics.
+
+## Documentation and handoff
+
+Before ending a development session:
+
+1. Update the README status, completed work, current work, open work, roadmap, timeline, and fresh verification counts.
+2. Update the goal matrix row-by-row with exact evidence and remaining proof.
+3. Mark completed plan checkboxes and retain unresolved tasks.
+4. Record changed files, test results, deployment state, browser/screenshots, latency limits, and external blockers.
+5. Commit and push only to the fork branch, then verify the remote branch SHA matches local `HEAD`.
+6. Do not provide a URL until an independent browser check has loaded it, exercised the relevant flow, and captured a screenshot.
+
+## Stop conditions
+
+Stop and report a blocker only when credentials or external authorization are required, the requested action is destructive, or three safe recovery approaches have failed. Otherwise continue through edit, test, browser validation, documentation, commit, push, and remote verification.
+
+## Required completion report
+
+Return:
+
+1. `Summary`
+2. `Changes Made`
+3. `Validation Results`
+4. `Deployment And Browser Evidence`
+5. `Open Gaps`
+6. `Fork Branch And Commit`

.agents/skills/cloakbrowser-manager-development/references/agent-control.md

@@ -0,0 +1,105 @@
+# External agent control plane
+
+Use this when Codex, Antigravity, Claude Code, OpenCode, Browser Use, a Chrome
+extension, or any harness must steer CloakBrowser Manager **without UI clicks**.
+
+The UI is for human visibility. The control plane is HTTP + CLI + this skill.
+
+## Auth
+
+1. Admin creates a Paperclip-compatible agent once (dashboard or API):
+
+```bash
+curl -sS -X POST "$CBM_BASE_URL/api/access/agents" \
+  -H "Authorization: Bearer $CBM_ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "display_name": "codex-ops",
+    "paperclip_agent_id": "codex-ops",
+    "grants": [
+      {"sandbox_id": "agents", "permission": "operate"},
+      {"sandbox_id": "agents", "permission": "automate"}
+    ]
+  }'
+```
+
+2. Store the returned `api_key` (`cbm_agent_…`) once. Only the hash is persisted.
+
+3. Every agent call uses:
+
+```text
+Authorization: Bearer cbm_agent_…
+```
+
+Permissions:
+
+| Grant | Can do |
+| --- | --- |
+| `view` | List/get profiles in sandbox, open VNC read-only, read health/extensions/open-links |
+| `interact` | VNC input + clipboard |
+| `operate` | Create/update/delete/organize profiles in that sandbox; launch/stop; health rerun |
+| `automate` | CDP REST + CDP WebSocket (does **not** imply launch — also grant `operate`) |
+
+`sandbox_id` is the authorization key. `project_id` / `folder_path` are organization only.
+
+## CLI
+
+```bash
+export CBM_BASE_URL=http://127.0.0.1:18117
+export CBM_AGENT_KEY=cbm_agent_…
+
+scripts/cbm_agent_ctl.py whoami
+scripts/cbm_agent_ctl.py profiles create --name demo --sandbox agents --harness codex --geoip
+scripts/cbm_agent_ctl.py profiles launch <id>
+scripts/cbm_agent_ctl.py profiles open-links <id> --mode cdp --field cdp_fullscreen_url
+scripts/cbm_agent_ctl.py profiles open-links <id> --mode vnc --field vnc_fullscreen_url
+scripts/cbm_agent_ctl.py profiles status <id>
+scripts/cbm_agent_ctl.py profiles stop <id>
+```
+
+Also: `sandboxes`, `catalog`, `profiles health`, `profiles extensions`, `open-session`.
+
+## Core HTTP surface
+
+| Action | Method + path | Min grant |
+| --- | --- | --- |
+| Identity | `GET /api/access/me` | any |
+| Sandboxes | `GET /api/access/sandboxes` | view (filtered) |
+| List/create profiles | `GET/POST /api/profiles` | view / operate |
+| Get/update/delete | `GET/PUT/DELETE /api/profiles/{id}` | view / operate / operate |
+| Launch/stop/status | `POST …/launch`, `POST …/stop`, `GET …/status` | operate / operate / view |
+| Health | `GET …/health`, `POST …/health/run` | view / operate |
+| Extensions | `GET …/extensions` | view |
+| Open links | `GET …/open-links?prefer=local\|cloud&mode=cdp\|vnc\|shell` | view |
+| One-click open | `POST /api/extension/sessions/open` | view (+ operate if launching) |
+| Catalog | `GET /api/extension/catalog` | any authenticated |
+| CDP | `GET/WS /api/profiles/{id}/cdp` | automate |
+| VNC | `WS /api/profiles/{id}/vnc` | view (input needs interact) |
+
+Admin-only (not agent): access users/agents/grants management, proxy inventory ingest, live diagnostics.
+
+Agent lifecycle (admin):
+
+| Action | Method + path |
+| --- | --- |
+| Create | `POST /api/access/agents` (returns one-time `api_key`) |
+| Update / deactivate | `PUT /api/access/agents/{id}` (`active=false` revokes WS) |
+| Rotate key | `POST /api/access/agents/{id}/rotate-key` |
+| Delete / revoke | `DELETE /api/access/agents/{id}` (drops key+grants, revokes WS immediately) |
+
+## VNC vs CDP open (handoff)
+
+- **CDP / Browser-Use snappy live:** top-level or `links.cdp_fullscreen_url` / `links.live_url` → `/session/{id}/live`
+- **VNC fullscreen:** top-level or `links.vnc_fullscreen_url` → `/?profile={id}&view=vnc&fullscreen=1`
+- **Raw sockets:** `links.websocket_url` (VNC WS), `links.cdp_url` / `local.cdp_ws_url` (CDP)
+- Prefer `mode=cdp` when the agent has `automate`; otherwise `mode=vnc`
+- `POST /api/extension/sessions/open` returns the same top-level flat URLs as `GET /api/profiles/{id}/open-links`
+
+Never print agent keys, proxy credentials, cookies, or host paths in logs/chat.
+
+## Boundaries
+
+- Host-scoped browser actions still require the verified `codex-computer-use` bridge.
+- Preferred harness labels are metadata; they do not bypass bridge verification.
+- Profile health is observation, not an undetectability guarantee.
+- Manager and browsers stay on the VCVM; Mac is client/tunnel only.

.agents/skills/cloakbrowser-manager-development/references/release-checklist.md

@@ -0,0 +1,117 @@
+---
+description: Release, VCVM, browser, security, evidence, commit, and push checks for the CloakBrowser Manager fork.
+metadata:
+  tags: [cloakbrowser, vcvm, mobile-vnc, release, verification]
+  source: internal
+---
+
+# CloakBrowser Manager release checklist
+
+Use the smallest focused checks while developing, then run every applicable release layer before claiming the branch is ready.
+
+## 1. Source and repository safety
+
+- Confirm the active worktree, branch, `fork`, and `origin` URLs.
+- Inspect all dirty and untracked paths; preserve unrelated work.
+- Search the staged diff for credentials, bearer tokens, passwords, cookies, proxy URLs, host paths, and raw browser content.
+- Run `git diff --check` and inspect `git diff --cached --stat` plus `git diff --cached`.
+
+## 2. Backend
+
+Focused examples:
+
+```bash
+.venv/bin/pytest backend/tests/test_models.py backend/tests/test_database.py backend/tests/test_api.py backend/tests/test_access_control.py -q
+```
+
+Full suite:
+
+```bash
+.venv/bin/pytest -q
+```
+
+When changing release scripts, compile them with the oldest supported Python runtime as well as the local interpreter. A passing Python 3.14 check does not prove Python 3.11 compatibility.
+
+## 3. Frontend
+
+Focused organization, access, mobile, API, and harness checks:
+
+```bash
+cd frontend
+npm test -- --run \
+  src/App.test.tsx \
+  src/components/ProfileList.test.tsx \
+  src/components/mobile/MobileSplitScreen.test.tsx \
+  src/components/AccessDashboard.test.tsx \
+  src/lib/profileOrganization.test.ts \
+  src/lib/api.test.ts \
+  src/lib/taskHarness.test.ts
+npm run build
+```
+
+Full suite:
+
+```bash
+cd frontend
+npm test
+npm run build
+```
+
+## 4. Release scripts and static gates
+
+Run the repository tests for scripts and deployment surfaces before a live deployment:
+
+```bash
+.venv/bin/pytest scripts -q
+python3 scripts/release_acceptance_gate.py --help
+python3 scripts/mobile_ui_gate.py --help
+python3 scripts/mobile_webkit_gate.py --help
+```
+
+Use the actual gate options documented by each script for the target environment. Do not weaken a failed or blocked prerequisite.
+
+## 5. VCVM deployment
+
+- Deploy only after local unit, integration, build, and static gates pass.
+- Confirm FastAPI, React, SQLite, CloakBrowser, KasmVNC/noVNC, and profile storage all run on the VCVM.
+- Keep the Manager on loopback or private Tailnet HTTPS; never publish it unauthenticated.
+- Verify authenticated profile listing, launch, VNC connection, framebuffer resize/apply, stop, and scoped denial behavior.
+- Restore temporary viewport or profile changes made by the gate.
+
+## 6. Browser and mobile evidence
+
+At minimum, cover:
+
+- compact portrait iPhone viewport;
+- short iPhone viewport with the software keyboard represented by `visualViewport`;
+- large iPhone portrait and landscape;
+- touch tablet;
+- fullscreen browser preview;
+- session grid and switching;
+- Fit, Width, Height, Phone fit, viewer zoom, and persisted framebuffer size;
+- chat collapse/expand, composer, Copy, Paste, and Capture capability states;
+- administrator and scoped operator views;
+- no horizontal overflow and no VNC/composer overlap.
+
+Capture screenshots only after the corresponding assertion passes. Record browser engine and emulation/device limits explicitly.
+
+## 7. Streaming evidence
+
+Report separately:
+
+- VCVM-local HTTP latency;
+- VCVM-local VNC WebSocket open and first RFB frame;
+- Mac-to-VCVM route and whether Tailscale is direct or DERP-relayed;
+- browser-observed first non-black frame;
+- visual canvas-change rate, if used.
+
+Do not call those values encoded FPS or touch-to-pixel latency unless the measurement actually covers those definitions.
+
+## 8. Documentation, commit, and push
+
+- Update `README.md` and `docs/GOAL-ACCEPTANCE-MATRIX-2026-07-22.md` with fresh evidence.
+- Keep historical evidence labeled by date/revision.
+- Commit explicit paths with a conventional message.
+- Push only to `fork`.
+- Verify `git ls-remote fork <branch>` equals local `git rev-parse HEAD`.
+- Report any generated or unrelated paths intentionally left uncommitted.