WebUI Fleet Bridge Planning Scratchpad

Mode: Task 0 docs-only decision PR authorized; Task 1 and all executable/runtime work remain blocked. Owner: Velma Opened: 2026-08-09 Scope: One enrolled Agent Host launching one native mosaic claude OAuth session and streaming it into apps/web through apps/gateway.

Objective

Turn the approved direction in jarvis-brain/docs/scratchpads/MOSAIC-WEBUI-FLEET-BRIDGE.md into a test-first implementation plan while preserving Fred's harness-home/launcher contract and Scooby's greenfield safety findings.

Source reconciliation

Current origin/main: b0f7d26dd9c14d91eaaefc35d6c9fd6618a0bd92.
Current origin/next: 4df478cdd150fdf8d52ea109f02ade5d85017acd.
Branches currently diverge (main has 11 unique commits; next has 13). next contains local-tier Redis fix #689; main contains later fleet/shell fixes.
Fred's three-root harness-home design and promotion stack are not yet fully present on either baseline.
Therefore neither current SHA is an acceptable implementation pin. Code may begin only from a Fred-certified reconciled SHA containing the required launcher/home contract and safe Gateway startup prerequisites.
The deployed mosaic.woltje.com v0.0.20 UI remains reference-only.

Verified seams

Current browser chat uses an in-process Pi SDK session.
AgentRuntimeProvider supports list/tree/stream/send/attach/detach/terminate, but not create/start.
InteractionController enrolls an already-existing runtime session; it cannot launch one.
Hermes is the only runtime provider registered in Gateway.
Tmux streaming is explicitly unsupported and remains out of scope.
mosaic claude is the authoritative launcher and accepts Claude's machine-facing stream-json flags.
Installed discovery version: Claude Code 2.1.226. Target Distrobox version must be independently pinned and certified.

Non-negotiable dependencies

Fred approves the machine-facing launcher/seat-home contract before code.
No WebUI/Gateway direct read of lease broker state, daemon socket, or state files (F-V3).
No provider OAuth token leaves the Agent Host.
No local Gateway/Web startup around the KBN/database hold.
Greenfield work runs in a Debian Distrobox with an isolated home.
The initial plan PR targets next; Fred binds D1–D15 on its exact head before issue/PRD/tracker completion or implementation work.

Reproducible evidence

Run from a clean Stack clone:

git fetch origin main next
git rev-parse origin/main origin/next
git rev-list --left-right --count origin/main...origin/next
rg -n "interface AgentRuntimeProvider|createSession|streamEvents|terminate" \
  packages/types/src/agent packages/agent/src apps/gateway/src/agent
rg -n "AgentService\.prompt|interaction_sessions|createRuntimeTerminationApproval" \
  apps/gateway/src packages/db/src/schema.ts

Primary inspected source seams:

packages/types/src/agent/agent-runtime-provider.ts
packages/agent/src/{runtime-provider-registry,hermes-runtime-provider,matrix-native-runtime-provider,tmux-fleet-runtime-provider}.ts
apps/gateway/src/agent/{runtime-provider-registry.service,interaction.controller,durable-session.repository,durable-session.service}.ts
apps/gateway/src/chat/chat.gateway.ts
packages/mosaic/src/commands/{launch,interaction}.ts
packages/mosaic/src/fleet/generated-env-boundary.ts
packages/db/src/schema.ts
apps/web/src/app/(dashboard)/chat/page.tsx

Planning-only investigation transcripts are local and intentionally uncommitted:

/tmp/velma-plan-stack-surface.txt
/tmp/velma-plan-structure.txt
/tmp/velma-plan-scooby.txt
/tmp/velma-plan-runtime-contract.txt

Source findings that constrain the design

interaction_sessions.id is the stable primary key; there are no create/policy/enrollment/state columns.
interaction_outbox has a unique (session_id, idempotency_key) index and only pending | processing | delivered.
Baseline DurableSessionRepository.create() can replace provider/runtime identity for the same owner; M1 must remove that implicit mutation.
Baseline termination approval is Redis-backed and currently consumes separately from PostgreSQL; M1 therefore needs durable authorization acceptance before destructive token deletion/dispatch.
Existing interaction HTTP base is /api/interaction/:agentName; the plan extends it rather than inventing a second route family.
Baseline launch.ts/lease launcher still use ambient lookup/literal interpreters. Section 4.1 is non-binding consumer input to Fred's W-F design; W-F's final resolved-launch contract must exist in the certified base before Velma can certify it.
Root pnpm test is not KBN-safe: it includes PGlite migration and framework-shell/lease-broker suites.

Independent draft review

Seven adversarial review rounds found and drove explicit fixes for:

a candidate resolved-seat consumer descriptor and threat model, now explicitly non-binding input to Fred's W-F-owned launcher design;
one active launch per stable conversation, exact pending/failed encodings, durable pre-dispatch reservation, CAS activation, and crash lookup without a migration;
generation-bound enrollment, command/event revalidation, SIGHUP config epochs, and stale-epoch rejection;
Redis/PostgreSQL exact-stop crash safety via non-destructive verify, durable authorization acceptance, atomic claim/GETDEL, and same-operation status reconciliation;
sequence gaps/reorder limits, deterministic UUIDv5 completion, and Gateway restart fail-closed behavior;
shared streaming redaction before host ring/transport and again before Gateway persistence/browser;
D2/D12-selected path-free provenance and a separate safe browser DTO—never raw or hashed path strings;
exact F-V3 boundary: bridge has no broker API, while Fred's sealed launcher may enforce broker policy internally;
migration-free focused tests in Tasks 1–8, with live OAuth, repository transaction, Gateway/Web, and Playwright restricted to the Fred/Scooby-certified Task 9 path;
candidate private/public commitment and artifact-binding mechanisms that W-F may accept, simplify, replace, or defer;
JCS event-digest recomputation and equal/different duplicate handling in both accepted and future-buffer states;
a safe browser presentation DTO for host/workspace/seat/persona labels, readiness, and connection state;
explicit OnApplicationBootstrap create/stop recovery enumeration with no auto-launch;
all POSIX/Windows/UNC/file/tilde path classes in the streaming redactor and definitive failed-stop response semantics;
the full 14-column canonical task schema, fake-only Task 5 repository tests, migration-free certified Task 9 DB test, server-owned operation correlations/routes, and exact merged-SHA smoke;
per-commit independent review, queue guards, exact-head PR review, squash merge, exact merged-next SHA/CI wait, worktree-bound smoke, issue-state readback, and reviewed tracker-closure PR with its own merged-next CI;
a private DB URL loader captured/exported per session without recording or echoing the credential;
an attached Task 9 implementation branch, provider-filtered exact issue-state readback, and machine-verified smoke JSON binding source/worktree/deployed SHA;
a capped, duplicate-key-rejecting, exact-key/type smoke schema so report extensions or JSON boolean/float coercion cannot smuggle data or fake child-count evidence.

The plan remains deliberately decision-PR-ready, not implementation-ready. Fred authorized only Task 0's initial two-document PR on next. He must still return every Section 2 value, replace all [FRED-GATE] entries, certify storage/startup, and provide the W-F-dependent IMPLEMENTATION_BASE_SHA before Task 0 closes or Task 1 starts.

Current status

Gitea principal verified as velma; helper and API wrapper resolution are fail-closed and correct.
Fred authorized the initial Task 0 docs-only PR in comms/20260809T094952Z__from-fred__ec0e85.md and confirmed its next lane/W-F descriptor corrections in comms/20260809T095437Z__from-fred__4ee79d.md.
Provisional decisions: D1/D8/D9/D10/D13/D14 approved; D4 tool labels exactly {Read, Grep, Glob}; D5/D12 provisional; D11 remains a single-operator seam; D2/D3/D6/D7 and IMPLEMENTATION_BASE_SHA are BLOCKED-ON-W-F.
Awaiting exact plan-PR-head review and Fred's complete D1–D15 binding contract.
No source code, database, deployment, or live runtime changes made.

8.4 KiB Raw Blame History Unescape Escape