Document Tauri React GUI plan

notes/epiphany-fork-implementation-plan.md

@@ -118,6 +118,7 @@ These boundaries are more important than the individual method names:
 - `thread/epiphany/roleLaunch` is a bounded authority surface for fixed modeling/checkpoint and verification/review templates, not a broad scheduler or specialist marketplace.
 - `thread/epiphany/roleResult` is a read-only result projection, not a promotion gate, state writer, scheduler, or hidden continuation trigger.
 - The GUI may render and steer typed state, but it must not manufacture canonical understanding.
+- The MVP GUI target is a local Tauri v2 + React operator app over the existing app-server APIs. Tauri owns windowing and local lifecycle; app-server and typed Epiphany state remain authoritative.
 - The app-server remains a host seam; Epiphany-owned machinery should live in `epiphany-core` where practical.
 - Qdrant is the preferred persistent semantic backend; BM25 remains the bootstrap/fallback/control path.
 
@@ -238,6 +239,64 @@ Do not spend Phase 6 polishing Phase 5 out of anxiety. The Phase 5 smoke harness
 is a regression guardrail, not a ritual drum circle for summoning more tiny
 hardening slices.
 
+## GUI Operator Plan
+
+Build the MVP GUI as a local Tauri v2 + React operator console.
+
+The GUI is not the source of truth. It is a desktop window over the same
+app-server surfaces already proved by the CLI status, coordinator, dogfood, and
+live-specialist runners. Its job is to make the single-user loop usable without
+terminal handling, not to invent a parallel state model.
+
+Initial shape:
+
+1. Scaffold `apps/epiphany-gui` as a Tauri v2 app with a React frontend.
+2. Start by consuming existing app-server JSON-RPC surfaces rather than adding new protocol unless the UI exposes a real missing primitive.
+3. Make the first screen an operator console, not a landing page:
+   - active thread and workspace
+   - coordinator recommendation and reason
+   - pressure, CRRC, and reorientation status
+   - fixed role lanes for implementation, modeling/checkpoint, verification/review, and reorientation
+   - reviewable role and reorient findings
+   - job/progress list
+   - artifact bundle list with links to summaries, transcripts, stderr, and comparison files
+4. Add explicit action buttons only for already-bounded authority surfaces:
+   - refresh status
+   - run status snapshot
+   - run coordinator pass
+   - launch fixed modeling/checkpoint role
+   - launch fixed verification/review role
+   - launch fixed reorient-worker when recommended
+   - accept a completed reorientation finding after review
+   - open artifact folder/file
+5. Keep semantic acceptance gated. The GUI may launch bounded work and display
+   findings, but it must not auto-promote evidence, auto-accept worker output,
+   invent arbitrary specialists, or continue implementation after unresolved
+   drift.
+
+Implementation slices:
+
+1. **Read-only shell**: scaffold Tauri/React, connect to a running app-server,
+   render the same data as `tools/epiphany_mvp_status.py`, and provide artifact
+   file links.
+2. **Bounded operator actions**: add buttons for the existing coordinator,
+   roleLaunch, roleResult, reorientLaunch, reorientResult, and reorientAccept
+   flows, preserving review gates.
+3. **Dogfood launcher**: wrap `tools/epiphany_mvp_dogfood.py` and
+   `tools/epiphany_mvp_coordinator.py` as explicit operator actions that write
+   artifact bundles and stream progress/status into the GUI.
+4. **Usability pass**: make the current recommendation, blocked lane, pending
+   review, and next safe action visually obvious enough that the user can test
+   the product without reading transcripts unless something smells wrong.
+
+Verification:
+
+- Keep the existing CLI smokes as backend guardrails.
+- Add a GUI smoke that starts the app-server against a smoke thread, opens the
+  Tauri webview, verifies the operator console renders scene/coordinator/roles,
+  and checks at least one bounded action produces an auditable artifact.
+- Use screenshots for layout regressions once the first screen exists.
+
 ## Later Phases
 
 These remain later work:
@@ -248,7 +307,7 @@ These remain later work:
 - richer role ergonomics after the fixed single-user coordinator proves useful
 - mutation gates that warn or block broad writes when map freshness is stale
 - broader CRRC runtime coordination beyond the landed narrow safe-boundary compact, fixed reorient-worker launch, and pre-compaction checkpoint steering actions
-- GUI workflows for graph, evidence, job, invariant, and frontier steering
+- richer GUI workflows for graph, evidence, job, invariant, and frontier steering after the operator console proves useful
 
 Do not start these from vibes. Each one needs a source-grounded slice plan and a
 clear invariant that says what it must not break.

notes/fresh-workspace-handoff.md

@@ -35,6 +35,7 @@ Do not trust this file for the exact live HEAD. Always check git.
 - Pre-compaction checkpoint intervention is now landed. On token-count events for loaded Epiphany threads, when pressure reaches the existing `shouldPrepareCompaction` threshold, the harness steers the active turn once with a CRRC checkpoint directive so the agent banks working context before compaction/reorientation. This is still bounded steering, not automatic semantic acceptance, a broad scheduler, or implementation continuation.
 - `tools/epiphany_mvp_dogfood.py` is the first auditable dogfood runner. It drives a bounded state/role/CRRC/reorientation loop and writes local artifacts under `.epiphany-dogfood/mvp-loop`, including raw app-server transcript, rendered snapshots, final status, vanilla-reference prompt/output, and comparison notes. The runner now writes truthful vanilla/comparison artifacts whether the optional vanilla reference is skipped, fails, or completes.
 - `tools/epiphany_mvp_live_specialist.py` is the first auditable live-specialist runner. It launches a real role specialist through `thread/epiphany/roleLaunch`, lets the spawned worker report through `report_agent_job_result`, reads it back through `thread/epiphany/roleResult`, and writes local artifacts under `.epiphany-dogfood/live-specialist`.
+- The MVP GUI plan is now Tauri v2 + React under `apps/epiphany-gui`, talking to existing app-server APIs. It is an operator console over typed state and artifact surfaces, not a new source of truth.
 - Internal `agent_job:` workers now get the reporting tool independent of the user-facing CSV spawn feature, and ephemeral worker sessions can initialize the sqlite state runtime on demand so specialist reports land in the shared backend.
 - Durable in-flight investigation checkpointing is now landed in authoritative typed state, writable through `thread/epiphany/update` or accepted `thread/epiphany/promote`, rendered into the prompt, and reflected through scene/context.
 - The repo is an Epiphany fork of Codex, not a Codex preset.
@@ -298,13 +299,14 @@ The fixed-lane coordinator MVP is testable, and the first pre-compaction CRRC
 intervention is now wired. Limited safe-boundary CRRC execution still handles
 compact and fixed reorient-worker launch actions after a turn ends; the
 token-count hook now handles the earlier danger zone by steering active loaded
-turns once when `shouldPrepareCompaction` is reached. The next real move is
-continued agent-run dogfooding, then the smallest local GUI/operator view over
-the same status and artifact surfaces so the user does not have to operate the
-machine from a terminal. CRRC is not a specialist-agent persona; the
-reorient-worker it may launch is the specialist. Do not turn the coordinator
-into a broad hidden dispatcher, arbitrary marketplace, alternate job backend,
-automatic semantic acceptance path, or GUI-as-source-of-truth.
+turns once when `shouldPrepareCompaction` is reached. The next real move is the
+first Tauri v2 + React operator console slice over the same status,
+coordinator, role, reorient, job, and artifact surfaces so the user does not
+have to operate the machine from a terminal. Start read-only, then add bounded
+buttons for already-existing authority surfaces. CRRC is not a specialist-agent
+persona; the reorient-worker it may launch is the specialist. Do not turn the
+coordinator into a broad hidden dispatcher, arbitrary marketplace, alternate
+job backend, automatic semantic acceptance path, or GUI-as-source-of-truth.
 
 Live `thread/epiphany/scene`, `thread/epiphany/jobs`, `thread/epiphany/roles`,
 `thread/epiphany/freshness`, `thread/epiphany/context`,

state/evidence.jsonl

@@ -64,3 +64,4 @@
 {"ts": "2026-04-29T02:35:26+01:00", "type": "design", "status": "ok", "note": "Corrected the CRRC MVP target: turn-complete-only automation is insufficient because compaction can lose learned but unexternalized working context. The next CRRC slice should detect rising pressure before the hard cliff, interrupt or steer the active agent into a bounded persistence/checkpoint pass, then compact/resume/reorient after scratch/checkpoint/map/evidence are banked as needed."}
 {"ts": "2026-04-29T15:15:06+01:00", "type": "implementation", "status": "ok", "note": "Landed the smallest pre-compaction checkpoint intervention: TokenCount handling maps pressure through the existing gauge and, for loaded Epiphany threads at shouldPrepareCompaction, steers the active turn once with a bounded CRRC directive to bank checkpoint/scratch/map/evidence before compaction or reorientation. It does not mutate state directly, accept findings, launch arbitrary specialists, or continue implementation. Focused app-server tests plus coordinator/status/reorient/role smokes passed; a stale scene expected-actions assertion was corrected to include the already-landed coordinator action."}
 {"ts": "2026-04-29T14:35:07+00:00", "type": "implementation", "status": "ok", "note": "Self-dogfood exposed an artifact-honesty blocker in tools/epiphany_mvp_dogfood.py: the manifest listed vanilla comparison artifacts that were not written. The runner now writes truthful vanilla-reference and comparison artifacts for skipped, failed, or completed reference runs; an explicit --run-vanilla-reference pass completed with a persisted vanilla transcript under .epiphany-dogfood/mvp-loop-selfdogfood-vanilla2-20260429."}
+{"ts": "2026-04-29T14:55:37+00:00", "type": "design", "status": "ok", "note": "Chose the MVP GUI path: scaffold a local Tauri v2 + React operator console over existing app-server status/coordinator/role/reorient/job/artifact surfaces. The GUI reflects and steers typed Epiphany state but does not become a source of truth; first slice should be read-only, with bounded action buttons added only for already-existing authority surfaces after rendering is proved."}

state/map.yaml

@@ -12,9 +12,9 @@ objective:
     explicit typed models of the codebase, active goal, evidence, and change
     machinery they are working on.
   current: >
-    Dogfood the landed Phase 6 MVP coordinator, limited CRRC safe-boundary
-    automation, and pre-compaction checkpoint intervention on real local work
-    before adding larger organs.
+    Turn the landed Phase 6 coordinator/status/dogfood artifact surfaces into
+    the smallest local Tauri v2 + React operator GUI, while continuing
+    agent-run dogfood of CRRC and pre-compaction behavior.
 
 constraints:
   - No frontier-scale training budget.
@@ -75,6 +75,7 @@ accepted_design:
   - Context pressure must become an explicit runtime signal for automatic CRRC; inference from transcript vibes, user warnings, or shrinking safe scope is useful only as a temporary human/agent heuristic.
   - The harness now has an in-flight investigation checkpoint packet in durable typed state; automatic CRRC still needs runtime logic that reads the packet and decides whether to resume or force reorientation and re-gathering after compaction.
   - GUI/client work must reflect or steer typed state rather than manufacture a second source of truth.
+  - The MVP GUI target is a local Tauri v2 + React operator console over existing app-server APIs. Tauri owns windowing and local lifecycle; React renders the operator surface; app-server and typed Epiphany state remain authoritative.
   - Durable `job_bindings` now form a thin Epiphany-owned launcher seam: bindings can carry launcher identity, authority scope, backend kind, and backend job id while still supporting the older runtime-agent-job pointer as a compatibility alias.
   - `thread/epiphany/jobs` is a read-only job/progress reflection: it derives indexing, remap, verification, and specialist slots from authoritative state and retrieval summaries, and can overlay durable launcher bindings onto live runtime `agent_jobs` snapshots through the current backend adapter when a real owner exists; it is not a scheduler, notification stream, or durable runtime job table.
   - `thread/epiphany/jobsUpdated` is the first live bound-job progress notification: it translates runtime `agent_job_progress:{json}` background events into changed launcher-bound payloads by resolving durable `job_bindings` against live `agent_jobs` snapshots through the current backend adapter, without polling in a loop, mutating state, or scheduling work.
@@ -162,4 +163,4 @@ rejected_paths:
 
 current_status:
   summary: Phase 1 durable state, Phase 2 prompt integration, Phase 3 typed read, Phase 4 retrieval/indexing, Phase 5 update/distill/propose/promote/read/notification, and Phase 6 read-only scene, jobs, roles, freshness, targeted context, pressure, reorient, CRRC, coordinator, reorient launch/result/accept, explicit modeling/checkpoint and verification/review role launch/result templates, MVP status, dogfood runner, coordinator runner, live specialist runner, limited safe-boundary CRRC automation, and pre-compaction checkpoint intervention are landed. Native CRRC can steer active loaded Epiphany turns once at `shouldPrepareCompaction`; turn-complete automation can still compact or launch the fixed reorient-worker when the coordinator says it can auto-run. The latest self-dogfood pass exposed and fixed an artifact-honesty blocker in the MVP dogfood runner: comparison and vanilla-reference artifacts are now actually written and the optional real vanilla run produces a persisted read-back transcript. Implementation remains main-agent work; CRRC remains workflow automation, not a specialist persona.
-  next_action: Continue dogfooding the coordinator/status/pre-compaction loop through auditable artifacts that the agent runs for the user, then turn the same artifact/status surfaces into the smallest local GUI/operator view. Keep semantic acceptance review-gated, and do not build a broad ambient dispatcher, GUI-as-source-of-truth, arbitrary specialist marketplace, or alternate job backend for the MVP.
+  next_action: Scaffold `apps/epiphany-gui` as a Tauri v2 + React local operator console over the existing app-server status/coordinator/role/reorient/artifact surfaces. First slice is read-only: render active thread, coordinator recommendation, pressure/CRRC/reorient status, role lanes, job progress, reviewable findings, and artifact bundle links without becoming a source of truth.