feat: --browser CLI flag & session discovery (#242)

* feat: add --browser CLI flag and session discovery (#135)

- Add `--browser <name>` global flag to override which browser opens
  (sets PLANNOTATOR_BROWSER, works with existing openBrowser() logic)
- Add `plannotator sessions` subcommand to list active server sessions
  with `--open [N]` to reopen in browser and `--clean` to prune stale entries
- Track active sessions in ~/.plannotator/sessions/<pid>.json with
  automatic stale cleanup via PID liveness checks
- Register/unregister sessions in all three server modes (plan, review, annotate)
- Export ./sessions and ./project from @plannotator/server package

Closes #135

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* test: add integration test for session discovery

Non-interactive test script that validates:
- Session file creation/cleanup lifecycle
- Session file content (all fields)
- `plannotator sessions` listing, --open, --clean
- Stale PID auto-cleanup

Also syncs bun.lock versions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: add --browser flag and session discovery to configuration page

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: add troubleshooting page

Covers lost tabs (sessions --open), data storage locations,
browser issues, and hook not firing.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: backnotprop

apps/hook/server/index.ts

@@ -1,7 +1,7 @@
 /**
  * Plannotator CLI for Claude Code
  *
- * Supports three modes:
+ * Supports four modes:
  *
  * 1. Plan Review (default, no args):
  *    - Spawned by ExitPlanMode hook
@@ -18,6 +18,14 @@
  *    - Opens any markdown file in the annotation UI
  *    - Outputs structured feedback to stdout
  *
+ * 4. Sessions (`plannotator sessions`):
+ *    - Lists active Plannotator server sessions
+ *    - `--open [N]` reopens a session in the browser
+ *    - `--clean` removes stale session files
+ *
+ * Global flags:
+ *   --browser <name>   - Override which browser to open (e.g. "Google Chrome")
+ *
  * Environment variables:
  *   PLANNOTATOR_REMOTE - Set to "1" or "true" for remote mode (preferred)
  *   PLANNOTATOR_PORT   - Fixed port to use (default: random locally, 19432 for remote)
@@ -38,6 +46,10 @@ import {
 import { getGitContext, runGitDiff } from "@plannotator/server/git";
 import { writeRemoteShareLink } from "@plannotator/server/share-url";
 import { resolveMarkdownFile } from "@plannotator/server/resolve-file";
+import { registerSession, unregisterSession, listSessions } from "@plannotator/server/sessions";
+import { openBrowser } from "@plannotator/server/browser";
+import { detectProjectName } from "@plannotator/server/project";
+import path from "path";
 
 // Embed the built HTML at compile time
 // @ts-ignore - Bun import attribute for text
@@ -51,6 +63,16 @@ const reviewHtmlContent = reviewHtml as unknown as string;
 // Check for subcommand
 const args = process.argv.slice(2);
 
+// Global flag: --browser <name>
+const browserIdx = args.indexOf("--browser");
+if (browserIdx !== -1 && args[browserIdx + 1]) {
+  process.env.PLANNOTATOR_BROWSER = args[browserIdx + 1];
+  args.splice(browserIdx, 2);
+}
+
+// Ensure session cleanup on exit
+process.on("exit", () => unregisterSession());
+
 // Check if URL sharing is enabled (default: true)
 const sharingEnabled = process.env.PLANNOTATOR_SHARE !== "disabled";
 
@@ -60,7 +82,52 @@ const shareBaseUrl = process.env.PLANNOTATOR_SHARE_URL || undefined;
 // Paste service URL for short URL sharing
 const pasteApiUrl = process.env.PLANNOTATOR_PASTE_URL || undefined;
 
-if (args[0] === "review") {
+if (args[0] === "sessions") {
+  // ============================================
+  // SESSION DISCOVERY MODE
+  // ============================================
+
+  if (args.includes("--clean")) {
+    // Force cleanup: list sessions (which auto-removes stale entries)
+    const sessions = listSessions();
+    console.error(`Cleaned up stale sessions. ${sessions.length} active session(s) remain.`);
+    process.exit(0);
+  }
+
+  const sessions = listSessions();
+
+  if (sessions.length === 0) {
+    console.error("No active Plannotator sessions.");
+    process.exit(0);
+  }
+
+  const openIdx = args.indexOf("--open");
+  if (openIdx !== -1) {
+    // Open a session in the browser
+    const nArg = args[openIdx + 1];
+    const n = nArg ? parseInt(nArg, 10) : 1;
+    const session = sessions[n - 1];
+    if (!session) {
+      console.error(`Session #${n} not found. ${sessions.length} active session(s).`);
+      process.exit(1);
+    }
+    await openBrowser(session.url);
+    console.error(`Opened ${session.mode} session in browser: ${session.url}`);
+    process.exit(0);
+  }
+
+  // List sessions as a table
+  console.error("Active Plannotator sessions:\n");
+  for (let i = 0; i < sessions.length; i++) {
+    const s = sessions[i];
+    const age = Math.round((Date.now() - new Date(s.startedAt).getTime()) / 60000);
+    const ageStr = age < 60 ? `${age}m` : `${Math.floor(age / 60)}h ${age % 60}m`;
+    console.error(`  #${i + 1}  ${s.mode.padEnd(9)} ${s.project.padEnd(20)} ${s.url.padEnd(28)} ${ageStr} ago`);
+  }
+  console.error(`\nReopen with: plannotator sessions --open [N]`);
+  process.exit(0);
+
+} else if (args[0] === "review") {
   // ============================================
   // CODE REVIEW MODE
   // ============================================
@@ -74,6 +141,8 @@ if (args[0] === "review") {
     gitContext.defaultBranch
   );
 
+  const reviewProject = (await detectProjectName()) ?? "_unknown";
+
   // Start review server (even if empty - user can switch diff types)
   const server = await startReviewServer({
     rawPatch,
@@ -94,6 +163,16 @@ if (args[0] === "review") {
     },
   });
 
+  registerSession({
+    pid: process.pid,
+    port: server.port,
+    url: server.url,
+    mode: "review",
+    project: reviewProject,
+    startedAt: new Date().toISOString(),
+    label: `review-${reviewProject}`,
+  });
+
   // Wait for user feedback
   const result = await server.waitForDecision();
 
@@ -150,6 +229,8 @@ if (args[0] === "review") {
   console.error(`Resolved: ${absolutePath}`);
   const markdown = await Bun.file(absolutePath).text();
 
+  const annotateProject = (await detectProjectName()) ?? "_unknown";
+
   // Start the annotate server (reuses plan editor HTML)
   const server = await startAnnotateServer({
     markdown,
@@ -167,6 +248,16 @@ if (args[0] === "review") {
     },
   });
 
+  registerSession({
+    pid: process.pid,
+    port: server.port,
+    url: server.url,
+    mode: "annotate",
+    project: annotateProject,
+    startedAt: new Date().toISOString(),
+    label: `annotate-${path.basename(absolutePath)}`,
+  });
+
   // Wait for user feedback
   const result = await server.waitForDecision();
 
@@ -204,6 +295,8 @@ if (args[0] === "review") {
     process.exit(1);
   }
 
+  const planProject = (await detectProjectName()) ?? "_unknown";
+
   // Start the plan review server
   const server = await startPlannotatorServer({
     plan: planContent,
@@ -222,6 +315,16 @@ if (args[0] === "review") {
     },
   });
 
+  registerSession({
+    pid: process.pid,
+    port: server.port,
+    url: server.url,
+    mode: "plan",
+    project: planProject,
+    startedAt: new Date().toISOString(),
+    label: `plan-${planProject}`,
+  });
+
   // Wait for user decision (blocks until approve/deny)
   const result = await server.waitForDecision();
 

apps/marketing/src/content/docs/getting-started/configuration.md

@@ -82,6 +82,26 @@ export PLANNOTATOR_BROWSER="/usr/bin/firefox"
 export PLANNOTATOR_BROWSER="/path/to/my-open-script.sh"
 ```
 
+For one-off overrides without changing your shell profile, use the `--browser` flag:
+
+```bash
+plannotator review --browser "Safari"
+plannotator annotate plan.md --browser "Firefox"
+```
+
+## Session discovery
+
+If you accidentally close a Plannotator browser tab, the server is still running — you just need the URL. The `sessions` subcommand lists active sessions and can reopen them:
+
+```bash
+plannotator sessions              # list active sessions
+plannotator sessions --open       # reopen most recent session
+plannotator sessions --open 2     # reopen a specific session
+plannotator sessions --clean      # remove stale session files
+```
+
+Sessions are tracked automatically. Stale entries from crashed processes are cleaned up on the next listing.
+
 ## Disabling sharing
 
 Set `PLANNOTATOR_SHARE=disabled` to remove all sharing UI — the Share tab, copy link action, and import review option are all hidden. Useful for teams working with sensitive plans.

apps/marketing/src/content/docs/guides/troubleshooting.md

@@ -0,0 +1,65 @@
+---
+title: "Troubleshooting"
+description: "Common issues and how to resolve them."
+sidebar:
+  order: 24
+section: "Guides"
+---
+
+## Lost a Plannotator tab?
+
+If you accidentally close a Plannotator browser tab, the server is still running in the background. You can find and reopen it:
+
+```bash
+plannotator sessions
+```
+
+This lists all active sessions with their mode, project, URL, and how long they've been running:
+
+```
+Active Plannotator sessions:
+
+  #1  review    my-project           http://localhost:54321    3m ago
+  #2  plan      my-project           http://localhost:12345    15m ago
+
+Reopen with: plannotator sessions --open [N]
+```
+
+To reopen one:
+
+```bash
+plannotator sessions --open       # reopens the most recent
+plannotator sessions --open 2     # reopens session #2
+```
+
+Stale sessions from crashed processes are cleaned up automatically. You can also force cleanup with `plannotator sessions --clean`.
+
+## Where does Plannotator store data?
+
+All local data lives under `~/.plannotator/`:
+
+| Directory | What's in it |
+|-----------|-------------|
+| `plans/` | Snapshots of approved and denied plans. Controlled by the "Save plans" toggle in Settings. |
+| `history/` | Automatic version history for every plan, organized by project and heading. Powers the plan diff and version browser. |
+| `drafts/` | Auto-saved annotation drafts. If a server crashes mid-review, your in-progress annotations are recovered on the next session. |
+| `sessions/` | Temporary session files for active servers. Cleaned up automatically when a server exits. |
+
+Plan saving is enabled by default. You can change the save directory or disable it entirely in the Plannotator UI settings (gear icon).
+
+## Browser doesn't open
+
+If the UI doesn't open automatically, check:
+
+- **Remote/SSH session?** Set `PLANNOTATOR_REMOTE=1` and `PLANNOTATOR_PORT` to a port you'll forward. See the [remote guide](/docs/guides/remote-and-devcontainers/).
+- **Wrong browser?** Set `PLANNOTATOR_BROWSER` to the app name or path, or use `--browser` for a one-off override.
+- **URL still works** — even if the browser didn't open, the server is running. Check `plannotator sessions` for the URL and open it manually.
+
+## Hook doesn't fire
+
+If `ExitPlanMode` doesn't trigger Plannotator:
+
+1. Make sure the plugin is installed: `/plugin install plannotator@plannotator`
+2. Restart Claude Code after installing (hooks load on startup)
+3. Verify `plannotator` is on your PATH: `which plannotator`
+4. Check that plan mode is enabled in your Claude Code session

apps/marketing/src/content/docs/reference/environment-variables.md

@@ -14,7 +14,7 @@ All Plannotator environment variables and their defaults.
 |----------|---------|-------------|
 | `PLANNOTATOR_REMOTE` | auto-detect | Set to `1` or `true` to force remote mode. Uses fixed port and skips browser auto-open. |
 | `PLANNOTATOR_PORT` | random (local) / `19432` (remote) | Fixed server port. When not set, local sessions use a random port; remote sessions default to `19432`. |
-| `PLANNOTATOR_BROWSER` | system default | Custom browser to open the UI in. macOS: app name or path. Linux/Windows: executable path. Can also be a script. Takes priority over `BROWSER`. |
+| `PLANNOTATOR_BROWSER` | system default | Custom browser to open the UI in. macOS: app name or path. Linux/Windows: executable path. Can also be a script. Takes priority over `BROWSER`. Also settable per-invocation with `--browser`. |
 | `BROWSER` | (none) | Standard env var for specifying a browser. VS Code sets this automatically in devcontainers. Used as fallback when `PLANNOTATOR_BROWSER` is not set. |
 | `PLANNOTATOR_SHARE` | enabled | Set to `disabled` to turn off sharing. Hides share UI and import options. |
 | `PLANNOTATOR_SHARE_URL` | `https://share.plannotator.ai` | Base URL for share links. Set this when self-hosting the share portal. |

bun.lock

@@ -15,7 +15,9 @@
     "./git": "./git.ts",
     "./repo": "./repo.ts",
     "./share-url": "./share-url.ts",
-    "./resolve-file": "./resolve-file.ts"
+    "./resolve-file": "./resolve-file.ts",
+    "./sessions": "./sessions.ts",
+    "./project": "./project.ts"
   },
   "files": [
     "*.ts"