Fix daemon routing and session lifecycle

Author: backnotprop

AGENTS.md

@@ -96,6 +96,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):

apps/hook/server/index.ts

@@ -383,17 +383,20 @@ function getPluginOrigin(request: Partial<PluginBaseRequest>): PluginClientOrigi
   return origin;
 }
 
+function getInvocationCwd(): string {
+  return process.env.PLANNOTATOR_CWD || process.cwd();
+}
+
 function resolvePluginCwd(request: Partial<PluginBaseRequest>): string {
-  if (!request.cwd) return process.cwd();
-  const cwd = path.resolve(request.cwd);
+  const cwd = path.resolve(request.cwd || getInvocationCwd());
   try {
     if (!statSync(cwd).isDirectory()) {
-      emitPluginError("invalid-cwd", `Invalid cwd: ${request.cwd}`);
+      emitPluginError("invalid-cwd", `Invalid cwd: ${request.cwd || cwd}`);
     }
   } catch (err) {
     emitPluginError(
       "invalid-cwd",
-      err instanceof Error ? err.message : `Invalid cwd: ${request.cwd}`,
+      err instanceof Error ? err.message : `Invalid cwd: ${request.cwd || cwd}`,
     );
   }
   return cwd;
@@ -420,7 +423,7 @@ async function ensureDaemonClient(options: { pluginError?: boolean } = {}) {
 
   const command = getDaemonStartCommand();
   const child = Bun.spawn(command, {
-    cwd: process.cwd(),
+    cwd: getInvocationCwd(),
     stdin: "ignore",
     stdout: "ignore",
     stderr: "ignore",
@@ -476,7 +479,10 @@ async function runDaemonSessionRequest(request: PluginRequest, options: { plugin
     fail(completed.error.code, completed.error.message);
   }
   if (completed.session.status !== "completed") {
-    fail(completed.session.status, completed.session.status);
+    fail(
+      completed.session.status,
+      completed.session.error ?? `Plannotator session ${completed.session.id} ended with status ${completed.session.status}.`,
+    );
   }
 
   return {
@@ -640,7 +646,7 @@ if (args[0] === "sessions") {
   const outcome = await runDaemonSessionRequest({
     action: "review",
     origin: detectedOrigin,
-    cwd: process.cwd(),
+    cwd: getInvocationCwd(),
     args: args.slice(1).join(" "),
     sharingEnabled,
     shareBaseUrl,
@@ -673,7 +679,7 @@ if (args[0] === "sessions") {
   const outcome = await runDaemonSessionRequest({
     action: "annotate",
     origin: detectedOrigin,
-    cwd: process.cwd(),
+    cwd: getInvocationCwd(),
     args: rawFilePath,
     noJina: cliNoJina,
     gate: gateFlag,
@@ -690,7 +696,7 @@ if (args[0] === "sessions") {
   // ANNOTATE LAST MESSAGE MODE
   // ============================================
 
-  const projectRoot = process.env.PLANNOTATOR_CWD || process.cwd();
+  const projectRoot = getInvocationCwd();
   const codexThreadId = process.env.CODEX_THREAD_ID;
   const isCodex = !!codexThreadId;
 
@@ -773,7 +779,7 @@ if (args[0] === "sessions") {
   const outcome = await runDaemonSessionRequest({
     action: "annotate-last",
     origin: detectedOrigin,
-    cwd: process.cwd(),
+    cwd: projectRoot,
     markdown: lastMessage.text,
     filePath: "last-message",
     mode: "annotate-last",
@@ -794,7 +800,7 @@ if (args[0] === "sessions") {
   await runDaemonSessionRequest({
     action: "archive",
     origin: detectedOrigin,
-    cwd: process.cwd(),
+    cwd: getInvocationCwd(),
     sharingEnabled,
     shareBaseUrl,
     pasteApiUrl,
@@ -836,7 +842,7 @@ if (args[0] === "sessions") {
   const outcome = await runDaemonSessionRequest({
     action: "plan",
     origin: "copilot-cli",
-    cwd: event.cwd || process.cwd(),
+    cwd: event.cwd || getInvocationCwd(),
     plan: planContent,
     sharingEnabled,
     shareBaseUrl,
@@ -868,7 +874,7 @@ if (args[0] === "sessions") {
   // COPILOT CLI ANNOTATE LAST MESSAGE MODE
   // ============================================
 
-  const projectRoot = process.env.PLANNOTATOR_CWD || process.cwd();
+  const projectRoot = getInvocationCwd();
 
   if (process.env.PLANNOTATOR_DEBUG) {
     console.error(`[DEBUG] Copilot CLI detected, finding session for CWD: ${projectRoot}`);
@@ -984,7 +990,7 @@ if (args[0] === "sessions") {
     const outcome = await runDaemonSessionRequest({
       action: "plan",
       origin: "codex",
-      cwd: process.cwd(),
+      cwd: getInvocationCwd(),
       plan: latestPlan.text,
       sharingEnabled,
       shareBaseUrl,
@@ -1040,7 +1046,7 @@ if (args[0] === "sessions") {
   const outcome = await runDaemonSessionRequest({
     action: "plan",
     origin: isGemini ? "gemini-cli" : detectedOrigin,
-    cwd: process.cwd(),
+    cwd: getInvocationCwd(),
     plan: planContent,
     permissionMode,
     sharingEnabled,

packages/server/daemon/client.ts

@@ -86,11 +86,50 @@ function stateBaseUrl(state: unknown): string | undefined {
   return typeof baseUrl === "string" ? baseUrl : undefined;
 }
 
+function statePid(state: unknown): number | undefined {
+  const pid = (state as { pid?: unknown } | null)?.pid;
+  return typeof pid === "number" && Number.isInteger(pid) && pid > 0 ? pid : undefined;
+}
+
+function isProcessAlive(pid: number, options: DaemonClientOptions): boolean {
+  const isAlive = options.isAlive ?? ((targetPid: number) => {
+    try {
+      process.kill(targetPid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+  return isAlive(pid);
+}
+
+async function waitForProcessExit(pid: number, options: DaemonClientOptions): Promise<void> {
+  for (let attempt = 0; attempt < 10; attempt++) {
+    if (!isProcessAlive(pid, options)) return;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+}
+
 export async function cleanupDaemonState(state: unknown, options: DaemonClientOptions = {}): Promise<void> {
   const fetchImpl = options.fetch ?? fetch;
   const baseUrl = stateBaseUrl(state);
+  let shutdownOk = false;
   if (baseUrl) {
-    await fetchImpl(`${baseUrl}/daemon/shutdown`, { method: "POST" }).catch(() => undefined);
+    try {
+      const response = await fetchImpl(`${baseUrl}/daemon/shutdown`, { method: "POST" });
+      shutdownOk = response.ok;
+    } catch {
+      shutdownOk = false;
+    }
+  }
+  const pid = statePid(state);
+  if (baseUrl && !shutdownOk && pid && isProcessAlive(pid, options)) {
+    try {
+      process.kill(pid, "SIGTERM");
+      await waitForProcessExit(pid, options);
+    } catch {
+      // Best effort; removing the stale state lets the caller start or report the real port error.
+    }
   }
   removeDaemonFiles(options);
 }

packages/server/daemon/server.test.ts

@@ -23,7 +23,7 @@ function makeHandler() {
       url: "http://127.0.0.1:4321/s/s1",
       project: "repo",
       label: "plan-repo",
-      htmlContent: "<html><head></head><body>Plan</body></html>",
+      htmlContent: "<html><script>const literal='</head>';</script><head></head><body>Plan</body></html>",
       handleRequest: (_req, url) => Response.json({ path: url.pathname }),
     }),
   });
@@ -44,6 +44,7 @@ describe("daemon HTTP router", () => {
     const { handler } = makeHandler();
     await handler(new Request("http://127.0.0.1:4321/daemon/sessions", {
       method: "POST",
+      headers: { "content-type": "application/json" },
       body: JSON.stringify({ request: { action: "plan", origin: "opencode", plan: "x" } }),
     }));
     const res = await handler(new Request("http://127.0.0.1:4321/daemon/status"));
@@ -58,6 +59,7 @@ describe("daemon HTTP router", () => {
     const { handler } = makeHandler();
     const create = await handler(new Request("http://127.0.0.1:4321/daemon/sessions", {
       method: "POST",
+      headers: { "content-type": "application/json" },
       body: JSON.stringify({ request: { action: "plan", origin: "opencode", plan: "x" } }),
     }));
     expect(create.status).toBe(201);
@@ -74,6 +76,7 @@ describe("daemon HTTP router", () => {
     const { handler } = makeHandler();
     await handler(new Request("http://127.0.0.1:4321/daemon/sessions", {
       method: "POST",
+      headers: { "content-type": "application/json" },
       body: JSON.stringify({ request: { action: "plan", origin: "opencode", plan: "x" } }),
     }));
     const res = await handler(new Request("http://127.0.0.1:4321/s/s1"));
@@ -82,12 +85,15 @@ describe("daemon HTTP router", () => {
     expect(html).toContain("apiBase=\"/s/s1/api\"");
     expect(html).toContain("window.fetch");
     expect(html).toContain("window.EventSource");
+    expect(html.indexOf("window.__PLANNOTATOR_API_BASE__")).toBeGreaterThan(html.indexOf("const literal"));
+    expect(html.indexOf("window.__PLANNOTATOR_API_BASE__")).toBeLessThan(html.indexOf("<body>"));
   });
 
   test("routes session-scoped API paths to the owning session", async () => {
     const { handler } = makeHandler();
     await handler(new Request("http://127.0.0.1:4321/daemon/sessions", {
       method: "POST",
+      headers: { "content-type": "application/json" },
       body: JSON.stringify({ request: { action: "plan", origin: "opencode", plan: "x" } }),
     }));
     const res = await handler(new Request("http://127.0.0.1:4321/s/s1/api/plan"));
@@ -100,6 +106,7 @@ describe("daemon HTTP router", () => {
     let timeoutDisabled = 0;
     await handler(new Request("http://127.0.0.1:4321/daemon/sessions", {
       method: "POST",
+      headers: { "content-type": "application/json" },
       body: JSON.stringify({ request: { action: "plan", origin: "opencode", plan: "x" } }),
     }));
     const record = store.get("s1");
@@ -118,23 +125,36 @@ describe("daemon HTTP router", () => {
     expect(timeoutDisabled).toBe(1);
   });
 
-  test("routes legacy root API paths by session referer during UI migration", async () => {
+  test("does not route root API paths by spoofable referer", async () => {
     const { handler } = makeHandler();
     await handler(new Request("http://127.0.0.1:4321/daemon/sessions", {
       method: "POST",
+      headers: { "content-type": "application/json" },
       body: JSON.stringify({ request: { action: "plan", origin: "opencode", plan: "x" } }),
     }));
     const res = await handler(new Request("http://127.0.0.1:4321/api/plan", {
       headers: { referer: "http://127.0.0.1:4321/s/s1" },
     }));
+    expect(res.status).toBe(404);
+  });
+
+  test("rejects non-JSON session creation requests", async () => {
+    const { handler } = makeHandler();
+    const res = await handler(new Request("http://127.0.0.1:4321/daemon/sessions", {
+      method: "POST",
+      headers: { "content-type": "text/plain" },
+      body: JSON.stringify({ request: { action: "plan", origin: "opencode", plan: "x" } }),
+    }));
     const body = await res.json();
-    expect(body.path).toBe("/api/plan");
+    expect(res.status).toBe(415);
+    expect(body.error.code).toBe("invalid-request");
   });
 
   test("cancels sessions and returns result status", async () => {
     const { handler, store } = makeHandler();
     await handler(new Request("http://127.0.0.1:4321/daemon/sessions", {
       method: "POST",
+      headers: { "content-type": "application/json" },
       body: JSON.stringify({ request: { action: "plan", origin: "opencode", plan: "x" } }),
     }));
     const cancel = await handler(new Request("http://127.0.0.1:4321/daemon/sessions/s1/cancel", {
@@ -143,7 +163,9 @@ describe("daemon HTTP router", () => {
     expect((await cancel.json()).session.status).toBe("cancelled");
 
     const result = await handler(new Request("http://127.0.0.1:4321/daemon/sessions/s1/result"));
-    expect((await result.json()).session.status).toBe("cancelled");
-    expect(store.get("s1")).toBeUndefined();
+    const body = await result.json();
+    expect(body.session.status).toBe("cancelled");
+    expect(body.session.error).toBe("Session cancelled.");
+    expect(store.get("s1")).toBeDefined();
   });
 });

packages/server/daemon/server.ts

@@ -9,6 +9,8 @@ import type { DaemonState } from "./state";
 import { DaemonSessionStore, type DaemonSessionRecord } from "./session-store";
 import type { SessionRequestContext } from "../session-handler";
 
+const RESULT_DELETE_GRACE_MS = 2_000;
+
 export interface DaemonServerOptions {
   state: DaemonState;
   store?: DaemonSessionStore;
@@ -44,15 +46,16 @@ function sessionFromPath(pathname: string): { id: string; rest: string } | null
   };
 }
 
-function sessionIdFromReferer(req: Request): string | null {
-  const referer = req.headers.get("referer");
-  if (!referer) return null;
-  try {
-    const url = new URL(referer);
-    return sessionFromPath(url.pathname)?.id ?? null;
-  } catch {
-    return null;
-  }
+function isJsonRequest(req: Request): boolean {
+  const contentType = req.headers.get("content-type") ?? "";
+  return contentType.split(";")[0].trim().toLowerCase() === "application/json";
+}
+
+function injectApiBase(html: string, apiBaseScript: string): string {
+  const marker = "</head>";
+  const index = html.lastIndexOf(marker);
+  if (index === -1) return `${apiBaseScript}${html}`;
+  return `${html.slice(0, index)}${apiBaseScript}${html.slice(index)}`;
 }
 
 export function createDaemonFetchHandler(options: DaemonServerOptions) {
@@ -66,8 +69,7 @@ export function createDaemonFetchHandler(options: DaemonServerOptions) {
 
   const context: DaemonFetchContext = { endpoint, store };
 
-  return Object.assign(
-    async function daemonFetch(req: Request, requestContext?: SessionRequestContext): Promise<Response> {
+  return async function daemonFetch(req: Request, requestContext?: SessionRequestContext): Promise<Response> {
       const url = new URL(req.url);
 
       if (url.pathname === "/daemon/capabilities" && req.method === "GET") {
@@ -94,6 +96,9 @@ export function createDaemonFetchHandler(options: DaemonServerOptions) {
       }
 
       if (url.pathname === "/daemon/sessions" && req.method === "POST") {
+        if (!isJsonRequest(req)) {
+          return json(createDaemonErrorResponse("invalid-request", "Daemon session requests must use application/json."), { status: 415 });
+        }
         let body: DaemonCreateSessionRequest;
         try {
           body = await req.json() as DaemonCreateSessionRequest;
@@ -127,7 +132,8 @@ export function createDaemonFetchHandler(options: DaemonServerOptions) {
         if (action === "result" && req.method === "GET") {
           const completed = await store.waitForResult(id);
           const response = json({ ok: true, session: store.summary(completed), result: completed.result ?? null });
-          void store.delete(id);
+          const timer = setTimeout(() => void store.delete(id), RESULT_DELETE_GRACE_MS);
+          timer.unref?.();
           return response;
         }
 
@@ -147,20 +153,6 @@ export function createDaemonFetchHandler(options: DaemonServerOptions) {
         return json({ ok: true, shuttingDown: true });
       }
 
-      if (url.pathname === "/api" || url.pathname.startsWith("/api/")) {
-        const id = sessionIdFromReferer(req);
-        if (id) {
-          const record = store.get(id);
-          if (!record) {
-            return new Response("Session not found", { status: 404 });
-          }
-          if (!record.handleRequest) {
-            return new Response("Session has no API handler", { status: 404 });
-          }
-          return record.handleRequest(req, url, requestContext);
-        }
-      }
-
       const browserSession = sessionFromPath(url.pathname);
       if (browserSession) {
         const record = store.get(browserSession.id);
@@ -177,14 +169,12 @@ export function createDaemonFetchHandler(options: DaemonServerOptions) {
         if (record.htmlContent) {
           const apiBase = `/s/${record.id}/api`;
           const apiBaseScript = `<script>(()=>{const apiBase=${JSON.stringify(apiBase)};window.__PLANNOTATOR_API_BASE__=apiBase;const rewrite=(input)=>{if(typeof input==="string"&&input.startsWith("/api/"))return apiBase+input.slice(4);if(input instanceof URL&&input.pathname.startsWith("/api/")){const next=new URL(input.toString());next.pathname=apiBase+input.pathname.slice(4);return next;}return input;};const originalFetch=window.fetch?.bind(window);if(originalFetch)window.fetch=(input,init)=>originalFetch(rewrite(input),init);const OriginalEventSource=window.EventSource;if(OriginalEventSource){window.EventSource=function(url,init){return new OriginalEventSource(rewrite(url),init)};window.EventSource.prototype=OriginalEventSource.prototype;}})();</script>`;
-          return new Response(record.htmlContent.replace("</head>", `${apiBaseScript}</head>`), {
+          return new Response(injectApiBase(record.htmlContent, apiBaseScript), {
             headers: { "Content-Type": "text/html" },
           });
         }
       }
 
       return new Response("Not found", { status: 404 });
-    },
-    { context },
-  );
+    };
 }