claude-code-session-manager 0.38.1 → 0.38.3

package/dist/index.html

@@ -7,7 +7,7 @@
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
     <link href="https://fonts.googleapis.com/css2?family=Newsreader:ital,opsz,wght@0,6..72,400;0,6..72,500;0,6..72,600;0,6..72,700;1,6..72,400&family=Geist:wght@300;400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
-    <script type="module" crossorigin src="./assets/index-CBSyk1aI.js"></script>
+    <script type="module" crossorigin src="./assets/index-BJRUaZ96.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/monaco-editor-BW5C4Iv1.js">
     <link rel="stylesheet" crossorigin href="./assets/monaco-editor-BTnBOi8r.css">
     <link rel="stylesheet" crossorigin href="./assets/index-DyOGjslF.css">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-session-manager",
-  "version": "0.38.1",
+  "version": "0.38.3",
   "description": "Local cockpit for the Claude Code CLI — multi-tab terminal, full config surface, scheduler, voice dictation, and live observability.",
   "type": "module",
   "main": "src/main/index.cjs",

package/plugins/session-manager-dev/skills/pr-review-sweep/1-classify/SKILL.md

@@ -38,6 +38,17 @@ there's a concrete failing case (a real input that breaks today); otherwise **fe
 Record the reasoning either way — `pr-review-sweep:queue` uses it to pick the PRD template,
 and a future reader should be able to see why a borderline call went the way it did.
 
+## Known-pattern check (if the project curates one)
+
+Before finalizing type/reasoning, check whether the thread matches an already-documented
+recurring pattern. Some projects keep a curated, evolving corpus of past review findings
+(commonly `docs/review-*.md`, indexed from `docs/README.md`, fed by a project-local
+`project-status-local` mining step — sigma is the reference example). If such docs exist in
+this repo and the thread matches a named pattern there, say so in the reasoning and cite the
+doc/section — it strengthens the bug-vs-feature call (a documented recurring bug is bug,
+full stop) and carries forward to `:queue`. If no such docs exist, or the thread doesn't
+match anything in them, this is a no-op — don't go hunting for docs a project doesn't have.
+
 ## Output
 
 Per thread: `{disposition, type | null, reasoning}`. Needs-my-decision threads carry the

package/plugins/session-manager-dev/skills/pr-review-sweep/3-queue/SKILL.md

@@ -34,7 +34,14 @@ existing PR's branch), and the standard two independent verification passes befo
 - **`bug` bundle** — additionally require: reproduce each defect described in the bundled
   threads, write a regression test per defect that fails before the fix and passes after,
   then fix. The PRD body should quote the reviewer's exact wording per thread so the
-  executor root-causes the actual reported defect, not a guessed one.
+  executor root-causes the actual reported defect, not a guessed one. If `:classify` flagged
+  a thread as matching a known documented pattern (see its "Known-pattern check"), the PRD
+  must say so explicitly and instruct the executor to **grep the rest of the codebase for
+  the same pattern, not just fix the one flagged instance** — several of sigma's own
+  documented patterns (e.g. an SSR-unsafe `useLayoutEffect`, an un-deduped array into a D1
+  `IN (...)`) turned out to be the exact same bug copy-pasted across 5+ sibling files, each
+  caught as a separate review comment on a separate PR because the first fix never swept the
+  rest. One PRD closing all occurrences beats N PRDs closing them one review cycle at a time.
 - **`feature` bundle** — additionally require: scope the change to exactly what each
   bundled thread asked for (no piggybacked scope creep across threads even though they're
   bundled together), match existing patterns/conventions in the touched files, and add a

package/src/main/__tests__/browserAgentServer.test.cjs

@@ -10,7 +10,9 @@
 const { test } = require('node:test');
 const assert = require('node:assert/strict');
 const http = require('node:http');
-const { createBrowserAgentServer } = require('../browserAgentServer.cjs');
+const fs = require('node:fs');
+const path = require('node:path');
+const { createBrowserAgentServer, TOKEN_PATH, resolveTokenPath } = require('../browserAgentServer.cjs');
 
 function request(port, { method = 'GET', path: reqPath, token, body }) {
   return new Promise((resolve, reject) => {
@@ -184,3 +186,50 @@ test('unknown route is a 404', async () => {
     await server.stop();
   }
 });
+
+test('SM_DEV=1 writes to a dev-suffixed path, never the production browser-agent-api.json', async () => {
+  const devPath = path.join(path.dirname(TOKEN_PATH), 'browser-agent-api.dev.json');
+  const prevMtime = fs.existsSync(TOKEN_PATH) ? fs.statSync(TOKEN_PATH).mtimeMs : null;
+  const prevEnv = process.env.SM_DEV;
+  const remote = makeFakeRemote();
+  let server;
+  try {
+    process.env.SM_DEV = '1';
+    server = createBrowserAgentServer(remote);
+    const { port, token } = await server.start();
+    assert.equal(resolveTokenPath(), devPath);
+    const parsed = JSON.parse(fs.readFileSync(devPath, 'utf8'));
+    assert.equal(parsed.port, port);
+    assert.equal(parsed.token, token);
+    if (prevMtime !== null) {
+      assert.equal(fs.statSync(TOKEN_PATH).mtimeMs, prevMtime);
+    } else {
+      assert.equal(fs.existsSync(TOKEN_PATH), false);
+    }
+  } finally {
+    if (server) await server.stop();
+    if (prevEnv === undefined) delete process.env.SM_DEV; else process.env.SM_DEV = prevEnv;
+    fs.rmSync(devPath, { force: true });
+  }
+});
+
+test('with neither SM_DEV nor SM_E2E set, writes to the original browser-agent-api.json path', async () => {
+  const prevDev = process.env.SM_DEV;
+  const prevE2e = process.env.SM_E2E;
+  const remote = makeFakeRemote();
+  let server;
+  try {
+    delete process.env.SM_DEV;
+    delete process.env.SM_E2E;
+    assert.equal(resolveTokenPath(), TOKEN_PATH);
+    server = createBrowserAgentServer(remote);
+    const { port, token } = await server.start();
+    const parsed = JSON.parse(fs.readFileSync(TOKEN_PATH, 'utf8'));
+    assert.equal(parsed.port, port);
+    assert.equal(parsed.token, token);
+  } finally {
+    if (server) await server.stop();
+    if (prevDev === undefined) delete process.env.SM_DEV; else process.env.SM_DEV = prevDev;
+    if (prevE2e === undefined) delete process.env.SM_E2E; else process.env.SM_E2E = prevE2e;
+  }
+});

package/src/main/__tests__/scheduler-notify-originating-tab.test.cjs

@@ -0,0 +1,99 @@
+/**
+ * scheduler-notify-originating-tab.test.cjs — unit tests for
+ * notifyOriginatingTab (PRD 761): on a job's terminal completed/failed
+ * transition, push a short status prompt into the chat tab that originated
+ * it via enqueueExternalPrompt (PRD 753).
+ *
+ * Run: timeout 300 npx vitest run src/main/__tests__/scheduler-notify-originating-tab.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, vi } from 'vitest';
+const { notifyOriginatingTab, isNotifiableTerminalStatus } = require('../scheduler.cjs');
+
+test('isNotifiableTerminalStatus: completed and failed are notifiable', () => {
+  expect(isNotifiableTerminalStatus('completed')).toBe(true);
+  expect(isNotifiableTerminalStatus('failed')).toBe(true);
+});
+
+test('isNotifiableTerminalStatus: needs_review is not notifiable (may still auto-fix)', () => {
+  expect(isNotifiableTerminalStatus('needs_review')).toBe(false);
+});
+
+test('isNotifiableTerminalStatus: a rateLimited exit never reaches an effectiveStatus (undefined) and is not notifiable', () => {
+  // spawnJob's treatAsPending branch (rateLimited || paused for rate_limit)
+  // resets the job to pending and returns before effectiveStatus is ever
+  // computed — so this hook is only ever evaluated with undefined/pending,
+  // never with a real status, on that path.
+  expect(isNotifiableTerminalStatus(undefined)).toBe(false);
+  expect(isNotifiableTerminalStatus('pending')).toBe(false);
+});
+
+test('resolves via sourceTabId when present on the PRD frontmatter', async () => {
+  const sendPrompt = vi.fn();
+  const parsePrdRaw = vi.fn(async () => ({ sourceTabId: 'tab-from-frontmatter' }));
+  const loadSessions = vi.fn(async () => ({ tabs: [] }));
+
+  await notifyOriginatingTab(
+    { slug: '761-notify', status: 'completed', cwd: '/some/cwd' },
+    { parsePrdRaw, loadSessions, sendPrompt },
+  );
+
+  expect(loadSessions).not.toHaveBeenCalled();
+  expect(sendPrompt).toHaveBeenCalledTimes(1);
+  expect(sendPrompt).toHaveBeenCalledWith(
+    'tab-from-frontmatter',
+    expect.stringContaining('761-notify'),
+  );
+});
+
+test('falls back to the first open tab whose cwd matches the job cwd', async () => {
+  const sendPrompt = vi.fn();
+  const parsePrdRaw = vi.fn(async () => ({ sourceTabId: null }));
+  const loadSessions = vi.fn(async () => ({
+    tabs: [
+      { id: 'tab-other', cwd: '/other/cwd' },
+      { id: 'tab-match', cwd: '/some/cwd' },
+      { id: 'tab-second-match', cwd: '/some/cwd' },
+    ],
+  }));
+
+  await notifyOriginatingTab(
+    { slug: '761-notify', status: 'failed', cwd: '/some/cwd' },
+    { parsePrdRaw, loadSessions, sendPrompt },
+  );
+
+  expect(sendPrompt).toHaveBeenCalledTimes(1);
+  expect(sendPrompt).toHaveBeenCalledWith('tab-match', expect.stringContaining('761-notify'));
+});
+
+test('no-ops without throwing when neither sourceTabId nor a cwd-matching tab resolves', async () => {
+  const sendPrompt = vi.fn();
+  const parsePrdRaw = vi.fn(async () => ({ sourceTabId: null }));
+  const loadSessions = vi.fn(async () => ({ tabs: [{ id: 'tab-other', cwd: '/unrelated' }] }));
+
+  await expect(
+    notifyOriginatingTab(
+      { slug: '761-notify', status: 'completed', cwd: '/some/cwd' },
+      { parsePrdRaw, loadSessions, sendPrompt },
+    ),
+  ).resolves.not.toThrow();
+
+  expect(sendPrompt).not.toHaveBeenCalled();
+});
+
+test('no-ops when parsing the PRD frontmatter throws', async () => {
+  const sendPrompt = vi.fn();
+  const parsePrdRaw = vi.fn(async () => { throw new Error('ENOENT'); });
+  const loadSessions = vi.fn(async () => ({ tabs: [] }));
+
+  await expect(
+    notifyOriginatingTab(
+      { slug: '761-notify', status: 'completed', cwd: '/some/cwd' },
+      { parsePrdRaw, loadSessions, sendPrompt },
+    ),
+  ).resolves.not.toThrow();
+
+  expect(sendPrompt).not.toHaveBeenCalled();
+});

package/src/main/browserAgentServer.cjs

@@ -21,6 +21,11 @@
  *     or derived from the scheduler's token.
  *   - Token compared with crypto.timingSafeEqual to avoid a timing
  *     side-channel on the comparison itself.
+ *   - Mode-scoped token file, same rationale/fix as localAdminHttp.cjs's
+ *     resolveTokenPath() (confirmed-live incident 2026-07-29): a dev/e2e
+ *     launch (SM_DEV=1 / SM_E2E=1) writes to browser-agent-api.dev.json /
+ *     browser-agent-api.e2e.json instead of the production file, so it can
+ *     never silently orphan a concurrently-running production instance.
  *   - Four routes: list tabs (read-only), screenshot, single action
  *     (click/type/key/scroll/navigate), DOM/text snapshot.
  *
@@ -44,6 +49,20 @@ const TOKEN_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'browse
 // still bounded so a malformed/malicious body can't exhaust memory.
 const BODY_MAX_BYTES = 8 * 1024 * 1024;
 
+/**
+ * Mode-aware token file path, resolved fresh on every call — see
+ * localAdminHttp.cjs's resolveTokenPath() for the full rationale.
+ */
+function resolveTokenPath() {
+  if (process.env.SM_DEV === '1') {
+    return path.join(os.homedir(), '.claude', 'session-manager', 'browser-agent-api.dev.json');
+  }
+  if (process.env.SM_E2E === '1') {
+    return path.join(os.homedir(), '.claude', 'session-manager', 'browser-agent-api.e2e.json');
+  }
+  return TOKEN_PATH;
+}
+
 function timingSafeEqualStrings(a, b) {
   const bufA = Buffer.from(String(a ?? ''));
   const bufB = Buffer.from(String(b ?? ''));
@@ -103,14 +122,16 @@ function createBrowserAgentServer(remote) {
 
   async function ensureToken() {
     token = crypto.randomBytes(32).toString('hex');
-    await config.writeJson(TOKEN_PATH, { port: null, token });
-    try { await fsp.chmod(TOKEN_PATH, 0o600); } catch { /* best-effort on platforms without POSIX perms */ }
+    const tokenPath = resolveTokenPath();
+    await config.writeJson(tokenPath, { port: null, token });
+    try { await fsp.chmod(tokenPath, 0o600); } catch { /* best-effort on platforms without POSIX perms */ }
     return token;
   }
 
   async function persistPort(port) {
-    await config.writeJson(TOKEN_PATH, { port, token });
-    try { await fsp.chmod(TOKEN_PATH, 0o600); } catch { /* */ }
+    const tokenPath = resolveTokenPath();
+    await config.writeJson(tokenPath, { port, token });
+    try { await fsp.chmod(tokenPath, 0o600); } catch { /* */ }
   }
 
   function authorized(req) {
@@ -200,4 +221,4 @@ function createBrowserAgentServer(remote) {
   return { start, stop, get token() { return token; }, get server() { return server; } };
 }
 
-module.exports = { createBrowserAgentServer, TOKEN_PATH };
+module.exports = { createBrowserAgentServer, TOKEN_PATH, resolveTokenPath };

package/src/main/chatRunner.cjs

@@ -677,6 +677,48 @@ function cancel(tabId) {
   return Promise.resolve();
 }
 
+// ─── External-caller entry point (PRD 753) ─────────────────────────────────
+// Pushes a prompt into an already-open tab's chat queue from outside the
+// renderer — Web Remote, the admin HTTP route, or the scheduler MCP tool.
+// Fire-and-forget over IPC: the renderer-side listener (chat.ts) resolves
+// the tab's live sessionId/cwd from useSessions and calls useChat.send()
+// directly, reusing send()'s existing queued-vs-immediate branching rather
+// than duplicating it here.
+
+function enqueueExternalPrompt(tabId, prompt) {
+  broadcast('chat:external-send', { tabId, prompt });
+}
+
+/**
+ * Registers the admin-HTTP entry point for enqueueExternalPrompt, mirroring
+ * prdCreate.cjs's registerAdminRoute pattern (auth is the injected transport's
+ * job; this only owns route logic + body parsing).
+ */
+function registerAdminRoute(adminHttp) {
+  const { readBody, sendJson } = require('./lib/localAdminHttp.cjs');
+  const { schemas } = require('./ipcSchemas.cjs');
+
+  adminHttp.registerRoute('POST', '/admin/chat/send-prompt', async (req, res) => {
+    const raw = await readBody(req);
+    let parsed;
+    try {
+      parsed = raw ? JSON.parse(raw) : {};
+    } catch {
+      sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+      return;
+    }
+    let body;
+    try {
+      body = schemas.chatExternalSend.parse(parsed);
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: e?.message ?? 'invalid body' });
+      return;
+    }
+    enqueueExternalPrompt(body.tabId, body.prompt);
+    sendJson(res, 200, { ok: true });
+  });
+}
+
 // ─── IPC handler registration ─────────────────────────────────────────────
 
 function registerChatHandlers() {
@@ -718,4 +760,6 @@ module.exports = {
   STOP_SENTINEL,
   CHAT_MODE_TRUTH_INSTRUCTION,
   __setExecutor,
+  enqueueExternalPrompt,
+  registerAdminRoute,
 };

package/src/main/index.cjs

@@ -27,9 +27,11 @@ const voiceWizard = require('./voiceWizard.cjs');
 const scheduler = require('./scheduler.cjs');
 const { createAdminHttp } = require('./lib/localAdminHttp.cjs');
 const prdCreate = require('./lib/prdCreate.cjs');
+const chatRunner = require('./chatRunner.cjs');
 const adminHttp = createAdminHttp();
 scheduler.registerAdminRoutes(adminHttp);
 prdCreate.registerAdminRoute(adminHttp, scheduler.remote);
+chatRunner.registerAdminRoute(adminHttp);
 const { createBrowserAgentServer } = require('./browserAgentServer.cjs');
 const browserAgentServer = createBrowserAgentServer({
   listTabs: () => browserView.listViews(),
@@ -60,7 +62,6 @@ const searchIpc = require('./search.cjs');
 const repoAnalyzer = require('./repoAnalyzer.cjs');
 const hivesIpc = require('./hives.cjs');
 const webRemote = require('./webRemote.cjs');
-const chatRunner = require('./chatRunner.cjs');
 const { listExchanges } = require('./exchanges.cjs');
 const { resolveClaudeBin } = require('./lib/claudeBin.cjs');
 const { checkInsideHome, assertInsideHome } = require('./lib/insideHome.cjs');

package/src/main/ipcSchemas.cjs

@@ -257,6 +257,10 @@ const schedulerCreatePrd = z.object({
   // prompt that spawned it. Same newline-injection guard as title/cwd since
   // it also becomes a frontmatter value.
   sourcePromptId: z.string().min(1).max(128).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
+  // Originating tab id (PRD 761) — used at job completion to route a status
+  // prompt back into the chat tab that queued this PRD, via
+  // enqueueExternalPrompt (PRD 753). Same newline-injection guard.
+  sourceTabId: z.string().min(1).max(128).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
 });
 
 // Bulk archive: slug list, capped to limit unbounded retag/archive payloads.
@@ -476,6 +480,18 @@ const chatClassifyTicket = z.object({
   ),
 });
 
+// External-caller entry point (admin HTTP route + MCP tool + web-remote
+// command, PRD 753) — pushes a prompt into an already-open tab's chat queue
+// from outside the renderer. tabId only (no sessionId/cwd): those are
+// resolved renderer-side from useSessions, same as the AC requires.
+const chatExternalSend = z.object({
+  tabId: z.string().min(1).max(128),
+  prompt: z.string().min(1).refine(
+    (s) => Buffer.byteLength(s, 'utf8') <= CHAT_PROMPT_MAX_BYTES,
+    `prompt must be ≤ ${CHAT_PROMPT_MAX_BYTES} bytes`,
+  ),
+});
+
 // ──────────────────────────────────────────── Web Remote
 // OTP is 8 uppercase alphanumeric chars (case-insensitive entry, normalised to upper in handler).
 const WEB_REMOTE_OTP_RE = /^[A-Z0-9]{8}$/i;
@@ -683,6 +699,9 @@ const MUTATE_COMMANDS = new Set([
   'cmd:schedule:reset-job',
   'cmd:schedule:run-now',
   'cmd:schedule:set-config',
+  // Pushes a prompt into an open tab's chat queue — a real mutation of that
+  // tab's session, same tier as pty:write.
+  'cmd:chat:send',
 ]);
 
 const ALLOWED_COMMANDS = new Set([...READ_COMMANDS, ...SAS_GATED_READS, ...MUTATE_COMMANDS]);
@@ -774,6 +793,7 @@ module.exports = {
     chatCancel,
     chatProbeContext,
     chatClassifyTicket,
+    chatExternalSend,
     exchangesList,
   },
   validated,

package/src/main/lib/__tests__/localAdminHttp.test.cjs

@@ -14,7 +14,8 @@
 import { test, expect } from 'vitest';
 const http = require('node:http');
 const fs = require('node:fs');
-const { createAdminHttp, TOKEN_PATH } = require('../localAdminHttp.cjs');
+const path = require('node:path');
+const { createAdminHttp, TOKEN_PATH, resolveTokenPath } = require('../localAdminHttp.cjs');
 
 function request(port, { method = 'GET', path: reqPath, token, body }) {
   return new Promise((resolve, reject) => {
@@ -118,3 +119,73 @@ test('start() persists token file with port + token, mode 0600', async () => {
     await admin.stop();
   }
 });
+
+test('SM_DEV=1 writes to a dev-suffixed path, never the production admin-api.json', async () => {
+  const devPath = path.join(path.dirname(TOKEN_PATH), 'admin-api.dev.json');
+  const prevMtime = fs.existsSync(TOKEN_PATH) ? fs.statSync(TOKEN_PATH).mtimeMs : null;
+  const prevEnv = process.env.SM_DEV;
+  process.env.SM_DEV = '1';
+  const admin = createAdminHttp();
+  try {
+    const { port, token } = await admin.start();
+    expect(resolveTokenPath()).toBe(devPath);
+    const parsed = JSON.parse(fs.readFileSync(devPath, 'utf8'));
+    expect(parsed.port).toBe(port);
+    expect(parsed.token).toBe(token);
+    // Production file must be untouched by the dev-mode instance.
+    if (prevMtime !== null) {
+      expect(fs.statSync(TOKEN_PATH).mtimeMs).toBe(prevMtime);
+    } else {
+      expect(fs.existsSync(TOKEN_PATH)).toBe(false);
+    }
+  } finally {
+    await admin.stop();
+    if (prevEnv === undefined) delete process.env.SM_DEV; else process.env.SM_DEV = prevEnv;
+    fs.rmSync(devPath, { force: true });
+  }
+});
+
+test('with neither SM_DEV nor SM_E2E set, writes to the original admin-api.json path', async () => {
+  const prevDev = process.env.SM_DEV;
+  const prevE2e = process.env.SM_E2E;
+  delete process.env.SM_DEV;
+  delete process.env.SM_E2E;
+  let admin;
+  try {
+    expect(resolveTokenPath()).toBe(TOKEN_PATH);
+    admin = createAdminHttp();
+    const { port, token } = await admin.start();
+    const parsed = JSON.parse(fs.readFileSync(TOKEN_PATH, 'utf8'));
+    expect(parsed.port).toBe(port);
+    expect(parsed.token).toBe(token);
+  } finally {
+    if (admin) await admin.stop();
+    if (prevDev === undefined) delete process.env.SM_DEV; else process.env.SM_DEV = prevDev;
+    if (prevE2e === undefined) delete process.env.SM_E2E; else process.env.SM_E2E = prevE2e;
+  }
+});
+
+test('dev and production token paths never collide', () => {
+  const prevEnv = process.env.SM_DEV;
+  try {
+    process.env.SM_DEV = '1';
+    const devPath = resolveTokenPath();
+    delete process.env.SM_DEV;
+    const prodPath = resolveTokenPath();
+    expect(devPath).not.toBe(prodPath);
+  } finally {
+    if (prevEnv === undefined) delete process.env.SM_DEV; else process.env.SM_DEV = prevEnv;
+  }
+});
+
+test('start()s self-check answers on the health path with the fresh bearer token', async () => {
+  const admin = createAdminHttp();
+  const { port, token } = await admin.start();
+  try {
+    const res = await request(port, { path: '/__admin/health', token });
+    expect(res.status).toBe(200);
+    expect(res.json).toEqual({ ok: true });
+  } finally {
+    await admin.stop();
+  }
+});

package/src/main/lib/localAdminHttp.cjs

@@ -15,6 +15,18 @@
  *     ~/.claude/session-manager/admin-api.json with 0600 perms.
  *   - Token compared with crypto.timingSafeEqual to avoid a timing
  *     side-channel on the comparison itself.
+ *
+ * Mode-scoped token file (confirmed-live incident 2026-07-29): a dev-mode or
+ * e2e Electron launch (SM_DEV=1 / SM_E2E=1) intentionally skips the
+ * single-instance lock (index.cjs), so it can run concurrently with a
+ * production instance. Without a mode-specific path, that dev/e2e instance's
+ * boot silently overwrote the production instance's admin-api.json with its
+ * own (soon-to-be-dead) port+token, orphaning scheduler-mcp-server.cjs's
+ * access to the still-running production app with no error anywhere. Dev/e2e
+ * instances now write to admin-api.dev.json / admin-api.e2e.json instead —
+ * see resolveTokenPath(). Production (neither env var set) is unaffected:
+ * it still writes/reads admin-api.json, matching scheduler-mcp-server.cjs's
+ * hardcoded read path.
  */
 
 'use strict';
@@ -28,6 +40,29 @@ const config = require('../config.cjs');
 
 const TOKEN_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'admin-api.json');
 
+/**
+ * Mode-aware token file path, resolved fresh on every call (not cached at
+ * module load) so a dev/e2e launch never collides with a production
+ * instance's admin-api.json. index.cjs treats SM_DEV and SM_E2E as one OR'd
+ * `isDev` boolean with no ordering between them; if both happen to be set,
+ * this resolves to the SM_DEV path (checked first below) — an arbitrary but
+ * harmless tie-break, since real launches only ever set one or the other.
+ */
+function resolveTokenPath() {
+  if (process.env.SM_DEV === '1') {
+    return path.join(os.homedir(), '.claude', 'session-manager', 'admin-api.dev.json');
+  }
+  if (process.env.SM_E2E === '1') {
+    return path.join(os.homedir(), '.claude', 'session-manager', 'admin-api.e2e.json');
+  }
+  return TOKEN_PATH;
+}
+
+// Reserved health-check path, handled directly (not via registerRoute) so
+// start()'s post-boot self-check never depends on route-registration order
+// relative to start() across callers (chatRunner/scheduler/prdCreate).
+const HEALTH_PATH = '/__admin/health';
+
 function timingSafeEqualStrings(a, b) {
   const bufA = Buffer.from(String(a ?? ''));
   const bufB = Buffer.from(String(b ?? ''));
@@ -79,14 +114,16 @@ function createAdminHttp() {
 
   async function ensureToken() {
     token = crypto.randomBytes(32).toString('hex');
-    await config.writeJson(TOKEN_PATH, { port: null, token });
-    try { await fsp.chmod(TOKEN_PATH, 0o600); } catch { /* best-effort on platforms without POSIX perms */ }
+    const tokenPath = resolveTokenPath();
+    await config.writeJson(tokenPath, { port: null, token });
+    try { await fsp.chmod(tokenPath, 0o600); } catch { /* best-effort on platforms without POSIX perms */ }
     return token;
   }
 
   async function persistPort(port) {
-    await config.writeJson(TOKEN_PATH, { port, token });
-    try { await fsp.chmod(TOKEN_PATH, 0o600); } catch { /* */ }
+    const tokenPath = resolveTokenPath();
+    await config.writeJson(tokenPath, { port, token });
+    try { await fsp.chmod(tokenPath, 0o600); } catch { /* */ }
   }
 
   function authorized(req) {
@@ -105,6 +142,10 @@ function createAdminHttp() {
       sendJson(res, 401, { ok: false, error: 'unauthorized' });
       return;
     }
+    if (req.method === 'GET' && req.url === HEALTH_PATH) {
+      sendJson(res, 200, { ok: true });
+      return;
+    }
     try {
       const handler = routes.get(`${req.method} ${req.url}`);
       if (!handler) {
@@ -117,6 +158,31 @@ function createAdminHttp() {
     }
   }
 
+  /**
+   * Post-boot self-check: confirm the server actually answers on the port
+   * it just wrote to the token file, before start() reports success. Catches
+   * the class of bug where the written port/token is stale or the listener
+   * never came up right — otherwise the only symptom is a caller getting
+   * "unauthorized"/connection-refused with zero context in the logs.
+   */
+  function selfCheck(port) {
+    return new Promise((resolve, reject) => {
+      const req = http.request(
+        { hostname: '127.0.0.1', port, method: 'GET', path: HEALTH_PATH, headers: { Authorization: `Bearer ${token}` }, timeout: 2000 },
+        (res) => {
+          res.resume();
+          res.on('end', () => {
+            if (res.statusCode === 200) resolve();
+            else reject(new Error(`admin HTTP self-check got status ${res.statusCode} from port ${port}`));
+          });
+        },
+      );
+      req.on('timeout', () => { req.destroy(new Error(`admin HTTP self-check timed out on port ${port}`)); });
+      req.on('error', (e) => reject(new Error(`admin HTTP self-check failed to reach port ${port}: ${e.message}`)));
+      req.end();
+    });
+  }
+
   async function start() {
     await ensureToken();
     server = http.createServer((req, res) => {
@@ -129,7 +195,13 @@ function createAdminHttp() {
       server.listen(0, '127.0.0.1', resolve);
     });
     const { port } = server.address();
-    await persistPort(port);
+    try {
+      await persistPort(port);
+      await selfCheck(port);
+    } catch (e) {
+      await stop();
+      throw e;
+    }
     return { port, token };
   }
 
@@ -151,6 +223,7 @@ function createAdminHttp() {
 module.exports = {
   createAdminHttp,
   TOKEN_PATH,
+  resolveTokenPath,
   timingSafeEqualStrings,
   readBody,
   sendJson,

package/src/main/lib/prdCreate.cjs

@@ -48,7 +48,7 @@ function deriveSlugFromTitle(title) {
 function buildPrdBody(input) {
   const {
     title, cwd, estimateMinutes, goal, acceptanceCriteria,
-    implementationNotes, outOfScope, sourcePromptId,
+    implementationNotes, outOfScope, sourcePromptId, sourceTabId,
   } = input;
 
   // No `parallelGroup` frontmatter key by convention (SKILL.md) — the NN-
@@ -58,6 +58,9 @@ function buildPrdBody(input) {
   // Optional, additive: traces this PRD back to the PromptTicket (PRD 748)
   // that was classified 'develop' and spawned it (PRD 749).
   if (sourcePromptId) fmLines.push(`sourcePromptId: ${sourcePromptId}`);
+  // Optional, additive: the tab that queued this PRD, read back by
+  // scheduler.cjs at job completion (PRD 761) to route a status prompt.
+  if (sourceTabId) fmLines.push(`sourceTabId: ${sourceTabId}`);
   fmLines.push('---', '');
 
   const acLines = acceptanceCriteria.map((line) => `- [ ] ${line}`).join('\n');

package/src/main/scheduler/prdParser.cjs

@@ -68,6 +68,11 @@ async function parsePrdRaw(filePath) {
     // classified 'develop' and spawned this PRD (PRD 749). Additive — absent
     // on every PRD authored before this field existed.
     sourcePromptId: fm.sourcePromptId || null,
+    // Optional traceability back to the chat tab that queued this PRD (PRD
+    // 761) — read back at job completion to route a status prompt via
+    // enqueueExternalPrompt (PRD 753). Additive — absent on every PRD
+    // authored before this field existed.
+    sourceTabId: fm.sourceTabId || null,
     body: body.trim(),
   };
 }