backnotprop · backnotprop · May 27, 2026 · May 18, 2026 · May 27, 2026
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -170,22 +170,29 @@ jobs:
             local ok=0
 
             for _ in $(seq 1 60); do
-              if curl -sf "http://127.0.0.1:${port}${endpoint}" -o /dev/null 2>/dev/null; then
-                ok=1
-                break
+              local sessions
+              sessions="$(curl -sf "http://127.0.0.1:${port}/daemon/sessions" 2>/dev/null || true)"
+              if [ -n "$sessions" ]; then
+                local session_url
+                session_url="$(python3 -c 'import json,sys; data=json.load(sys.stdin); sessions=data.get("sessions") or []; print(sessions[0].get("url","") if sessions else "")' <<< "$sessions")"
+                if [ -n "$session_url" ] && curl -sf "${session_url}${endpoint}" -o /dev/null 2>/dev/null; then
+                  ok=1
+                  break
+                fi
               fi
               sleep 0.5
             done
 
             kill "$pid" 2>/dev/null || true
             wait "$pid" 2>/dev/null || true
+            PLANNOTATOR_PORT="$port" "$BINARY" daemon stop >/dev/null 2>&1 || true
 
             if [ "$ok" = "0" ]; then
-              echo "FAIL: ${label} did not respond on :${port}${endpoint}"
+              echo "FAIL: ${label} did not expose a daemon-scoped ${endpoint}"
               exit 1
             fi
 
-            echo "OK: ${label} responded on :${port}${endpoint}"
+            echo "OK: ${label} exposed daemon-scoped ${endpoint}"
           }
 
           # 2. review: exercises server startup, bundled HTML, git diff, and HTTP.
@@ -232,9 +239,14 @@ jobs:
             try {
               for ($i = 0; $i -lt 60; $i++) {
                 try {
-                  Invoke-WebRequest -Uri "http://127.0.0.1:$Port$Endpoint" -UseBasicParsing -TimeoutSec 1 | Out-Null
-                  $ok = $true
-                  break
+                  $sessionsResponse = Invoke-WebRequest -Uri "http://127.0.0.1:$Port/daemon/sessions" -UseBasicParsing -TimeoutSec 1
+                  $sessionsBody = $sessionsResponse.Content | ConvertFrom-Json
+                  if ($sessionsBody.sessions.Count -gt 0) {
+                    $sessionUrl = $sessionsBody.sessions[0].url
+                    Invoke-WebRequest -Uri "$sessionUrl$Endpoint" -UseBasicParsing -TimeoutSec 1 | Out-Null
+                    $ok = $true
+                    break
+                  }
                 } catch {
                   if ($process.HasExited) {
                     break
@@ -247,6 +259,7 @@ jobs:
                 Stop-Process -Id $process.Id -Force
                 Wait-Process -Id $process.Id -ErrorAction SilentlyContinue
               }
+              & $binary daemon stop *> $null
               Remove-Item Env:\PLANNOTATOR_PORT -ErrorAction SilentlyContinue
             }
 
@@ -255,10 +268,10 @@ jobs:
               Get-Content $stdout -ErrorAction SilentlyContinue
               Write-Host "stderr:"
               Get-Content $stderr -ErrorAction SilentlyContinue
-              throw "FAIL: $Label did not respond on :$Port$Endpoint"
+              throw "FAIL: $Label did not expose a daemon-scoped $Endpoint"
             }
 
-            Write-Host "OK: $Label responded on :$Port$Endpoint"
+            Write-Host "OK: $Label exposed daemon-scoped $Endpoint"
           }
 
           # 2. review: exercises server startup, bundled HTML, git diff, and HTTP.

diff --git a/.gitignore b/.gitignore
@@ -52,6 +52,4 @@ opencode.json
 plannotator-local
 # Local research/reference docs (not for repo)
 /reference/
-# Local goal setup packages generated by the setup-goal skill.
-/goals/
 *.bun-build
diff --git a/AGENTS.md b/AGENTS.md
@@ -44,6 +44,7 @@ plannotator/
 │   │   ├── index.ts              # startPlannotatorServer(), handleServerReady()
 │   │   ├── review.ts             # startReviewServer(), handleReviewServerReady()
 │   │   ├── annotate.ts           # startAnnotateServer(), handleAnnotateServerReady()
+│   │   ├── daemon/               # Long-running daemon runtime, state, client, and session store
 │   │   ├── storage.ts            # Re-exports from @plannotator/shared/storage
 │   │   ├── share-url.ts          # Server-side share URL generation for remote sessions
 │   │   ├── remote.ts             # isRemoteSession(), getServerPort()
@@ -99,6 +100,8 @@ Plannotator has one server implementation:
 
 Claude Code runs this server through the released `plannotator` binary entrypoint. OpenCode and Pi do not package their own server implementations; they call the same binary through the plugin protocol in `packages/shared/plugin-protocol.ts`. Runtime-agnostic logic (store, validation, types) lives in `packages/shared/`.
 
+Daemon-backed commands run through one long-running `plannotator` process per user/machine environment. `plannotator daemon start|status|stop` manage that lifecycle, while normal plan/review/annotate/archive commands auto-start a compatible daemon and create session-scoped browser URLs at `/s/<sessionId>`. Browser API calls must use `/s/<sessionId>/api/...`; root `/api/...` routes are not a daemon session boundary.
+
 ## Installation
 
 **Via plugin marketplace** (when repo is public):
@@ -133,6 +136,7 @@ claude --plugin-dir ./apps/hook
 **Config-only settings (`~/.plannotator/config.json`)**: Some settings have no env-var equivalent and are toggled by editing the config file directly:
 
 - `pfmReminder` (`true` / `false`, default `false`) — when enabled, a Plannotator Flavored Markdown reminder is injected at plan-time describing the renderer's extensions (code-file links, callouts, tables, diagrams, task lists, hex swatches, wiki-links). Lets the planning agent enrich plans with PFM features without having to discover them. Composes cleanly with the compound-skill improvement hook. Supported across all three runtimes: Claude Code (`improve-context` PreToolUse hook in `apps/hook/server/index.ts`), OpenCode (`experimental.chat.system.transform` in `apps/opencode-plugin/index.ts`), and Pi (`before_agent_start` in `apps/pi-extension/index.ts`).
+- `legacyTabMode` (`true` / `false`, default `false`) — when enabled, the daemon opens a new browser tab for every session regardless of whether a frontend is already connected. Sessions use the full-screen `CompletionOverlay` with auto-close instead of the inline `CompletionBanner`. Preserves the pre-frontend tab-per-session behavior for users who prefer it.
 
 **Legacy:** `SSH_TTY` and `SSH_CONNECTION` are still detected when `PLANNOTATOR_REMOTE` is unset. Set `PLANNOTATOR_REMOTE=1` / `true` to force remote mode or `0` / `false` to force local mode.
 
@@ -216,6 +220,49 @@ During normal plan review, an Archive sidebar tab provides the same browsing via
 
 ## Server API
 
+### Daemon Runtime (`packages/server/daemon/`)
+
+The daemon is the single long-running Bun server used by normal plan/review/annotate/archive commands. It owns a session store and exposes browser sessions at `/s/<sessionId>`. Session browser APIs are scoped under `/s/<sessionId>/api/...`; root `/api/...` is not a valid daemon session API boundary.
+
+| Endpoint              | Method | Purpose                                    |
+| --------------------- | ------ | ------------------------------------------ |
+| `/daemon/capabilities` | GET | Return daemon protocol/capability metadata |
+| `/daemon/status` | GET | Return daemon process, endpoint, and session counts |
+| `/daemon/sessions` | GET | List active sessions (`?clean=1` also reaps expired sessions before listing) |
+| `/daemon/sessions` | POST | Create a plan/review/annotate/archive session from a plugin-protocol request |
+| `/daemon/sessions/:id` | GET | Fetch a session summary |
+| `/daemon/sessions/:id/result` | GET | Wait for a session decision/result |
+| `/daemon/sessions/:id/cancel` | POST | Cancel a session and dispose its resources |
+| `/daemon/sessions/:id` | DELETE | Delete a session record |
+| `/daemon/shutdown` | POST | Ask the daemon to stop |
+| `/daemon/config` | GET | Read global config (`~/.plannotator/config.json`) |
+| `/daemon/config` | POST | Write global config keys (allowlisted: `displayName`, `pfmReminder`, `legacyTabMode`, `diffOptions`, `conventionalComments`, `conventionalLabels`) |
+| `/daemon/git/user` | GET | Return git user name from `git config user.name` |
+| `/daemon/vaults` | GET | Detect available Obsidian vaults |
+| `/daemon/obsidian/vaults` | GET | Alias for `/daemon/vaults` |
+| `/daemon/hooks/status` | GET | Return PFM reminder and improvement hook status |
+| `/daemon/projects` | DELETE | Remove a project by `?cwd=` (optional `?clean=1` to cancel active sessions) |
+| `/daemon/projects/prs` | GET | List open PRs for a project (`?cwd=`) |
+| `/daemon/projects/prs/detailed` | GET | List PRs with review metadata for dashboard (`?cwd=`) |
+| `/daemon/fs/list` | GET | List directory contents (`?path=`) |
+| `/daemon/ws` | WebSocket | Multiplex daemon lifecycle events, session-scoped external annotation events, agent job events, session revision events, and correlated session actions |
+| `/s/:id` | GET | Serve the browser HTML for a session |
+| `/s/:id/api/...` | Any | Route browser API requests to that session's plan/review/annotate handler |
+
+Runtime live updates for daemon lifecycle events, external annotations, agent jobs, and session revisions are delivered through `/daemon/ws`. Session-scoped updates subscribe by `{ family, sessionId }`. HTTP endpoints below remain for snapshots, mutations, uploads, and large payloads. AI query token streaming remains on `/api/ai/query`.
+
+### Session Persistence and Resubmission
+
+When a user denies a plan (or sends feedback on a review/annotation), the session enters `awaiting-resubmission` status instead of completing. The session's HTTP handler stays alive. When the agent replans and submits again via `POST /daemon/sessions`, the daemon matches the new submission to the existing session by a match key (`plan:project:slug` for plans, `review:project:branch` for reviews, `annotate:project:filePath` for single-file annotations). The session reactivates in place — the frontend receives a `session-revision` event via WebSocket with the updated content.
+
+**Sessions never die.** No session type calls `store.complete()` from its decision handler. All sessions survive feedback, approve, and exit — the HTTP handler stays alive and the tab keeps working. `registerPersistentDecision` always calls `store.suspend()`. `registerReviewDecision` always calls `store.idle()`. Non-terminal sessions have no expiry timer.
+
+**Session statuses (plan/annotate):** `active` → `awaiting-resubmission` (on any decision) → `active` (on resubmit) → `awaiting-resubmission` ... repeating.
+
+**Session statuses (code review):** `active` → `idle` (on any decision) → `active` (on agent resubmit) → `idle` ... repeating.
+
+**Event families:** `daemon`, `external-annotations`, `agent-jobs`, `session-revision`.
+
 ### Plan Server (`packages/server/index.ts`)
 
 | Endpoint              | Method | Purpose                                    |
@@ -239,8 +286,7 @@ During normal plan review, an Archive sidebar tab provides the same browsing via
 | `/api/draft`          | GET/POST/DELETE | Auto-save annotation drafts to survive server crashes |
 | `/api/editor-annotations` | GET | List editor annotations (VS Code only) |
 | `/api/editor-annotation` | POST/DELETE | Add or remove an editor annotation (VS Code only) |
-| `/api/external-annotations/stream` | GET | SSE stream for real-time external annotations |
-| `/api/external-annotations` | GET | Snapshot of external annotations (polling fallback, `?since=N` for version gating) |
+| `/api/external-annotations` | GET | Snapshot of external annotations (`?since=N` for version gating) |
 | `/api/external-annotations` | POST | Add external annotations (single or batch `{ annotations: [...] }`) |
 | `/api/external-annotations` | PATCH | Update fields on a single annotation (`?id=`) |
 | `/api/external-annotations` | DELETE | Remove by `?id=`, `?source=`, or clear all |
@@ -265,14 +311,12 @@ During normal plan review, an Archive sidebar tab provides the same browsing via
 | `/api/ai/abort` | POST | Abort the current query |
 | `/api/ai/permission` | POST | Respond to a permission request |
 | `/api/ai/sessions` | GET | List active sessions |
-| `/api/external-annotations/stream` | GET | SSE stream for real-time external annotations |
-| `/api/external-annotations` | GET | Snapshot of external annotations (polling fallback, `?since=N` for version gating) |
+| `/api/external-annotations` | GET | Snapshot of external annotations (`?since=N` for version gating) |
 | `/api/external-annotations` | POST | Add external annotations (single or batch `{ annotations: [...] }`) |
 | `/api/external-annotations` | PATCH | Update fields on a single annotation (`?id=`) |
 | `/api/external-annotations` | DELETE | Remove by `?id=`, `?source=`, or clear all |
 | `/api/agents/capabilities` | GET | Check available agent providers (claude, codex, tour) |
-| `/api/agents/jobs/stream` | GET | SSE stream for real-time agent job status updates |
-| `/api/agents/jobs` | GET | Snapshot of agent jobs (polling fallback, `?since=N` for version gating) |
+| `/api/agents/jobs` | GET | Snapshot of agent jobs (`?since=N` for version gating) |
 | `/api/agents/jobs` | POST | Launch an agent job (body: `{ provider, command, label }`) |
 | `/api/agents/jobs` | DELETE | Kill all running agent jobs |
 | `/api/agents/jobs/:id` | DELETE | Kill a specific agent job |
@@ -288,7 +332,9 @@ During normal plan review, an Archive sidebar tab provides the same browsing via
 
 | Endpoint              | Method | Purpose                                    |
 | --------------------- | ------ | ------------------------------------------ |
-| `/api/plan`           | GET    | Returns `{ plan, origin, mode: "annotate", filePath, sourceInfo?, gate, renderAs?, rawHtml? }` |
+| `/api/plan`           | GET    | Returns `{ plan, origin, mode: "annotate", filePath, sourceInfo?, gate, renderAs?, rawHtml?, previousPlan, versionInfo }` |
+| `/api/plan/version`   | GET    | Fetch specific version (`?v=N`) — single-file annotate only |
+| `/api/plan/versions`  | GET    | List all versions — single-file annotate only |
 | `/api/feedback`       | POST   | Submit annotations (body: feedback, annotations) |
 | `/api/approve`        | POST   | Approve without feedback (review-gate UX, `--gate`) |
 | `/api/exit`           | POST   | Close session without feedback |
@@ -297,8 +343,7 @@ During normal plan review, an Archive sidebar tab provides the same browsing via
 | `/api/doc`            | GET    | Serve linked .md/.mdx/.html file or code file (`?path=<path>&base=<dir>`) |
 | `/api/doc/exists`     | POST   | Batch-validate code-file paths (body: `{ paths: string[], base?: string }`) |
 | `/api/draft`          | GET/POST/DELETE | Auto-save annotation drafts to survive server crashes |
-| `/api/external-annotations/stream` | GET | SSE stream for real-time external annotations |
-| `/api/external-annotations` | GET | Snapshot of external annotations (polling fallback, `?since=N` for version gating) |
+| `/api/external-annotations` | GET | Snapshot of external annotations (`?since=N` for version gating) |
 | `/api/external-annotations` | POST | Add external annotations (single or batch `{ annotations: [...] }`) |
 | `/api/external-annotations` | PATCH | Update fields on a single annotation (`?id=`) |
 | `/api/external-annotations` | DELETE | Remove by `?id=`, `?source=`, or clear all |

diff --git a/apps/frontend/.oxfmtignore b/apps/frontend/.oxfmtignore
@@ -0,0 +1,2 @@
+dist
+src/routeTree.gen.ts
diff --git a/apps/frontend/README.md b/apps/frontend/README.md
@@ -0,0 +1,34 @@
+# @plannotator/debug-frontend
+
+Debug/development harness UI for the Plannotator daemon runtime. **Not production code** — this is a
+testbed for exercising daemon sessions, verifying event streams, and testing session lifecycle actions.
+
+## Shape
+
+- `src/routes` is only TanStack Router wiring.
+- `src/daemon` owns the typed daemon API client and contracts.
+- `src/sessions` owns session ids, session state, the dashboard, and mode dispatch.
+- `src/plan`, `src/review`, `src/annotate`, `src/archive`, and `src/setup-goal` own product views.
+- `src/testing` owns contract fixtures and browser helpers.
+
+The shell talks to session APIs through `/s/:sessionId/api`, never root `/api`.
+
+The build is intentionally single-file HTML for daemon serving. Separate static asset
+routes are deferred until the full UI migration needs code splitting or cacheable chunks.
+
+## Commands
+
+```bash
+bun run --cwd apps/debug-frontend dev
+bun run --cwd apps/debug-frontend build
+bun run --cwd apps/debug-frontend check
+bun run --cwd apps/debug-frontend test:browser
+```
+
+Or from the repo root:
+
+```bash
+bun run dev:debug-frontend
+bun run build:debug-frontend
+bun run check:debug-frontend
+```
diff --git a/apps/frontend/index.html b/apps/frontend/index.html
@@ -0,0 +1,23 @@
+<!doctype html>
+<html lang="en" class="theme-neutral">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Plannotator</title>
+    <script>
+      // Apply saved theme before React mounts to prevent flash of unstyled content.
+      // ThemeProvider will take over once mounted.
+      try {
+        const ct = document.cookie.match(/(?:^|; )plannotator-color-theme=([^;]*)/);
+        const theme = ct ? decodeURIComponent(ct[1]) : 'neutral';
+        const mt = document.cookie.match(/(?:^|; )plannotator-theme=([^;]*)/);
+        const mode = mt ? decodeURIComponent(mt[1]) : 'dark';
+        document.documentElement.className = 'theme-' + theme + (mode === 'light' ? ' light' : '');
+      } catch(e) {}
+    </script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
diff --git a/apps/frontend/package.json b/apps/frontend/package.json
@@ -0,0 +1,62 @@
+{
+  "name": "@plannotator/frontend",
+  "private": true,
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && bun run scripts/verify-single-file-build.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint . --fix",
+    "fmt": "oxfmt --ignore-path .oxfmtignore --write .",
+    "fmt:check": "oxfmt --ignore-path .oxfmtignore --check .",
+    "test": "vitest run --passWithNoTests",
+    "check": "bun run typecheck && bun run lint && bun run fmt:check && bun run test"
+  },
+  "dependencies": {
+    "@fontsource-variable/geist-mono": "^5.2.7",
+    "@fontsource-variable/instrument-sans": "^5.2.8",
+    "@fontsource-variable/inter": "^5.2.8",
+    "@plannotator/code-review": "workspace:*",
+    "@plannotator/plan-review": "workspace:*",
+    "@plannotator/shared": "workspace:*",
+    "@plannotator/ui": "workspace:*",
+    "@radix-ui/react-collapsible": "^1.1.12",
+    "@radix-ui/react-context-menu": "^2.2.16",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-label": "^2.1.8",
+    "@radix-ui/react-separator": "^1.1.8",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@radix-ui/react-tabs": "^1.1.13",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "@tanstack/react-router": "^1.141.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "immer": "^10.2.0",
+    "lucide-react": "^1.14.0",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.6.0",
+    "tailwindcss-animate": "^1.0.7",
+    "vaul": "^1.1.2",
+    "zustand": "^5.0.13"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.1.18",
+    "@tanstack/router-plugin": "^1.141.0",
+    "@types/node": "^22.14.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^5.0.0",
+    "oxfmt": "^0.17.0",
+    "oxlint": "^1.31.0",
+    "tailwindcss": "^4.1.18",
+    "typescript": "~5.8.2",
+    "vite": "^6.2.0",
+    "vite-plugin-singlefile": "^2.0.3",
+    "vitest": "^4.0.16"
+  }
+}