claude-code-session-manager 0.41.0 → 0.42.0

package/dist/index.html

@@ -7,10 +7,10 @@
     <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-H7rwsoKV.js"></script>
+    <script type="module" crossorigin src="./assets/index-D4ga1iZ5.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-CKY3mHgV.css">
+    <link rel="stylesheet" crossorigin href="./assets/index-CxGY-V5G.css">
   </head>
   <body class="bg-bg text-fg font-sans antialiased">
     <div id="root"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-session-manager",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "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/scripts/lib/watchdogHelpers.cjs

@@ -313,9 +313,16 @@ async function emitFeedbackPRD(cwd, {
     // Every PRD belongs to an Epic (CLAUDE.md domain model). The sweep joins
     // one standing "Inbound feedback" Epic per project (reuseByGoal) so
     // recurring ticks chain into a single Epic rather than minting one each.
+    // This is an unattended automated sweep, not a human action — status
+    // MUST be 'proposed' (same as lib/rcaFeedbackHook.cjs) so the Epic lands
+    // behind the Approve & start human gate instead of running immediately;
+    // an 'active' default here would let an unattended process mint and
+    // execute PRDs with zero human approval, exactly the hole the 'proposed'
+    // gate exists to close.
     const epic = await ensureEpic(cwd, {
       goalText: 'Inbound feedback processing',
       tag: 'discussion',
+      status: 'proposed',
       reuseByGoal: true,
     });
     epicId = epic.epicId;

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

@@ -0,0 +1,87 @@
+/**
+ * opsErrorLog.test.cjs — appendError() is the sole writer of the `logs` ops
+ * namespace (single-writer law, opsOwnership.cjs). Verifies: writes a tagged
+ * JSONL line to <cwd>/session-manager-operations/logs/errors-<date>.jsonl,
+ * redacts sensitive meta keys, and no-ops (never throws) with no cwd.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/opsErrorLog.test.cjs
+ */
+
+'use strict';
+
+import { test } from 'vitest';
+import assert from 'node:assert/strict';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const opsErrorLog = require('../lib/opsErrorLog.cjs');
+
+function mkTmpProject() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'sm-opslog-test-'));
+}
+
+function readLines(cwd) {
+  const dir = opsErrorLog.logsDir(cwd);
+  const file = opsErrorLog.todayFile(cwd);
+  if (!fs.existsSync(file)) return [];
+  return fs.readFileSync(file, 'utf8').trim().split('\n').filter(Boolean).map((l) => JSON.parse(l));
+}
+
+test('appendError writes a tagged JSONL line', () => {
+  const cwd = mkTmpProject();
+  opsErrorLog.appendError({
+    cwd,
+    scope: 'pty',
+    tabId: 'tab-123',
+    tags: ['spawn-failed'],
+    message: 'pty.spawn threw: boom',
+  });
+  const lines = readLines(cwd);
+  assert.equal(lines.length, 1);
+  const [line] = lines;
+  assert.equal(line.level, 'error');
+  assert.equal(line.scope, 'pty');
+  assert.equal(line.tabId, 'tab-123');
+  assert.equal(line.message, 'pty.spawn threw: boom');
+  assert.ok(line.tags.includes('level:error'));
+  assert.ok(line.tags.includes('scope:pty'));
+  assert.ok(line.tags.includes('tab:tab-123'));
+  assert.ok(line.tags.includes('spawn-failed'));
+  assert.ok(typeof line.ts === 'string' && !Number.isNaN(Date.parse(line.ts)));
+});
+
+test('appendError redacts sensitive meta keys', () => {
+  const cwd = mkTmpProject();
+  opsErrorLog.appendError({
+    cwd,
+    scope: 'chatRunner',
+    message: 'run failed',
+    meta: { token: 'sk-secret', sessionId: 'abc', password: 'hunter2' },
+  });
+  const [line] = readLines(cwd);
+  assert.equal(line.meta.token, '[redacted]');
+  assert.equal(line.meta.password, '[redacted]');
+  assert.equal(line.meta.sessionId, 'abc');
+});
+
+test('appendError is a no-op with no cwd', () => {
+  // Must not throw, and there is nowhere to assert a file was NOT written
+  // since no cwd means no path — this just proves it never throws.
+  assert.doesNotThrow(() => opsErrorLog.appendError({ scope: 'x', message: 'y' }));
+});
+
+test('appendError merges caller tags without duplicating auto-derived ones', () => {
+  const cwd = mkTmpProject();
+  opsErrorLog.appendError({
+    cwd,
+    scope: 'chatRunner',
+    tabId: 'tab-9',
+    tags: ['level:error', 'silent-probe'], // deliberately duplicates an auto tag
+    message: 'probe failed',
+  });
+  const [line] = readLines(cwd);
+  const count = line.tags.filter((t) => t === 'level:error').length;
+  assert.equal(count, 1);
+  assert.ok(line.tags.includes('silent-probe'));
+});

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

@@ -23,6 +23,7 @@ const {
   PRD_CREATE_SLUG_RE,
   registerAdminRoute,
   createPrd,
+  resolveSourcePromptIdFromClaudeSession,
 } = require('../lib/prdCreate.cjs');
 const { createAdminHttp } = require('../lib/localAdminHttp.cjs');
 const config = require('../config.cjs');
@@ -505,3 +506,72 @@ test('POST /admin/scheduler/create-prd with sourcePromptId writes it into the cr
     await admin.stop();
   }
 });
+
+// ──────────────────────────────────────────── originClaudeSessionId fallback
+// (2026-08-01 fix: a PRD queued via the scheduler_create_prd MCP tool from
+// inside an Epic's own chat session, without an explicit sourcePromptId,
+// must still join that Epic rather than mint an unrelated sibling one.)
+
+async function writeActiveIndexFixture(cwd, sessions) {
+  const dir = path.join(cwd, 'session-manager-operations', 'prompt-sessions');
+  await fsp.mkdir(dir, { recursive: true });
+  await fsp.writeFile(path.join(dir, 'active-index.json'), JSON.stringify({ sessions, events: {} }, null, 2));
+}
+
+test('resolveSourcePromptIdFromClaudeSession finds the Epic whose claudeSessionId matches', async () => {
+  const root = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-resolve-epic-'));
+  try {
+    await writeActiveIndexFixture(root, {
+      'psess-abc123': { id: 'psess-abc123', claudeSessionId: 'claude-sess-1', status: 'active' },
+    });
+    expect(resolveSourcePromptIdFromClaudeSession(root, 'claude-sess-1')).toBe('psess-abc123');
+    expect(resolveSourcePromptIdFromClaudeSession(root, 'claude-sess-unknown')).toBeNull();
+    expect(resolveSourcePromptIdFromClaudeSession(root, null)).toBeNull();
+  } finally {
+    await fsp.rm(root, { recursive: true, force: true });
+  }
+});
+
+test('createPrd resolves sourcePromptId from originClaudeSessionId when the caller omitted sourcePromptId', async () => {
+  const root = await fsp.mkdtemp(path.join(os.homedir(), '.sm-origin-session-epic-'));
+  config.addAllowedRoot(root);
+  try {
+    await writeActiveIndexFixture(root, {
+      'psess-always-select-tab': { id: 'psess-always-select-tab', claudeSessionId: 'claude-sess-epic-1', status: 'active' },
+    });
+    const prdsDir = path.join(root, 'session-manager-operations', 'scheduler', 'epics', 'psess-always-select-tab', 'prds');
+    const remote = makeFakeRemoteWithPrdsDir(prdsDir);
+
+    const result = await createPrd(
+      validCreateBody({ cwd: root, slug: 'joins-the-epic', originClaudeSessionId: 'claude-sess-epic-1' }),
+      remote,
+    );
+
+    expect(result.ok).toBe(true);
+    const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+    expect(written).toMatch(/sourcePromptId: psess-always-select-tab/);
+  } finally {
+    await fsp.rm(root, { recursive: true, force: true });
+  }
+});
+
+test('createPrd leaves sourcePromptId unset when originClaudeSessionId matches no known Epic (plain SessionTab chat)', async () => {
+  const root = await fsp.mkdtemp(path.join(os.homedir(), '.sm-origin-session-no-match-'));
+  config.addAllowedRoot(root);
+  try {
+    await writeActiveIndexFixture(root, {});
+    const prdsDir = path.join(root, 'session-manager-operations', 'scheduler', 'prds');
+    const remote = makeFakeRemoteWithPrdsDir(prdsDir);
+
+    const result = await createPrd(
+      validCreateBody({ cwd: root, slug: 'no-epic-match', originClaudeSessionId: 'claude-sess-not-an-epic' }),
+      remote,
+    );
+
+    expect(result.ok).toBe(true);
+    const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+    expect(!/sourcePromptId:/.test(written)).toBeTruthy();
+  } finally {
+    await fsp.rm(root, { recursive: true, force: true });
+  }
+});

package/src/main/chatRunner.cjs

@@ -51,6 +51,7 @@ const { classifyToolUse } = require('./lib/toolUseClassify.cjs');
 const { extractJson } = require('./lib/extractJson.cjs');
 const { classifyPromptTicket } = require('./lib/classifyPromptTicket.cjs');
 const sessionSlots = require('./lib/sessionSlots.cjs');
+const opsErrorLog = require('./lib/opsErrorLog.cjs');
 
 // ─── Stop-signal protocol ──────────────────────────────────────────────────
 // Single source of truth for the sentinel and parser. The renderer (PRD 320)
@@ -470,6 +471,19 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume, silent, onSilentRes
     const emitTerminal = (channel, payload) => {
       if (terminalSent) return;
       terminalSent = true;
+      // Every terminal error for this tab, logged once, regardless of the
+      // `silent` gate below — a probe run's failure is still real signal for
+      // tracing even though it never reaches the visible chat UI.
+      if (channel === 'chat:run:error') {
+        opsErrorLog.appendError({
+          cwd,
+          scope: 'chatRunner',
+          tabId,
+          tags: silent ? ['silent-probe'] : [],
+          message: payload?.message ?? 'chat run failed',
+          meta: { sessionId, silent },
+        });
+      }
       // Silent (probe) runs still need this bookkeeping so the lane frees
       // correctly, but must never surface on the six turn-affecting channels.
       if (silent) return;
@@ -495,7 +509,14 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume, silent, onSilentRes
     };
 
     const claudeBin = resolveClaudeBin();
-    const childEnv = cleanChildEnv({ PATH: pathWithUserBins() });
+    // Carried down to any MCP server this run spawns (e.g.
+    // scripts/scheduler-mcp-server.cjs, inherited via the claude CLI's own
+    // child env) so scheduler_create_prd can auto-resolve sourcePromptId
+    // when the model forgets to pass it — see prdCreate.cjs's
+    // resolveSourcePromptIdFromClaudeSession. sessionId IS the Epic's
+    // claudeSessionId for an Epic-backed tab (domain model: Epic:claude-session
+    // 1:1); for a non-Epic tab, resolution below simply finds no match.
+    const childEnv = cleanChildEnv({ PATH: pathWithUserBins(), SM_CHAT_SESSION_ID: sessionId });
 
     // Prepend the stop-signal protocol instruction and the chat-mode truth
     // instruction to every prompt

package/src/main/ipcSchemas.cjs

@@ -303,6 +303,14 @@ const schedulerCreatePrd = z.object({
   // 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(),
+  // The calling MCP process's own claude session id (scheduler-mcp-server.cjs
+  // forwards its inherited SM_CHAT_SESSION_ID env var here when the model
+  // omitted sourcePromptId) — never written to frontmatter itself; prdCreate.cjs's
+  // createPrd() resolves it against active-index.json to fill sourcePromptId
+  // when it matches an existing Epic's claudeSessionId, so a PRD queued from
+  // within an Epic's own chat session joins that Epic even if the tool call
+  // forgot to pass sourcePromptId explicitly.
+  originClaudeSessionId: z.string().min(1).max(128).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
   // User-selected Feature/Bug tag (PRD 774) carried from the originating
   // PromptTicket — deterministic, never LLM-classified.
   tag: z.enum(['feature', 'bug', 'discussion']).optional(),

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

@@ -11,12 +11,24 @@
 
 'use strict';
 
-import { test, expect } from 'vitest';
+import { test, expect, afterAll } from 'vitest';
 const http = require('node:http');
 const fs = require('node:fs');
 const path = require('node:path');
+const os = require('node:os');
 const { createAdminHttp, TOKEN_PATH, resolveTokenPath } = require('../localAdminHttp.cjs');
 
+// Redirect every start() in this file away from the PRODUCTION admin-api.json.
+// Without this, these tests overwrote the running app's port+token with a
+// throwaway server's, orphaning scheduler-mcp-server.cjs until an app restart
+// (confirmed live 2026-08-01). Tests that specifically exercise path
+// resolution unset this override themselves.
+// Must live under the home dir: config.writeJson enforces allowedRoots.
+const TEST_TOKEN_PATH = path.join(path.dirname(TOKEN_PATH), `admin-api.test-${process.pid}.json`);
+process.env.SM_ADMIN_TOKEN_PATH = TEST_TOKEN_PATH;
+
+afterAll(() => { fs.rmSync(TEST_TOKEN_PATH, { force: true }); });
+
 function request(port, { method = 'GET', path: reqPath, token, body }) {
   return new Promise((resolve, reject) => {
     const headers = {};
@@ -109,11 +121,11 @@ test('start() persists token file with port + token, mode 0600', async () => {
   const admin = createAdminHttp();
   const { port, token } = await admin.start();
   try {
-    const raw = fs.readFileSync(TOKEN_PATH, 'utf8');
+    const raw = fs.readFileSync(TEST_TOKEN_PATH, 'utf8');
     const parsed = JSON.parse(raw);
     expect(parsed.port).toBe(port);
     expect(parsed.token).toBe(token);
-    const mode = fs.statSync(TOKEN_PATH).mode & 0o777;
+    const mode = fs.statSync(TEST_TOKEN_PATH).mode & 0o777;
     expect(mode).toBe(0o600);
   } finally {
     await admin.stop();
@@ -124,6 +136,8 @@ test('SM_DEV=1 writes to a dev-suffixed path, never the production admin-api.jso
   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;
+  const prevOverride = process.env.SM_ADMIN_TOKEN_PATH;
+  delete process.env.SM_ADMIN_TOKEN_PATH;
   process.env.SM_DEV = '1';
   const admin = createAdminHttp();
   try {
@@ -141,32 +155,36 @@ test('SM_DEV=1 writes to a dev-suffixed path, never the production admin-api.jso
   } finally {
     await admin.stop();
     if (prevEnv === undefined) delete process.env.SM_DEV; else process.env.SM_DEV = prevEnv;
+    if (prevOverride !== undefined) process.env.SM_ADMIN_TOKEN_PATH = prevOverride;
     fs.rmSync(devPath, { force: true });
   }
 });
 
-test('with neither SM_DEV nor SM_E2E set, writes to the original admin-api.json path', async () => {
+test('with neither SM_DEV nor SM_E2E set, resolves to the original admin-api.json path', () => {
+  // Path RESOLUTION only — deliberately does not start() a server here. This
+  // test used to boot one with no override set, which wrote a throwaway
+  // port+token straight into the live app's admin-api.json and cut
+  // scheduler-mcp-server.cjs off from the running app. Persistence itself is
+  // covered by the 0600 test above, against the redirected test path.
   const prevDev = process.env.SM_DEV;
   const prevE2e = process.env.SM_E2E;
+  const prevOverride = process.env.SM_ADMIN_TOKEN_PATH;
   delete process.env.SM_DEV;
   delete process.env.SM_E2E;
-  let admin;
+  delete process.env.SM_ADMIN_TOKEN_PATH;
   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;
+    if (prevOverride !== undefined) process.env.SM_ADMIN_TOKEN_PATH = prevOverride;
   }
 });
 
 test('dev and production token paths never collide', () => {
   const prevEnv = process.env.SM_DEV;
+  const prevOverride = process.env.SM_ADMIN_TOKEN_PATH;
+  delete process.env.SM_ADMIN_TOKEN_PATH;
   try {
     process.env.SM_DEV = '1';
     const devPath = resolveTokenPath();
@@ -175,6 +193,7 @@ test('dev and production token paths never collide', () => {
     expect(devPath).not.toBe(prodPath);
   } finally {
     if (prevEnv === undefined) delete process.env.SM_DEV; else process.env.SM_DEV = prevEnv;
+    if (prevOverride !== undefined) process.env.SM_ADMIN_TOKEN_PATH = prevOverride;
   }
 });
 

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

@@ -0,0 +1,94 @@
+'use strict';
+
+// Run: timeout 120 npx vitest run src/main/lib/__tests__/schedulerBatchDepends.test.cjs
+//
+// Regression coverage for dependsOn eligibility in pickForProject. The
+// bare-slug cases below are the ones that shipped broken: a PRD's filename
+// carries the auto-allocated `NN-` prefix, but `dependsOn:` is authored with
+// the bare name (the author can't know the number the allocator will issue),
+// so every such dep silently resolved to "no row -> already done" and the
+// gate never held anything.
+
+// vitest globals (test) — same convention as the other .cjs tests.
+const assert = require('node:assert/strict');
+const { pickForProject, DEFAULT_PROJECT_CWD } = require('../schedulerBatch.cjs');
+
+const CWD = DEFAULT_PROJECT_CWD;
+
+function job(slug, status, extra = {}) {
+return {
+  slug,
+  status,
+  cwd: CWD,
+  parallelGroup: Number(String(slug).match(/^(\d+)-/)?.[1] ?? 99),
+  dependsOn: [],
+  ...extra,
+};
+}
+
+function pick(jobs, running = new Set(), slots = 3) {
+return pickForProject(jobs, running, slots);
+}
+
+test('holds a dependent whose bare-named dep is still running (NN- prefix stripped)', () => {
+  const jobs = [
+    job('873-leftnav-two-face-framework', 'running'),
+    job('874-nav-face-project-home', 'pending', { dependsOn: ['leftnav-two-face-framework'] }),
+  ];
+  const { batch } = pick(jobs, new Set(['873-leftnav-two-face-framework']));
+  assert.deepEqual(batch.map((j) => j.slug), []);
+});
+
+test('holds a dependent whose bare-named dep is still pending', () => {
+  const jobs = [
+    job('873-leftnav-two-face-framework', 'pending'),
+    job('895-home-global-behavior-settings', 'pending', {
+      dependsOn: ['leftnav-two-face-framework', 'nav-face-session-manager-config'],
+    }),
+    job('890-nav-face-session-manager-config', 'pending', {
+      dependsOn: ['leftnav-two-face-framework'],
+    }),
+  ];
+  const { batch } = pick(jobs);
+  // Only the framework PRD (no deps) is eligible; both dependents are held.
+  assert.deepEqual(batch.map((j) => j.slug), ['873-leftnav-two-face-framework']);
+});
+
+test('releases a dependent once its bare-named dep is completed', () => {
+  const jobs = [
+    job('873-leftnav-two-face-framework', 'completed'),
+    job('874-nav-face-project-home', 'pending', { dependsOn: ['leftnav-two-face-framework'] }),
+  ];
+  const { batch } = pick(jobs);
+  assert.deepEqual(batch.map((j) => j.slug), ['874-nav-face-project-home']);
+});
+
+test('still resolves an exact-slug dep (dep written WITH the NN- prefix)', () => {
+  const jobs = [
+    job('873-leftnav-two-face-framework', 'pending'),
+    job('874-nav-face-project-home', 'pending', {
+      dependsOn: ['873-leftnav-two-face-framework'],
+    }),
+  ];
+  const { batch } = pick(jobs);
+  assert.deepEqual(batch.map((j) => j.slug), ['873-leftnav-two-face-framework']);
+});
+
+test('a dep with no row at all is treated as already done (archived/retired)', () => {
+  const jobs = [
+    job('874-nav-face-project-home', 'pending', { dependsOn: ['some-long-archived-prd'] }),
+  ];
+  const { batch } = pick(jobs);
+  assert.deepEqual(batch.map((j) => j.slug), ['874-nav-face-project-home']);
+});
+
+test('a FAILED bare-named dep holds the dependent and reports an explicit reason', () => {
+  const jobs = [
+    job('873-leftnav-two-face-framework', 'failed'),
+    job('874-nav-face-project-home', 'pending', { dependsOn: ['leftnav-two-face-framework'] }),
+  ];
+  const { batch, reason } = pick(jobs);
+  assert.deepEqual(batch, []);
+  assert.match(reason, /depends-gate/);
+  assert.match(reason, /874-nav-face-project-home <- leftnav-two-face-framework/);
+});

package/src/main/lib/auditLog.cjs

@@ -0,0 +1,60 @@
+/**
+ * auditLog.cjs — append-only trace of every Epic/PRD creation, so a rogue or
+ * unexpected Epic/PRD can always be traced back to its origin.
+ *
+ * Deliberately machine-level (~/.claude/session-manager/), not under any
+ * project's session-manager-operations/ — this is a security trace, not app
+ * state a project's single-writer law needs to arbitrate, and it must
+ * survive even if the project's ops root doesn't exist yet.
+ *
+ * Best-effort only: a logging failure must never block the mint/create it is
+ * observing (same posture as rcaFeedbackHook.cjs / dodDrainHook.cjs).
+ *
+ * Plain Node module (no Electron deps) so scripts/mint-epic.cjs and
+ * scripts/propose-epic.cjs (which run outside Electron) can require it too.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const AUDIT_LOG_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'audit-log.jsonl');
+
+/**
+ * Best-effort identity of the process making this call — there is no
+ * cryptographic caller identity available across the admin HTTP API (bearer
+ * token proves "runs as this OS user", not "which agent/session"), so this
+ * captures every breadcrumb that IS available: this process's pid/ppid, and
+ * (when set) the claude session id chatRunner.cjs stamps on headless
+ * `claude -p` children and passes down to MCP server children.
+ */
+function callerContext() {
+  return {
+    pid: process.pid,
+    ppid: process.ppid,
+    claudeSessionId: process.env.SM_CHAT_SESSION_ID || null,
+  };
+}
+
+/**
+ * appendAuditEvent(kind, fields) — append one JSONL record. `kind` is a short
+ * label ('epic_mint' | 'prd_create' | ...); `fields` is event-specific detail
+ * (cwd, epicId, status, title, slug, etc). Never throws.
+ */
+function appendAuditEvent(kind, fields = {}) {
+  try {
+    const record = {
+      at: new Date().toISOString(),
+      kind,
+      ...fields,
+      caller: callerContext(),
+    };
+    fs.mkdirSync(path.dirname(AUDIT_LOG_PATH), { recursive: true });
+    fs.appendFileSync(AUDIT_LOG_PATH, `${JSON.stringify(record)}\n`);
+  } catch (e) {
+    console.error('[auditLog] failed to append audit event', e?.message ?? String(e));
+  }
+}
+
+module.exports = { appendAuditEvent, AUDIT_LOG_PATH };

package/src/main/lib/epicMint.cjs

@@ -22,6 +22,7 @@ const path = require('node:path');
 const crypto = require('node:crypto');
 const { resolveEpicPrdWriteDir } = require('./prdLocations.cjs');
 const { assertOpsWrite } = require('./opsOwnership.cjs');
+const { appendAuditEvent } = require('./auditLog.cjs');
 
 function activeIndexPath(cwd) {
   return path.join(cwd, 'session-manager-operations', 'prompt-sessions', 'active-index.json');
@@ -164,6 +165,11 @@ function ensureEpic(cwd, { goalText, tag, reuseByGoal = false, epicId: explicitE
     index.events[epicId] = [firstEvent];
     writeActiveIndex(cwd, index);
 
+    // Every mint is logged, whether the Epic starts 'proposed' (human gate
+    // ahead) or 'active' (started immediately) — this is the trace-back point
+    // for "who/what created this Epic" (see auditLog.cjs).
+    appendAuditEvent('epic_mint', { cwd, epicId, status, tag: tag ?? null, goalText: session.goalText });
+
     const prdDir = resolveEpicPrdWriteDir(cwd, epicId);
     fs.mkdirSync(prdDir, { recursive: true });
     return { epicId, prdDir, created: true };

package/src/main/lib/localAdminHttp.cjs

@@ -49,6 +49,15 @@ const TOKEN_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'admin-
  * harmless tie-break, since real launches only ever set one or the other.
  */
 function resolveTokenPath() {
+  // Explicit override, highest priority. Exists because the unit tests call
+  // createAdminHttp().start() directly with neither SM_DEV nor SM_E2E set,
+  // which resolved to the PRODUCTION admin-api.json and overwrote the
+  // running app's port+token with a throwaway test server's — silently
+  // orphaning scheduler-mcp-server.cjs's access to the live app until the
+  // next app restart (confirmed live 2026-08-01: `npm run test:unit` made
+  // every scheduler_* MCP tool report "app is not running"). Tests point
+  // this at a tmp file; production never sets it.
+  if (process.env.SM_ADMIN_TOKEN_PATH) return process.env.SM_ADMIN_TOKEN_PATH;
   if (process.env.SM_DEV === '1') {
     return path.join(os.homedir(), '.claude', 'session-manager', 'admin-api.dev.json');
   }

package/src/main/lib/opsErrorLog.cjs

@@ -0,0 +1,96 @@
+'use strict';
+
+/**
+ * opsErrorLog.cjs — sole writer of the `logs` ops namespace
+ * (single-writer law, see opsOwnership.cjs). Appends one structured JSONL
+ * line per error to `<cwd>/session-manager-operations/logs/errors-<date>.jsonl`
+ * so errors from every tab/surface land in one common, per-project place
+ * instead of scattered across console.error calls and the machine-global
+ * <userData>/logs/ (which mixes every project together and isn't tagged for
+ * tracing). Every call site funnels through `appendError` — that is what
+ * makes this the sole writer in practice, not just in the OWNERS map.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { assertOpsWrite } = require('./opsOwnership.cjs');
+
+// Same redaction policy as logs.cjs's sanitizeMeta — kept independent (not
+// shared/required) so this module has no dependency on the Electron `app`
+// module and can be unit-tested without a running app.
+const REDACT_KEY = /^(transcript|interim|final|text|content|partial|userText|message|token|secret|password|authorization|cookie|api[_-]?key|access[_-]?token|refresh[_-]?token)$/i;
+
+function sanitizeMeta(meta) {
+  if (!meta || typeof meta !== 'object') return meta;
+  if (Array.isArray(meta)) return meta;
+  const out = {};
+  for (const [k, v] of Object.entries(meta)) {
+    out[k] = REDACT_KEY.test(k) ? '[redacted]' : v;
+  }
+  return out;
+}
+
+function logsDir(cwd) {
+  return path.join(cwd, 'session-manager-operations', 'logs');
+}
+
+function todayFile(cwd) {
+  const d = new Date();
+  const yyyy = d.getFullYear();
+  const mm = String(d.getMonth() + 1).padStart(2, '0');
+  const dd = String(d.getDate()).padStart(2, '0');
+  return path.join(logsDir(cwd), `errors-${yyyy}-${mm}-${dd}.jsonl`);
+}
+
+/**
+ * Append one structured error line, tagged for tracing/analysis.
+ *
+ * @param {{
+ *   cwd: string,           // required — which project's ops root owns this line
+ *   scope: string,         // subsystem name, e.g. 'pty', 'chatRunner', 'voice'
+ *   level?: string,        // default 'error'; 'warn' also accepted
+ *   tabId?: string,        // claudeSessionId of the tab this error belongs to, if any
+ *   epicId?: string,       // Epic id, if this error happened inside an Epic-backed run
+ *   tags?: string[],       // extra caller-supplied tags, merged with the auto-derived ones
+ *   message: string,
+ *   meta?: unknown,
+ * }} entry
+ */
+function appendError({ cwd, scope, level = 'error', tabId, epicId, tags = [], message, meta }) {
+  if (!cwd || typeof cwd !== 'string') return; // no project to attribute this line to — skip
+  const file = todayFile(cwd);
+  try {
+    assertOpsWrite(file, 'logs');
+  } catch {
+    return; // fail-closed, same as every other ops write path — never throw from a log call
+  }
+
+  const autoTags = [
+    `level:${level}`,
+    `scope:${scope || 'unknown'}`,
+    ...(tabId ? [`tab:${tabId}`] : []),
+    ...(epicId ? [`epic:${epicId}`] : []),
+  ];
+  const allTags = Array.from(new Set([...autoTags, ...tags]));
+
+  const line = {
+    ts: new Date().toISOString(),
+    level,
+    scope: scope || 'unknown',
+    tabId: tabId || null,
+    epicId: epicId || null,
+    tags: allTags,
+    message: String(message ?? ''),
+    ...(meta !== undefined ? { meta: sanitizeMeta(meta) } : {}),
+  };
+
+  try {
+    fs.mkdirSync(logsDir(cwd), { recursive: true });
+    // 0o600: same rationale as logs.cjs — error meta can carry local paths /
+    // device labels, keep it off other local users' reach.
+    const fd = fs.openSync(file, 'a', 0o600);
+    try { fs.writeSync(fd, JSON.stringify(line) + '\n'); } finally { fs.closeSync(fd); }
+  } catch { /* best-effort — a logging failure must never break the caller */ }
+}
+
+module.exports = { appendError, logsDir, todayFile };