claude-code-session-manager 0.86.0 → 0.88.0

package/src/main/seedAgentPersonas.cjs

@@ -130,4 +130,4 @@ async function seedAgentPersonas({ logger = console, writeLog = () => {} } = {})
   }
 }
 
-module.exports = { seedAgentPersonas, markerPath, MAX_ATTEMPTS };
+module.exports = { seedAgentPersonas, markerPath, MAX_ATTEMPTS, PERSONAS };

package/src/main/seedDevPlugin.cjs

@@ -1,7 +1,7 @@
 /**
  * First-boot seeder for the bundled `session-manager-dev` plugin.
  *
- * The plugin (its 10 dev skills) ships inside the npx distribution. To make it
+ * The plugin (the dev skills under plugins/session-manager-dev/skills) ships inside the npx distribution. To make it
  * a true default, the app installs it on first launch from its own bundled
  * marketplace (offline — no GitHub/registry). Idempotent two ways:
  *

package/src/main/seedSchedulerMcp.cjs

@@ -35,7 +35,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 const { spawn } = require('node:child_process');
-const { resolveClaudeBin } = require('./lib/claudeBin.cjs');
+const { resolveClaudeBin, claudeSpawnTarget } = require('./lib/claudeBin.cjs');
 const { cleanChildEnv, pathWithUserBins } = require('./lib/cleanEnv.cjs');
 const { writeJsonSync } = require('./config.cjs');
 
@@ -106,13 +106,14 @@ function scriptPathMissing() {
  *  No shell:true — argv array passed directly to spawn. */
 function runClaudeMcpAdd(serverPath) {
   return new Promise((resolve) => {
-    const claudeBin = resolveClaudeBin();
+    const target = claudeSpawnTarget('aux', 'mcp-add');
     let proc;
     try {
       proc = spawn(
-        claudeBin,
+        target.command,
         ['mcp', 'add', SERVER_NAME, '--scope', 'user', '--', 'node', serverPath],
         {
+          ...(target.argv0 ? { argv0: target.argv0 } : {}),
           cwd: os.homedir(),
           env: cleanChildEnv({ PATH: pathWithUserBins() }),
           stdio: 'ignore',
@@ -130,13 +131,13 @@ function runClaudeMcpAdd(serverPath) {
 /** Run `claude mcp remove session-manager-scheduler --scope user`, best-effort. */
 function runClaudeMcpRemove() {
   return new Promise((resolve) => {
-    const claudeBin = resolveClaudeBin();
+    const target = claudeSpawnTarget('aux', 'mcp-remove');
     let proc;
     try {
       proc = spawn(
-        claudeBin,
+        target.command,
         ['mcp', 'remove', SERVER_NAME, '--scope', 'user'],
-        { cwd: os.homedir(), env: cleanChildEnv({ PATH: pathWithUserBins() }), stdio: 'ignore' }
+        { cwd: os.homedir(), env: cleanChildEnv({ PATH: pathWithUserBins() }), stdio: 'ignore', ...(target.argv0 ? { argv0: target.argv0 } : {}) }
       );
     } catch (err) {
       resolve({ ok: false, error: err?.message ?? String(err) });

package/src/main/seedStatus.cjs

@@ -43,7 +43,7 @@ const FIXES = {
   'dev-plugin': 'Open Plugins → Library and click Install next to "session-manager-dev".',
   'scheduler-mcp': () =>
     `Run in a terminal: claude mcp add ${seedSchedulerMcp.SERVER_NAME} --scope user -- node ${seedSchedulerMcp.serverScriptPath()}`,
-  'agent-personas': 'Copy src/seed/agents/architect.md and dev-lead.md into ~/.claude/agents/ (skip any that already exist there).',
+  'agent-personas': `Copy ${seedAgentPersonas.PERSONAS.map((n) => `src/seed/agents/${n}.md`).join(', ')} into ~/.claude/agents/ (skip any that already exist there).`,
 };
 
 /** { 'dev-plugin': {status, fix}, 'scheduler-mcp': {status, fix}, 'agent-personas': {status, fix} } */

package/src/main/supervisor.cjs

@@ -16,7 +16,8 @@ const path = require('node:path');
 const os = require('node:os');
 const { spawn, execFileSync } = require('node:child_process');
 const { ipcMain } = require('electron');
-const { resolveClaudeBin } = require('./lib/claudeBin.cjs');
+const { resolveClaudeBin, claudeSpawnTarget } = require('./lib/claudeBin.cjs');
+const { withProcRole } = require('./lib/cleanEnv.cjs');
 
 const HOME = os.homedir();
 const SUPERVISOR_LOG_PATH = path.join(HOME, '.claude', 'session-manager', 'supervisor.log');
@@ -207,7 +208,8 @@ function runProbe(claudeBin, prompt) {
   return new Promise((resolve) => {
     let child;
     try {
-      child = spawn(claudeBin, [
+      const target = claudeSpawnTarget('aux', 'supervisor', claudeBin);
+      child = spawn(target.command, [
         '-p', prompt,
         '--model', 'claude-opus-4-7',
         '--no-session-persistence',
@@ -215,7 +217,7 @@ function runProbe(claudeBin, prompt) {
         '--max-budget-usd', '0.10',
         '--dangerously-skip-permissions',
         '--allowedTools', 'Bash',
-      ], { stdio: ['ignore', 'pipe', 'pipe'] });
+      ], { env: withProcRole(process.env, 'aux'), stdio: ['ignore', 'pipe', 'pipe'], ...(target.argv0 ? { argv0: target.argv0 } : {}) });
     } catch (e) {
       console.error('[supervisor] probe spawn failed:', e?.message);
       resolve({ verdict: 'ok', action: 'none', targetPid: null, reason: `spawn failed: ${e?.message}`, costUsd: null });

package/src/main/templates/PRD_AUTHORING.md

@@ -1,3 +1,4 @@
+<!-- PRD_AUTHORING.md v2 -->
 # PRD Authoring Guide — Scheduler Safety Rules
 
 This guide codifies lessons from two stuck-job incidents (fizzpop poll-hang, etch-engine post-AC overrun) into enforceable rules every PRD MUST follow. Violating these rules costs real money and wastes hours waiting at a terminal.
@@ -148,6 +149,8 @@ estimateMinutes: 60
 
 **Rule:** Include exact file paths, function signatures if they save a Read, library versions, and the name of any sibling PRD the executor must NOT duplicate. Do not reference "the conversation", "what we discussed", "the design doc", or any other external context. If the executor would need to search for something, include the answer.
 
+**Epic context digest is additive, not a dependency (PRD 958):** when a job's `epicId` resolves to a known Epic in that project's `active-index.json`, the scheduler prepends a short digest of the Epic's own session (goal text + recent turns, built by `src/main/lib/epicContextDigest.cjs`'s `buildContextDigest`) to the `-p` prompt sent to the executor — the on-disk PRD `.md` file itself is never rewritten. This exists purely to orient the executor faster; it is never load-bearing. The digest is a silent no-op when the Epic doesn't resolve, and any failure building it is caught and logged, never blocking dispatch. Every PRD body must still stand on its own per the rule above — write it as if the digest will not be there.
+
 ---
 
 ## §8 Scope sizing — target ~15 min, ceiling 30 (data-driven, 2026-06)
@@ -448,3 +451,50 @@ intake`, commit `352b89c`). It syncs open GitHub issues into `session-manager-op
 → queue path the rest of this guide documents. An external project building a Slack (or any
 other) adapter should follow the same source → triage → queue shape, ending at
 `scheduler_create_prd` (app running) or a hand-written PRD file (app closed) as described above.
+
+## §15 Resolving a `failed`/`needs_review` job whose target work is already done
+
+**Symptom:** a job lands in `failed` or `needs_review` even though its actual objective was
+already satisfied — either by a sibling/concurrent job that finished the same work first (a
+duplicate PRD racing another one), or by an out-of-band actor (a human, another agent) reaching
+the same target state before the scheduler's run even started. The job's own transcript may be
+completely accurate (`SCHEDULER_VERDICT: PASS but no commit landed during the run window`) — the
+"failure" is a stale queue entry, not broken work.
+
+**Do NOT hand-edit `queue.json` to fix the status.** It's a live file the running Electron
+scheduler process (and the external watchdog) both read and write; a manual edit races the app's
+own save cycle and risks a torn write. There is also no supported IPC/CLI surface today to flip a
+single job's `status` field directly.
+
+**The safe, supported remediation — confirmed working live (2026-07-18):** archive the job's PRD
+*source file*, not the queue entry. `reconcile()` (`src/main/scheduler.cjs`) runs on every queue
+read/tick and drops any `queue.json` job entry whose PRD `.md` no longer exists in `prds/` — so
+archiving the file is sufficient; you never touch `queue.json` yourself.
+
+```js
+// From this repo's root (session-manager), or anywhere queueOps.cjs is reachable:
+const q = require('./src/main/queueOps.cjs');
+await q.archiveMany(['<slug-of-the-stale-job>']);
+// Atomic rename to prds-archived/<ISO>/<slug>.md — reversible, path-contained,
+// no queue.json write. The next reconcile() (within one scheduler tick, ~10-15s
+// observed) drops the matching queue.json job entry automatically.
+```
+
+This is the exact mechanism `schedule:clear-queue`'s IPC handler uses internally, just scoped to
+one slug instead of "every non-running job" — safe to call from outside Electron (no admin API
+needed) since `queueOps.cjs`'s `archiveMany` is a plain exported function, not IPC-gated.
+
+**When to use this vs. requeueing a retry:** only when you've confirmed the target state is
+already correct (read the failed job's own transcript/log — did it conclude "nothing left to
+do"? did a sibling job's commit already land the same objective? does an independent check like
+`gh pr view <n> --json mergeable` already show the desired end state?). If the target state is
+genuinely NOT yet reached, fix and requeue instead — archiving does not fix an actual bug, it
+only clears a stale status label for already-completed work.
+
+**Known gap this doesn't cover:** the verifier's `pass_no_commit` classification (a run that
+concludes "PASS, no code change needed" gets flagged `needs_review` as if it were suspicious)
+does not yet special-case "another actor already satisfied this PRD's postcondition" for
+externally-checkable targets (e.g. a `gh pr view`-mergeable branch). `RESCANNABLE_VERDICTS`
+already includes `pass_no_commit` for one narrow case (fix-plan jobs, exempted 2026-07-12) but
+not the general case. See `session-manager-operations/feedback/processed/` for the tracked
+follow-up on softening this classification for merge-style PRDs with a checkable postcondition.

package/src/main/usage.cjs

@@ -23,6 +23,7 @@ const os = require('node:os');
 const { ipcMain } = require('electron');
 const { refreshIfNeeded, expiresAtMs } = require('./lib/credentials.cjs');
 const { writeJson } = require('./config.cjs');
+const { createUsageCircuit, singleFlight } = require('./lib/usageCircuit.cjs');
 
 const USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
 
@@ -116,6 +117,19 @@ const OK_CACHE_TTL_MS = 30_000;
  *
  * Returns one of: 'ok' | 'auth' | 'transient' | 'meter_rate_limited'
  */
+/**
+ * Parses a `Retry-After` header value (delta-seconds or an HTTP-date) into a
+ * millisecond duration from now, or null if absent/unparseable.
+ */
+function parseRetryAfterMs(headerValue) {
+  if (!headerValue) return null;
+  const seconds = Number(headerValue);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
+  const dateMs = Date.parse(headerValue);
+  if (Number.isFinite(dateMs)) return Math.max(0, dateMs - Date.now());
+  return null;
+}
+
 function classifyUsageResponse(status, bodyText) {
   if (status === 401 || status === 403) return { kind: 'auth', httpStatus: status };
   if (status === 429) {
@@ -133,6 +147,18 @@ function classifyUsageResponse(status, bodyText) {
 
 let cache = null;
 let hydrationPromise = null;
+// Retry-After suppression window: while `now < retryNotBeforeMs`, fetchUsage()
+// refuses to issue another request and instead replays `lastRateLimitedResult`
+// (annotated `suppressed: true`) — set only from a 429's Retry-After header.
+let retryNotBeforeMs = 0;
+let lastRateLimitedResult = null;
+
+// Single shared circuit for the /api/oauth/usage meter. Both callers — the
+// renderer's billing:fetch IPC handler and the scheduler's pollLoop — go
+// through this same fetchUsage(), so a success recorded from EITHER caller
+// clears the streak for both, and concurrent callers coalesce into one HTTP
+// request via singleFlight.
+const circuit = createUsageCircuit();
 
 async function hydrateCache() {
   try {
@@ -142,23 +168,17 @@ async function hydrateCache() {
   }
 }
 
+function ensureHydrated() {
+  if (!hydrationPromise) hydrationPromise = hydrateCache();
+  return hydrationPromise;
+}
+
 async function persistCache(c) {
   await writeJson(CACHE_PATH, c);
 }
 
-async function fetchUsage() {
-  // Test stub: SM_MOCK_BILLING_KIND lets e2e tests simulate billing API responses
-  // without hitting the real endpoint. Only active when SM_E2E=1 to prevent
-  // accidental use in production.
-  if (process.env.SM_E2E === '1' && process.env.SM_MOCK_BILLING_KIND) {
-    const kind = process.env.SM_MOCK_BILLING_KIND;
-    if (kind === 'meter_rate_limited') return { kind: 'meter_rate_limited', message: 'e2e stub', httpStatus: 429 };
-    if (kind === 'transient') return { kind: 'transient', message: 'e2e stub', httpStatus: 503 };
-    if (kind === 'auth') return { kind: 'auth', message: 'e2e stub', httpStatus: 401 };
-    // 'ok' stub returns a minimal valid payload.
-    return { kind: 'ok', data: { usage: { 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 }, subscriptionType: null, rateLimitTier: null, credentialsExpiresAt: null, fetchedAt: Date.now() } };
-  }
-
+/** The actual network round-trip, coalesced across concurrent callers below. */
+async function networkFetchUsage() {
   // Check expiry and attempt proactive refresh before touching the network.
   const refresh = await refreshIfNeeded();
   if (refresh.kind === 'auth') {
@@ -168,6 +188,7 @@ async function fetchUsage() {
   // 'ok' or 'unsupported' — creds present and not yet expired
   const creds = refresh.creds;
 
+  let result;
   let r;
   try {
     r = await fetch(USAGE_URL, {
@@ -179,59 +200,107 @@ async function fetchUsage() {
       signal: AbortSignal.timeout(10_000),
     });
   } catch (e) {
-    return { kind: 'transient', message: e.message || String(e), httpStatus: null };
+    result = { kind: 'transient', message: e.message || String(e), httpStatus: null };
   }
-  if (r.status === 401 || r.status === 403) {
-    const body = await r.text().catch(() => '');
-    const ms = expiresAtMs(creds);
-    return { kind: 'auth', message: body.slice(0, 200) || `HTTP ${r.status}`, httpStatus: r.status, expiredAt: ms };
-  }
-  if (r.status === 408 || r.status >= 500) {
-    const body = await r.text().catch(() => '');
-    return { kind: 'transient', message: body.slice(0, 200) || `HTTP ${r.status}`, httpStatus: r.status };
-  }
-  if (r.status === 429) {
-    const body = await r.text().catch(() => '');
-    let parsed = null;
-    try { parsed = JSON.parse(body); } catch { /* */ }
-    if (parsed?.error?.type === 'rate_limit_error') {
-      return { kind: 'meter_rate_limited', message: body.slice(0, 200), httpStatus: 429 };
+  if (!result) {
+    if (r.status === 401 || r.status === 403) {
+      const body = await r.text().catch(() => '');
+      const ms = expiresAtMs(creds);
+      result = { kind: 'auth', message: body.slice(0, 200) || `HTTP ${r.status}`, httpStatus: r.status, expiredAt: ms };
+    } else if (r.status === 408 || r.status >= 500) {
+      const body = await r.text().catch(() => '');
+      result = { kind: 'transient', message: body.slice(0, 200) || `HTTP ${r.status}`, httpStatus: r.status };
+    } else if (r.status === 429) {
+      const body = await r.text().catch(() => '');
+      let parsed = null;
+      try { parsed = JSON.parse(body); } catch { /* */ }
+      if (parsed?.error?.type === 'rate_limit_error') {
+        result = {
+          kind: 'meter_rate_limited',
+          message: body.slice(0, 200),
+          httpStatus: 429,
+          retryAfterMs: parseRetryAfterMs(r.headers.get('retry-after')),
+        };
+      } else {
+        result = { kind: 'transient', message: body.slice(0, 200) || 'HTTP 429', httpStatus: 429 };
+      }
+    } else if (!r.ok) {
+      const body = await r.text().catch(() => '');
+      result = { kind: 'transient', message: body.slice(0, 200) || `HTTP ${r.status}`, httpStatus: r.status };
+    } else {
+      const usage = await r.json();
+      result = {
+        kind: 'ok',
+        data: {
+          usage,
+          subscriptionType: creds.subscriptionType ?? null,
+          rateLimitTier: creds.rateLimitTier ?? null,
+          credentialsExpiresAt: creds.expiresAt ?? null,
+          fetchedAt: Date.now(),
+        },
+      };
     }
-    return { kind: 'transient', message: body.slice(0, 200) || 'HTTP 429', httpStatus: 429 };
   }
-  if (!r.ok) {
-    const body = await r.text().catch(() => '');
-    return { kind: 'transient', message: body.slice(0, 200) || `HTTP ${r.status}`, httpStatus: r.status };
+
+  if (result.kind === 'ok') {
+    cache = { data: result.data, fetchedAt: Date.now(), sourceCredsExpiresAt: result.data.credentialsExpiresAt };
+    persistCache(cache).catch(() => {});
+    retryNotBeforeMs = 0;
+    lastRateLimitedResult = null;
+    circuit.recordSuccess(result.data);
+  } else if (result.kind === 'meter_rate_limited') {
+    lastRateLimitedResult = result;
+    if (Number.isFinite(result.retryAfterMs) && result.retryAfterMs > 0) {
+      retryNotBeforeMs = Date.now() + result.retryAfterMs;
+    }
+    circuit.recordFailure(result.kind);
+  } else if (result.kind === 'transient') {
+    circuit.recordFailure(result.kind);
   }
-  const usage = await r.json();
-  return {
-    kind: 'ok',
-    data: {
-      usage,
-      subscriptionType: creds.subscriptionType ?? null,
-      rateLimitTier: creds.rateLimitTier ?? null,
-      credentialsExpiresAt: creds.expiresAt ?? null,
-      fetchedAt: Date.now(),
-    },
-  };
+  return result;
 }
 
-function registerBillingHandlers() {
-  hydrationPromise = hydrateCache();
+// Concurrent callers (the renderer's billing:fetch and the scheduler's
+// pollLoop) coalesce into this one in-flight promise instead of each firing
+// their own request against a rate-limited endpoint.
+const singleFlightNetworkFetch = singleFlight(networkFetchUsage);
 
-  ipcMain.handle('billing:fetch', async () => {
-    if (hydrationPromise) { await hydrationPromise; hydrationPromise = null; }
+/**
+ * The single owner of caching, single-flight de-duplication and Retry-After
+ * suppression for the usage meter. Every caller — renderer IPC and scheduler
+ * pollLoop alike — must go through this function rather than hitting the
+ * network or the cache file directly.
+ */
+async function fetchUsage() {
+  // Test stub: SM_MOCK_BILLING_KIND lets e2e tests simulate billing API responses
+  // without hitting the real endpoint. Only active when SM_E2E=1 to prevent
+  // accidental use in production.
+  if (process.env.SM_E2E === '1' && process.env.SM_MOCK_BILLING_KIND) {
+    const kind = process.env.SM_MOCK_BILLING_KIND;
+    if (kind === 'meter_rate_limited') return { kind: 'meter_rate_limited', message: 'e2e stub', httpStatus: 429 };
+    if (kind === 'transient') return { kind: 'transient', message: 'e2e stub', httpStatus: 503 };
+    if (kind === 'auth') return { kind: 'auth', message: 'e2e stub', httpStatus: 401 };
+    // 'ok' stub returns a minimal valid payload.
+    return { kind: 'ok', data: { usage: { 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 }, subscriptionType: null, rateLimitTier: null, credentialsExpiresAt: null, fetchedAt: Date.now() } };
+  }
 
-    if (cache && cache.fetchedAt && Date.now() - cache.fetchedAt < OK_CACHE_TTL_MS) {
-      return { kind: 'ok', data: cache.data };
-    }
+  await ensureHydrated();
 
+  if (cache && cache.fetchedAt && Date.now() - cache.fetchedAt < OK_CACHE_TTL_MS) {
+    return { kind: 'ok', data: cache.data };
+  }
+
+  if (lastRateLimitedResult && retryNotBeforeMs && Date.now() < retryNotBeforeMs) {
+    return { ...lastRateLimitedResult, suppressed: true };
+  }
+
+  return singleFlightNetworkFetch();
+}
+
+function registerBillingHandlers() {
+  ipcMain.handle('billing:fetch', async () => {
     const r = await fetchUsage();
-    if (r.kind === 'ok') {
-      cache = { data: r.data, fetchedAt: Date.now(), sourceCredsExpiresAt: r.data.credentialsExpiresAt };
-      persistCache(cache).catch(() => {});
-      return { kind: 'ok', data: r.data };
-    }
+    if (r.kind === 'ok') return { kind: 'ok', data: r.data };
     if (r.kind === 'auth') {
       if (cache) return { kind: 'auth', message: r.message, httpStatus: r.httpStatus, expiredAt: r.expiredAt, cached: cache.data, staleSince: cache.fetchedAt };
       return r;
@@ -241,11 +310,24 @@ function registerBillingHandlers() {
       return r;
     }
     if (r.kind === 'meter_rate_limited') {
-      if (cache) return { kind: 'meter_rate_limited', message: r.message, httpStatus: r.httpStatus, cached: cache.data, staleSince: cache.fetchedAt };
+      if (cache) return { kind: 'meter_rate_limited', message: r.message, httpStatus: r.httpStatus, retryAfterMs: r.retryAfterMs, suppressed: r.suppressed, cached: cache.data, staleSince: cache.fetchedAt };
       return r;
     }
     return r; // config
   });
 }
 
-module.exports = { registerBillingHandlers, fetchUsage, classifyUsageResponse, usageMeterApplicable, readClaudeSettingsAuth };
+module.exports = {
+  registerBillingHandlers,
+  fetchUsage,
+  classifyUsageResponse,
+  parseRetryAfterMs,
+  usageMeterApplicable,
+  readClaudeSettingsAuth,
+  // The single shared breaker instance — scheduler.cjs's pollLoop (and every
+  // other consumer) reads THIS object's state()/openedAt()/
+  // getConsecutiveFailures() rather than deriving its own, so a failure
+  // recorded via any path (poller, executor 429) opens the same circuit.
+  usageCircuit: circuit,
+  __usageCircuitForTest: circuit,
+};