claude-code-session-manager 0.86.0 → 0.88.0

package/src/main/__tests__/scheduler-tick-wedge.test.cjs

@@ -0,0 +1,172 @@
+/**
+ * scheduler-tick-wedge.test.cjs — tickQueue's serialized chain (tickTail) must
+ * survive a tick body that never settles: the body is bounded by a watchdog,
+ * the chain resets, and a late-resuming stale body is fenced off (no spawn, no
+ * mutate). mutateTail is never reset.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-tick-wedge.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeAll, afterAll } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+let tmpHome;
+let originalHome;
+let originalClaudeBin;
+let originalAutofix;
+let originalWatchdog;
+let originalClaudeVersion;
+let scheduler;
+let queueStore;
+let auditLog;
+let spawnMarker;
+
+function auditKinds() {
+  try {
+    return fs.readFileSync(auditLog.auditLogPath(), 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l).kind);
+  } catch { return []; }
+}
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  originalClaudeBin = process.env.SM_CLAUDE_BIN;
+  originalAutofix = process.env.SM_AUTOFIX_DISABLE;
+  originalWatchdog = process.env.SM_TICK_WATCHDOG_MS;
+  // This test's spawn marker is written by the stub on ANY invocation, including the
+  // `claude --version` probe — so it needs the real probe, not the sandbox's pinned version.
+  originalClaudeVersion = process.env.SM_CLAUDE_VERSION;
+  delete process.env.SM_CLAUDE_VERSION;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-tick-wedge-'));
+  process.env.HOME = tmpHome;
+  process.env.SM_AUTOFIX_DISABLE = '1';
+  // Any spawn of the "claude" binary drops a marker file: proof spawnJob ran.
+  spawnMarker = path.join(tmpHome, 'claude-spawned.marker');
+  const stubPath = path.join(tmpHome, 'claude-stub.cjs');
+  const body = `require('node:fs').appendFileSync(${JSON.stringify(spawnMarker)}, 'x');\n`
+    + `process.stdout.write(JSON.stringify({ type: 'result', subtype: 'success', result: 'ok\\nSCHEDULER_VERDICT: PASS' }) + '\\n');\n`
+    + 'process.exit(0);\n';
+  fs.writeFileSync(stubPath, `#!${process.execPath}\n${body}`, { mode: 0o755 });
+  process.env.SM_CLAUDE_BIN = stubPath;
+  fs.mkdirSync(path.join(tmpHome, '.claude', 'session-manager'), { recursive: true });
+  fs.mkdirSync(path.join(tmpHome, '.claude', 'projects'), { recursive: true });
+  scheduler = require('../scheduler.cjs');
+  queueStore = require('../lib/queueStore.cjs');
+  auditLog = require('../lib/auditLog.cjs');
+});
+
+afterAll(() => {
+  process.env.HOME = originalHome;
+  for (const [k, v] of [['SM_CLAUDE_BIN', originalClaudeBin], ['SM_AUTOFIX_DISABLE', originalAutofix], ['SM_TICK_WATCHDOG_MS', originalWatchdog], ['SM_CLAUDE_VERSION', originalClaudeVersion]]) {
+    if (v === undefined) delete process.env[k]; else process.env[k] = v;
+  }
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+test('a never-settling tick body is declared wedged, the chain resets, the stale body is fenced, audit fires once', async () => {
+  process.env.SM_TICK_WATCHDOG_MS = '150';
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-tick-wedge-project-'));
+  const projDir = fs.mkdtempSync(path.join(tmpHome, '.claude', 'projects', 'sm-tick-wedge-fake-'));
+  fs.writeFileSync(path.join(projDir, 'session.jsonl'), `${JSON.stringify({ cwd })}\n`, 'utf8');
+  const slug = `9003-tick-wedge-${process.pid}`;
+  await scheduler.writeQueue({
+    jobs: [{ slug, title: 'x', cwd, status: 'pending', dependsOn: [] }],
+    config: {},
+    paused: null,
+  });
+
+  // The first readMerged (the tick body's first await) hangs until released;
+  // every later call delegates to the real reader.
+  const realRead = queueStore.readMerged;
+  let release;
+  const hung = new Promise((r) => { release = r; });
+  let calls = 0;
+  queueStore.readMerged = function patched(...args) {
+    calls += 1;
+    if (calls === 1) return hung;
+    return realRead.apply(this, args);
+  };
+
+  try {
+    const wedgedResult = await scheduler.tickQueue();
+    expect(wedgedResult).toMatchObject({ fired: false, reason: 'wedged' });
+    expect(auditKinds().filter((k) => k === 'tick_wedged')).toHaveLength(1);
+
+    // A second wedge in the same episode (no normal tick between) must not re-audit.
+    calls = 0;
+    const hung2 = new Promise(() => {});
+    queueStore.readMerged = function patched2(...args) {
+      calls += 1;
+      if (calls === 1) return hung2;
+      return realRead.apply(this, args);
+    };
+    const again = await scheduler.tickQueue();
+    expect(again).toMatchObject({ reason: 'wedged' });
+    expect(auditKinds().filter((k) => k === 'tick_wedged')).toHaveLength(1);
+
+    // Next tick runs on a fresh chain (real reader, generous budget).
+    queueStore.readMerged = realRead;
+    process.env.SM_TICK_WATCHDOG_MS = '30000';
+    // Launch gates this case controls, so the dispatch assertion below does not
+    // depend on host state: the CPU load gate (loadavg1/cores > 0.85 -> 'load-deferred')
+    // via tickQueue's bypassLoadGate, and the memory gate ('memory-deferred', reads
+    // MemAvailable from /proc/meminfo) via a stubbed fs.readFileSync for that one path.
+    const realReadFileSync = fs.readFileSync;
+    fs.readFileSync = function patchedReadFileSync(file, ...rest) {
+      if (file === '/proc/meminfo') return 'MemAvailable:   67108864 kB\n';
+      return realReadFileSync.call(this, file, ...rest);
+    };
+    let fresh;
+    try {
+      fresh = await scheduler.tickQueue({ bypassLoadGate: true });
+    } finally {
+      fs.readFileSync = realReadFileSync;
+    }
+    expect(fresh.reason).not.toBe('wedged');
+
+    // Let the fresh tick's own spawn (if any) finish, then clear the marker.
+    // The fresh tick must have dispatched: wait for the stub's marker, then for
+    // the row to leave running/pending (spawnJob is fire-and-forget).
+    const deadline = Date.now() + 10_000;
+    while (Date.now() < deadline) {
+      const row = queueStore.readMergedSync().jobs.find((j) => j.slug === slug);
+      if (fs.existsSync(spawnMarker) && (!row || (row.status !== 'running' && row.status !== 'pending'))) break;
+      await new Promise((r) => setTimeout(r, 25));
+    }
+    expect(fs.existsSync(spawnMarker)).toBe(true);
+    fs.rmSync(spawnMarker, { force: true });
+
+    // Late-resume the stale body with a state that WOULD dispatch a pending job.
+    const before = queueStore.readMergedSync();
+    const staleState = {
+      ...before,
+      jobs: [{ slug: `9004-tick-wedge-stale-${process.pid}`, title: 'y', cwd, status: 'pending', dependsOn: [] }],
+      config: { ...(before.config || {}) },
+    };
+    release(staleState);
+    await new Promise((r) => setTimeout(r, 300));
+    expect(fs.existsSync(spawnMarker)).toBe(false);
+  } finally {
+    queueStore.readMerged = realRead;
+  }
+});
+
+test('a slow-but-healthy tick under the budget is not flagged as wedged', async () => {
+  process.env.SM_TICK_WATCHDOG_MS = '2000';
+  const realRead = queueStore.readMerged;
+  const before = auditKinds().filter((k) => k === 'tick_wedged').length;
+  queueStore.readMerged = async function slow(...args) {
+    await new Promise((r) => setTimeout(r, 100));
+    return realRead.apply(this, args);
+  };
+  try {
+    const r = await scheduler.tickQueue();
+    expect(r?.reason).not.toBe('wedged');
+    expect(auditKinds().filter((k) => k === 'tick_wedged').length).toBe(before);
+  } finally {
+    queueStore.readMerged = realRead;
+  }
+});

package/src/main/__tests__/scheduler-transient-failure.test.cjs

@@ -4,12 +4,12 @@
  * requeue instead of burning a whole run + an auto-fix investigation on an
  * outage that has nothing to do with the code.
  *
- * Run: timeout 120 node --test src/main/__tests__/scheduler-transient-failure.test.cjs
+ * Run: timeout 300 npx vitest run src/main/__tests__/scheduler-transient-failure.test.cjs
  */
 
 'use strict';
 
-const { test } = require('node:test');
+import { test } from 'vitest';
 const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const os = require('node:os');

package/src/main/__tests__/scheduler-worktree-cap-defer.test.cjs

@@ -18,6 +18,7 @@ import { test, expect, beforeAll, afterAll, afterEach } from 'vitest';
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const claudeStub = require('../../../tests/helpers/claudeStub.cjs');
 const { execFileSync } = require('node:child_process');
 
 let tmpHome;
@@ -30,6 +31,24 @@ function git(args, cwd) {
   return execFileSync('git', args, { cwd, encoding: 'utf8' });
 }
 
+// A completed job's PRD is archived immediately (archiveCompletedPrd, called
+// for EVERY job that reaches effectiveStatus:'completed' — not just a
+// retention-aged one), and the very next reconcile() pass (spawnJob's own
+// broadcast({flush:true}) right after finishing) then finds the row's PRD
+// gone and backfills+drops it from queue.json into history.jsonl in that
+// SAME pass — see scheduler-reconcile-history-backfill.test.cjs. So a job
+// that actually completed is found in EITHER queue.json OR history.jsonl,
+// never guaranteed to still be the former.
+function readTerminalRow(queuePath, projectCwd, slug) {
+  const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
+  const row = jobs.find((j) => j.slug === slug);
+  if (row) return row;
+  const historyPath = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'state', 'history.jsonl');
+  if (!fs.existsSync(historyPath)) return undefined;
+  const lines = fs.readFileSync(historyPath, 'utf8').trim().split('\n').filter(Boolean);
+  return lines.map((l) => JSON.parse(l)).reverse().find((j) => j.slug === slug);
+}
+
 function initRepo(dir) {
   fs.mkdirSync(dir, { recursive: true });
   git(['init', '-q'], dir);
@@ -61,8 +80,9 @@ function writeProjectQueue(cwd, jobs) {
 // test can prove whether — and where — it was actually spawned, then emits a
 // clean stream-json success result.
 function writeClaudeStub() {
-  const stubPath = path.join(os.tmpdir(), `sm-claude-stub-capdefer-${process.pid}-${Math.floor(Math.random() * 1e9)}.cjs`);
-  const body = `
+  return claudeStub.writeClaudeStub({
+    allowCommitUnder: os.tmpdir(),
+    body: `
     const fs = require('fs');
     const path = require('path');
     const { execFileSync } = require('child_process');
@@ -73,14 +93,13 @@ function writeClaudeStub() {
     // fallback case), where the run parks in needs_review instead, which is
     // fine — this test only cares whether it ran in place, not its verdict.
     try {
-      execFileSync('git', ['add', '-A'], { cwd: process.cwd() });
-      execFileSync('git', ['commit', '-q', '-m', 'stub commit'], { cwd: process.cwd() });
+      runGit(['add', '-A']);
+      runGit(['commit', '-q', '-m', 'stub commit']);
     } catch { /* not a git repo — best-effort only */ }
     process.stdout.write(JSON.stringify({ type: 'result', subtype: 'success', result: 'ok\\nSCHEDULER_VERDICT: PASS' }) + '\\n');
     process.exit(0);
-  `;
-  fs.writeFileSync(stubPath, `#!${process.execPath}\n${body}\n`, { mode: 0o755 });
-  return stubPath;
+  `,
+  });
 }
 
 beforeAll(() => {
@@ -111,7 +130,13 @@ test('a job held behind the worktree cap stays pending with a heldReason, is nev
   registerActiveProject(projectCwd);
 
   const slug = `1112-test-held-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
-  const prdsDir = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'prds');
+  // Epic-scoped, not the legacy flat prds/ dir: the flat dir is retired and
+  // swept into prds-archived/ by consolidateFlatPrds on every reconcile()
+  // pass once a row is no longer 'pending'/'running' — which would strand
+  // this test's row the moment it completes (reconcile()'s terminal-job
+  // "PRD gone -> archived on purpose" drop, see
+  // scheduler-reconcile-history-backfill.test.cjs).
+  const prdsDir = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'epics', 'test-fixture-epic', 'prds');
   fs.mkdirSync(prdsDir, { recursive: true });
   fs.writeFileSync(path.join(prdsDir, `${slug}.md`), 'Held behind the worktree cap.', 'utf8');
   const queuePath = writeProjectQueue(projectCwd, [{ slug, status: 'pending', cwd: projectCwd }]);
@@ -147,8 +172,8 @@ test('a job held behind the worktree cap stays pending with a heldReason, is nev
 
     await spawnJob({ slug, cwd: projectCwd }, `${runId}-2`, runDir, projectCwd);
 
-    jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
-    row = jobs.find((j) => j.slug === slug);
+    row = readTerminalRow(queuePath, projectCwd, slug);
+    expect(row).toBeTruthy();
     expect(row.status).toBe('completed');
     expect(row.heldReason).toBeUndefined();
   } finally {
@@ -163,7 +188,8 @@ test('a non-git cwd still falls back to running in place (unchanged behaviour
   registerActiveProject(projectCwd);
 
   const slug = `1112-test-nongit-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
-  const prdsDir = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'prds');
+  // Epic-scoped — see the sibling test above for why not the flat prds/ dir.
+  const prdsDir = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'epics', 'test-fixture-epic', 'prds');
   fs.mkdirSync(prdsDir, { recursive: true });
   fs.writeFileSync(path.join(prdsDir, `${slug}.md`), 'Non-git cwd, must run in place.', 'utf8');
   const queuePath = writeProjectQueue(projectCwd, [{ slug, status: 'pending', cwd: projectCwd }]);
@@ -187,6 +213,20 @@ test('a non-git cwd still falls back to running in place (unchanged behaviour
     expect(row.worktreeFallbackReason).toMatch(/not a git repository/);
     // Ran IN PLACE — the marker landed directly in projectCwd, not a worktree.
     expect(fs.existsSync(path.join(projectCwd, 'ran-here.marker'))).toBe(true);
+
+    // A job losing worktree isolation must never be a silent downgrade
+    // discoverable only by reading queue.json afterwards — it must also land
+    // as a warn line in the durable ops error log, naming the slug, cwd, and
+    // reason.
+    const { todayFile } = require('../lib/opsErrorLog.cjs');
+    const errorLogPath = todayFile(projectCwd);
+    expect(fs.existsSync(errorLogPath)).toBe(true);
+    const logLines = fs.readFileSync(errorLogPath, 'utf8').trim().split('\n').map((l) => JSON.parse(l));
+    const fallbackLine = logLines.find((l) => l.scope === 'scheduler' && l.level === 'warn' && l.message.includes(slug));
+    expect(fallbackLine).toBeTruthy();
+    expect(fallbackLine.message).toMatch(/SHARED working tree/);
+    expect(fallbackLine.message).toMatch(/not a git repository/);
+    expect(fallbackLine.meta).toMatchObject({ slug, cwd: projectCwd, reason: expect.stringMatching(/not a git repository/) });
   } finally {
     fs.rmSync(projectCwd, { recursive: true, force: true });
     fs.rmSync(runDir, { recursive: true, force: true });

package/src/main/__tests__/scheduler-worktree-exec-cwd.test.cjs

@@ -23,6 +23,7 @@ import { test, expect, beforeAll, afterAll, afterEach } from 'vitest';
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const claudeStub = require('../../../tests/helpers/claudeStub.cjs');
 
 let tmpHome;
 let originalHome;
@@ -48,16 +49,13 @@ afterEach(() => {
 // where it actually ran), captures the '-p' prompt, then emits a stream-json
 // success result and exits 0.
 function writeClaudeStub() {
-  const stubPath = path.join(os.tmpdir(), `sm-claude-stub-${process.pid}-${Math.floor(Math.random() * 1e9)}.cjs`);
-  const body = `
+  return claudeStub.writeClaudeStub({ body: `
     const fs = require('fs');
     const path = require('path');
     fs.writeFileSync(path.join(process.cwd(), 'ran-here.marker'), 'yes', 'utf8');
     process.stdout.write(JSON.stringify({ type: 'result', subtype: 'success', result: 'ok' }) + '\\n');
     process.exit(0);
-  `;
-  fs.writeFileSync(stubPath, `#!${process.execPath}\n${body}\n`, { mode: 0o755 });
-  return stubPath;
+  ` });
 }
 
 test('executeJob spawns the child in execCwd (worktree) while resolving the PRD from job.cwd (main tree)', async () => {

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

@@ -0,0 +1,157 @@
+/**
+ * usageSingleFlight.test.cjs — usage.cjs's fetchUsage() is the single owner
+ * of caching, single-flight de-duplication, and the shared usageCircuit for
+ * the /api/oauth/usage meter. Before this, the renderer's billing:fetch IPC
+ * handler owned the 30s OK-cache alone and the scheduler's pollLoop called
+ * fetchUsage() directly with no cache/dedup — two independent request
+ * streams against a rate-limiting endpoint, and a success on one path never
+ * reset the other's failure streak. This suite proves: (1) concurrent
+ * fetchUsage() callers coalesce into exactly one network fetch, (2) a
+ * success resets the shared circuit's streak regardless of which "caller"
+ * triggered the preceding failures, and (3) a 429's Retry-After suppresses
+ * the next request until it elapses.
+ *
+ * Never hits the live billing endpoint — global.fetch is stubbed throughout,
+ * and HOME is pointed at a scratch dir so no real credentials/cache file on
+ * this machine is ever read.
+ *
+ * usage.cjs (and config.cjs/credentials.cjs, which it requires) are loaded
+ * via Node's own require() — this is a .cjs test, not transformed ESM — so
+ * vi.mock()/vi.resetModules() do NOT intercept them the way they would for
+ * an ESM import graph; both also bake os.homedir() into module-level
+ * constants at first require (config.cjs's allowedRoots/WRITE_PREFIXES,
+ * usage.cjs's CACHE_PATH, credentials.cjs's CREDS_PATH). So this suite
+ * follows historyRollup.test.cjs's pattern instead: swap $HOME to a fresh
+ * tmp dir with a valid, far-from-expiry fake credentials file, purge
+ * Node's require.cache for every affected module, and re-require fresh
+ * each test.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/usageSingleFlight.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, vi, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+function jsonResponse(status, body, headers = {}) {
+  return {
+    status,
+    ok: status >= 200 && status < 300,
+    text: async () => JSON.stringify(body),
+    json: async () => body,
+    headers: { get: (k) => headers[k.toLowerCase()] ?? null },
+  };
+}
+
+const usagePayload = { five_hour: { utilization: 10, resets_at: null }, seven_day: { utilization: 10, resets_at: null }, seven_day_sonnet: null, seven_day_opus: null, extra_usage: null };
+
+const MODULES_TO_RELOAD = [
+  '../usage.cjs',
+  '../config.cjs',
+  '../lib/credentials.cjs',
+  '../lib/usageCircuit.cjs',
+];
+
+function purgeRequireCache() {
+  for (const m of MODULES_TO_RELOAD) {
+    try { delete require.cache[require.resolve(m)]; } catch { /* not loaded yet */ }
+  }
+}
+
+let realHome;
+let tmpHome;
+
+beforeEach(() => {
+  realHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'usage-single-flight-test-'));
+  process.env.HOME = tmpHome;
+  fs.mkdirSync(path.join(tmpHome, '.claude'), { recursive: true });
+  fs.writeFileSync(
+    path.join(tmpHome, '.claude', '.credentials.json'),
+    JSON.stringify({
+      claudeAiOauth: {
+        accessToken: 'test-access-token',
+        refreshToken: 'test-refresh-token',
+        expiresAt: Date.now() + 1_000 * 60 * 60 * 24, // 24h out — never "expiring soon"
+        subscriptionType: 'max',
+        rateLimitTier: 'default_claude_max_20x',
+      },
+    }),
+  );
+  purgeRequireCache();
+});
+
+afterEach(() => {
+  process.env.HOME = realHome;
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+  purgeRequireCache();
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+test('two concurrent fetchUsage() calls produce exactly one HTTP fetch', async () => {
+  const { fetchUsage } = require('../usage.cjs');
+  let fetchCalls = 0;
+  vi.stubGlobal('fetch', vi.fn(async () => {
+    fetchCalls++;
+    // Slow enough that both callers are guaranteed to be in-flight together.
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    return jsonResponse(200, usagePayload);
+  }));
+
+  const [a, b] = await Promise.all([fetchUsage(), fetchUsage()]);
+
+  expect(fetchCalls).toBe(1);
+  expect(a.kind).toBe('ok');
+  expect(b.kind).toBe('ok');
+});
+
+test('an ok result resets the shared circuit streak built up by prior failures', async () => {
+  const usage = require('../usage.cjs');
+  const circuit = usage.__usageCircuitForTest;
+
+  let call = 0;
+  vi.stubGlobal('fetch', vi.fn(async () => {
+    call++;
+    if (call <= 3) return jsonResponse(500, { error: 'boom' });
+    return jsonResponse(200, usagePayload);
+  }));
+
+  // Three consecutive transient failures — simulating the scheduler's poller
+  // failing repeatedly — trip the circuit open.
+  await usage.fetchUsage();
+  await usage.fetchUsage();
+  await usage.fetchUsage();
+  expect(circuit.state()).toBe('open');
+
+  // A later success — as if it came from the renderer's independent
+  // billing:fetch call, but reached through the SAME shared fetchUsage() —
+  // must reset the streak the scheduler's calls built up, since both
+  // callers share one circuit instance.
+  const ok = await usage.fetchUsage();
+  expect(ok.kind).toBe('ok');
+  expect(circuit.state()).toBe('closed');
+});
+
+test('a 429 with Retry-After suppresses the next request until it elapses', async () => {
+  const usage = require('../usage.cjs');
+
+  let fetchCalls = 0;
+  vi.stubGlobal('fetch', vi.fn(async () => {
+    fetchCalls++;
+    return jsonResponse(429, { error: { type: 'rate_limit_error' } }, { 'retry-after': '60' });
+  }));
+
+  const first = await usage.fetchUsage();
+  expect(first.kind).toBe('meter_rate_limited');
+  expect(first.retryAfterMs).toBe(60_000);
+
+  const second = await usage.fetchUsage();
+  expect(second.kind).toBe('meter_rate_limited');
+  expect(second.suppressed).toBe(true);
+  // No second network call — the suppression window hasn't elapsed.
+  expect(fetchCalls).toBe(1);
+});

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

@@ -46,7 +46,7 @@ test('WORK_TYPES matches the tag ids declared in tagLibrary.ts TAG_LIBRARY, in o
   expect(tagMatches).toEqual(WORK_TYPES);
 });
 
-test('api.d.ts tag unions (line ~1166 and ~1687) both contain exactly the same 6 values', () => {
+test('api.d.ts tag unions both contain exactly the same 6 values', () => {
   const src = fs.readFileSync(API_D_TS_PATH, 'utf8');
   const unionMatches = [...src.matchAll(/tag\?:\s*((?:'[^']+'\s*\|?\s*)+);/g)].map((m) =>
     m[1]

package/src/main/bilkoHost.cjs

@@ -46,6 +46,10 @@ const {
 const WRITER = 'bilko-host';
 const PROJECT_PAGE_LENSES = new Set(['home', 'marketing', 'feature', 'architecture']);
 
+function homePagePath(cwd) {
+  return opsPath(cwd, 'project-pages', 'home.html');
+}
+
 function bilkoHostDir(cwd) {
   return opsPath(cwd, 'bilko-host');
 }
@@ -103,9 +107,10 @@ async function writeDocuments(cwd, documents) {
 async function get({ cwd }) {
   const realCwd = config.validatePath(cwd);
 
-  const marketingResult = await config.readText(
-    opsPath(realCwd, 'project-pages', 'output', 'marketing.html'),
-  );
+  // The single Project Home page (project-pages/home.html) seeds the root
+  // document. `hasMarketingPage` is the renderer's legacy field name for
+  // "a root-document source page exists".
+  const marketingResult = await config.readText(homePagePath(realCwd));
   const pkgResult = await config.readJson(path.join(realCwd, 'package.json'));
   const pkg = pkgResult.exists && !pkgResult.parseError ? pkgResult.data : null;
 
@@ -142,15 +147,15 @@ async function get({ cwd }) {
   };
 }
 
-/** Seeds documents.json with a single root document (the Marketing Project Page) if it doesn't exist yet. */
+/** Seeds documents.json with a single root document (the Project Home page, home.html) if it doesn't exist yet. */
 async function ensureSeededDocuments(cwd) {
   const existing = await readDocuments(cwd);
   if (existing) return existing;
   const seeded = [{
     id: crypto.randomUUID(),
     subpath: '',
-    title: 'Project (Marketing)',
-    source: { kind: 'project-page-lens', lens: 'marketing' },
+    title: 'Project (Home)',
+    source: { kind: 'project-page-lens', lens: 'home' },
     addedAt: new Date().toISOString(),
   }];
   await writeDocuments(cwd, seeded);
@@ -215,8 +220,12 @@ async function removeDocument({ cwd, id }) {
 
 async function resolveDocumentHtml(cwd, doc) {
   if (doc.source.kind === 'project-page-lens') {
+    // Only `home` is generated now (one home.html); the other lens names
+    // are legacy and resolve to their old output/<lens>.html if one exists.
     const result = await config.readText(
-      opsPath(cwd, 'project-pages', 'output', `${doc.source.lens}.html`),
+      doc.source.lens === 'home'
+        ? homePagePath(cwd)
+        : opsPath(cwd, 'project-pages', 'output', `${doc.source.lens}.html`),
     );
     if (!result.exists) {
       throw new Error(`document "${doc.title}" points at the ${doc.source.lens} Project Page, but it hasn't been generated yet`);

package/src/main/build-info.json

@@ -0,0 +1,8 @@
+{
+  "version": "0.88.0",
+  "gitSha": "8b723b765b5cb9f867b2ae244011b54ab3c81ef0",
+  "gitShortSha": "8b723b7",
+  "gitBranch": "HEAD",
+  "builtAt": "2026-09-19T14:31:26.080Z",
+  "dirty": false
+}

package/src/main/chatRunner.cjs

@@ -44,7 +44,7 @@
 
 const { spawn } = require('node:child_process');
 const { ipcMain } = require('electron');
-const { resolveClaudeBin } = require('./lib/claudeBin.cjs');
+const { resolveClaudeBin, claudeSpawnTarget } = require('./lib/claudeBin.cjs');
 const { cleanChildEnv, pathWithUserBins } = require('./lib/cleanEnv.cjs');
 const { recordExchange } = require('./exchanges.cjs');
 const { classifyToolUse } = require('./lib/toolUseClassify.cjs');
@@ -530,11 +530,14 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume, silent, onSilentRes
     const fullPrompt = STOP_SIGNAL_INSTRUCTION + CHAT_MODE_TRUTH_INSTRUCTION + prompt;
 
     // sessionId is the Epic's claudeSessionId for an Epic-backed tab (see
-    // comment above childEnv) — resolve that Epic's agentType persona model
-    // so Chat and Terminal views of the same Epic launch with the same
-    // model. Never throws; falls back to the hardcoded 'sonnet' literal when
-    // there's no Epic, no agentType, or the persona has no model/'inherit' —
-    // --model must never be left unpinned (CLAUDE.md model-pinning rule).
+    // comment above childEnv) — resolve that Epic's agentType persona model,
+    // project-overlay-then-global (agentModelResolve.cjs's
+    // readOverlayAwarePersonaModel). Terminal (EpicTerminalPane.tsx) calls
+    // this SAME function via the agents:resolve-epic-model IPC, so the two
+    // views of one Epic agree by construction, not by convention. Never
+    // throws; falls back to the hardcoded 'sonnet' literal when there's no
+    // Epic, no agentType, or the persona has no model/'inherit' — --model
+    // must never be left unpinned (CLAUDE.md model-pinning rule).
     const model = agentModelResolve.resolveEpicModel({ cwd, claudeSessionId: sessionId });
 
     // Build argv as an array — no shell: true, no string interpolation
@@ -568,7 +571,9 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume, silent, onSilentRes
     // real-time NDJSON streaming; stderr piped for error-message capture.
     let child;
     try {
-      child = spawn(claudeBin, args, {
+      const target = claudeSpawnTarget('chat', sessionId, claudeBin);
+      child = spawn(target.command, args, {
+        ...(target.argv0 ? { argv0: target.argv0 } : {}),
         cwd: execCwd,
         env: childEnv,
         stdio: ['ignore', 'pipe', 'pipe'],

package/src/main/config.cjs

@@ -148,9 +148,8 @@ function validateWrite(realAbs) {
       //                    (PRD 825; scheduler.cjs remote.writePrd)
       //   project-brief    projectBrief.cjs's brief.json (PRD 837)
       //   bilko-host       bilkoHost.cjs's bundle prep
-      //   project-pages    projectHomeAdminRoutes.cjs's app-side render path
-      //                    (summary.json/picks.json/output/*; PRD:
-      //                    project-home-admin-routes)
+      //   project-pages    projectHomeAdminRoutes.cjs's project_home_write
+      //                    path (home.html)
       // Paths come from opsOwnership.opsPath (PRD 1082) — the one ops-root
       // resolver — which THROWS for an ephemeral root (a linked worktree that
       // pty.cjs registered as an allowed root for its spawn cwd, or

package/src/main/docEdit.cjs

@@ -17,7 +17,8 @@
 const { ipcMain } = require('electron');
 const { spawn } = require('node:child_process');
 const crypto = require('node:crypto');
-const { resolveClaudeBin } = require('./lib/claudeBin.cjs');
+const { resolveClaudeBin, claudeSpawnTarget } = require('./lib/claudeBin.cjs');
+const { withProcRole } = require('./lib/cleanEnv.cjs');
 const { extractJson } = require('./lib/extractJson.cjs');
 const { assertInsideHome } = require('./lib/insideHome.cjs');
 const { expandHome } = require('./lib/expandHome.cjs');
@@ -99,7 +100,8 @@ function runClaude(prompt, { model = 'sonnet', timeoutMs = 90_000, systemPrompt
     // stdin MUST be closed ('ignore') — `claude -p` otherwise blocks waiting
     // for piped stdin and returns empty. SM_KG_INTERNAL=1 tells the
     // prompt-logging hook to skip this invocation.
-    const child = spawn(bin, args, { env: { ...process.env, SM_KG_INTERNAL: '1' }, stdio: ['ignore', 'pipe', 'pipe'] });
+    const target = claudeSpawnTarget('aux', 'docedit', bin);
+    const child = spawn(target.command, args, { env: withProcRole({ ...process.env, SM_KG_INTERNAL: '1' }, 'aux'), stdio: ['ignore', 'pipe', 'pipe'], ...(target.argv0 ? { argv0: target.argv0 } : {}) });
     let out = '';
     let err = '';
     // Cap accumulated stdout — the model output shouldn't grow `out` without