claude-code-session-manager 0.75.2 → 0.76.0

package/src/main/lib/epicStatusMirror.cjs

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * epicStatusMirror.cjs — mirrors an Epic's lifecycle `status` onto its own
+ * durable file, `prompt-sessions/<epicId>.json`, every time a write path
+ * changes that status in `active-index.json`.
+ *
+ * Why this exists: `active-index.json` is the ONLY place an Epic's status
+ * lives today. A lost, clobbered, git-reverted, or worktree-snapshotted index
+ * silently erases every open Epic it held, with no way to recover them —
+ * `activeIndexRebuild.cjs`'s `rebuildActiveIndex` is that recovery path, and
+ * it reconstructs rows from exactly the mirror this module writes. The
+ * archive file `markCompleted()` already writes at completion (session/
+ * events/transcript/archivedAt — see prompt-sessions/README.md) is the same
+ * file this module targets; a live (proposed/active) Epic gets a sparse
+ * mirror here instead, later overwritten wholesale by the real archive.
+ *
+ * Raw fs tmp+rename — NOT config.cjs's `writeJson` — so this module stays
+ * requirable from epicMint.cjs, which is deliberately Electron-free (its own
+ * header: "so the external watchdog scripts can require it"; config.cjs
+ * requires 'electron' at module load). The write shape matches config.cjs's
+ * writeJson exactly (`JSON.stringify(data, null, 2) + '\n'`, `<path>.tmp-
+ * <pid>` then rename) so main-process callers (activeIndexMerge.cjs) and
+ * epicMint.cjs never diverge in format despite using different write paths.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { assertOpsWrite, opsPath } = require('./opsOwnership.cjs');
+
+function epicMirrorPath(cwd, epicId) {
+  return opsPath(cwd, 'prompt-sessions', `${epicId}.json`);
+}
+
+function readExistingMirror(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * mirrorEpicStatus(cwd, epicId, { session?, status?, archivedAt?, writer? })
+ * — read-merge-write onto `prompt-sessions/<epicId>.json`, preserving
+ * whatever else is already there (e.g. a full `PromptSessionArchive` written
+ * by `markCompleted`, or a prior mirror).
+ *
+ * When `session` (the full PromptSession record) is given, it is spread onto
+ * the file too — not just the four mirror fields — so a live (proposed/
+ * active) Epic's file alone is enough for `activeIndexRebuild.cjs` to
+ * reconstruct a complete `active-index.json` row, not just its status.
+ * `status`/`archivedAt` may be passed independently of `session` (or to
+ * override `session.status`) for callers that only know the status.
+ *
+ * Never throws on a read failure (a missing/corrupt existing file is treated
+ * as "start fresh"); a write failure propagates, matching every other atomic
+ * writer in this codebase (config.cjs's writeTextAtomic, epicMint.cjs's own
+ * writeActiveIndex).
+ */
+function mirrorEpicStatus(cwd, epicId, { session = null, status = null, archivedAt = null, writer = 'epics' } = {}) {
+  const resolvedStatus = status || (session && session.status) || null;
+  if (!cwd || !epicId || !resolvedStatus) return;
+  const file = epicMirrorPath(cwd, epicId);
+  assertOpsWrite(file, writer);
+  const existing = readExistingMirror(file);
+  const merged = {
+    ...existing,
+    ...(session || {}),
+    id: epicId,
+    cwd,
+    status: resolvedStatus,
+    archivedAt: archivedAt ?? existing.archivedAt ?? null,
+    indexedAt: new Date().toISOString(),
+  };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(merged, null, 2) + '\n');
+  fs.renameSync(tmp, file);
+}
+
+/**
+ * removeEpicMirror(cwd, epicId) — best-effort delete of the mirror file, used
+ * only by epicMint.cjs's removeEpic() rollback (undoing a mint whose caller
+ * failed to complete its own work). Never throws — a missing file is a no-op.
+ */
+function removeEpicMirror(cwd, epicId) {
+  if (!cwd || !epicId) return;
+  try {
+    fs.unlinkSync(epicMirrorPath(cwd, epicId));
+  } catch { /* never existed, or already gone */ }
+}
+
+module.exports = { mirrorEpicStatus, removeEpicMirror, epicMirrorPath };

package/src/main/lib/epicValidationHook.cjs

@@ -62,7 +62,8 @@ function pairKey(epicId, prdSlug) {
  */
 function defaultReadActiveIndex(cwd) {
   try {
-    const p = path.join(cwd, 'session-manager-operations', 'prompt-sessions', 'active-index.json');
+    const { opsPath } = require('./opsOwnership.cjs');
+    const p = opsPath(cwd, 'prompt-sessions', 'active-index.json');
     return JSON.parse(fs.readFileSync(p, 'utf8'));
   } catch {
     return null;

package/src/main/lib/gitWorktree.cjs

@@ -157,10 +157,21 @@ async function isGitRepo(cwd) {
   }
 }
 
-/** True when `cwd`'s own working tree (not any worktree) has zero pending changes. */
+/**
+ * True when `cwd`'s own working tree (not any worktree) has zero pending
+ * changes to TRACKED files (modified or staged). Untracked files are
+ * deliberately excluded (`--untracked-files=no`): an untracked file is never
+ * tracked WIP a job depends on, and `git worktree add` checks out only
+ * committed HEAD content into the new worktree — it never touches, copies, or
+ * is affected by the base tree's untracked files either way. Counting them as
+ * "dirty" here bought no safety: one stray scratch file in a project silently
+ * disabled isolation for every job in that project, permanently, since a
+ * failed-to-commit job leaves the tree dirty and re-triggers the same
+ * fallback for every subsequent job (RCA: PRD 1064, starry-night-ships).
+ */
 async function isBaseTreeClean(cwd) {
   try {
-    const out = await execGit(['status', '--porcelain'], { cwd, timeout: 10_000 });
+    const out = await execGit(['status', '--porcelain', '--untracked-files=no'], { cwd, timeout: 10_000 });
     return out.trim().length === 0;
   } catch {
     return false;
@@ -316,6 +327,44 @@ async function cleanupWorktree({ kind, cwd, dir, branch, keepBranch }) {
   activeWorktreeCount[kind] = Math.max(0, activeWorktreeCount[kind] - 1);
 }
 
+/**
+ * Best-effort dump of a worktree's full outstanding diff (tracked
+ * modifications AND untracked files) to `outFile`, for a caller about to
+ * tear the worktree down. A job killed before its finish-protocol commit
+ * (rate limit, timeout, crash, hard kill) otherwise loses that work
+ * outright the moment `cleanupWorktree` removes the checkout — no branch,
+ * no stash, no patch survives it. `git add -A --intent-to-add` stages
+ * untracked paths (empty blobs) without touching their content, so the
+ * subsequent `git diff HEAD --binary` includes their full contents exactly
+ * like a tracked modification; the result is a patch a later `git apply`
+ * can consume verbatim.
+ *
+ * Never throws — this always runs immediately before teardown and must
+ * never block branch integration/cleanup or change a job's verdict. Writes
+ * nothing (and returns `{ ok: false }`) when the worktree is clean or on
+ * any git failure, so a successful run's teardown never leaves a 0-byte
+ * artifact behind.
+ */
+async function salvageWorktreeDiff({ cwd, outFile }) {
+  try {
+    const status = await execGit(['status', '--porcelain'], { cwd, timeout: 15_000 });
+    if (!status.trim()) return { ok: false };
+    try {
+      await execGit(['add', '-A', '--intent-to-add'], { cwd, timeout: 30_000 });
+    } catch {
+      // Best-effort — the diff below still captures whatever staged/tracked
+      // changes exist even if intent-to-add partially failed.
+    }
+    const patch = await execGit(['diff', 'HEAD', '--binary'], { cwd, timeout: 30_000 });
+    if (!patch || !patch.trim()) return { ok: false };
+    const { writeTextAtomic } = require('../config.cjs');
+    await writeTextAtomic(outFile, patch);
+    return { ok: true, bytes: Buffer.byteLength(patch, 'utf8') };
+  } catch {
+    return { ok: false };
+  }
+}
+
 /** Parse `git worktree list --porcelain` into `[{ worktree, branch }]`. */
 function parseWorktreeListPorcelain(text) {
   const entries = [];
@@ -399,6 +448,9 @@ async function integrateJobBranch({ cwd, branch, slug }) {
 async function cleanupJobWorktree({ cwd, dir, branch, keepBranch }) {
   return cleanupWorktree({ kind: 'job', cwd, dir, branch, keepBranch });
 }
+async function salvageJobWorktreeDiff({ dir, outFile }) {
+  return salvageWorktreeDiff({ cwd: dir, outFile });
+}
 
 async function createEpicWorktree({ cwd, epicId }) {
   return createWorktree({ kind: 'epic', cwd, key: epicId });
@@ -423,6 +475,7 @@ module.exports = {
   createWorktree,
   integrateBranch,
   cleanupWorktree,
+  salvageWorktreeDiff,
   parseWorktreeListPorcelain,
   reconcileWorktreesOnBoot,
   // Job-kind convenience wrappers — same call shape jobWorktree.cjs has
@@ -430,6 +483,7 @@ module.exports = {
   createJobWorktree,
   integrateJobBranch,
   cleanupJobWorktree,
+  salvageJobWorktreeDiff,
   // Epic-kind convenience wrappers.
   createEpicWorktree,
   integrateEpicBranch,

package/src/main/lib/jobWorktree.cjs

@@ -62,6 +62,7 @@ module.exports = {
   createJobWorktree: gitWorktree.createJobWorktree,
   integrateJobBranch: gitWorktree.integrateJobBranch,
   cleanupJobWorktree: gitWorktree.cleanupJobWorktree,
+  salvageJobWorktreeDiff: gitWorktree.salvageJobWorktreeDiff,
   parseWorktreeListPorcelain: gitWorktree.parseWorktreeListPorcelain,
   reconcileWorktreesOnBoot: (cwds) => gitWorktree.reconcileWorktreesOnBoot(cwds, { kind: KIND }),
   // Test-only escape hatch for the in-memory concurrency counter.

package/src/main/lib/loadGate.cjs

@@ -0,0 +1,134 @@
+'use strict';
+
+/**
+ * loadGate.cjs — CPU-load launch gate for the scheduler (PRD 1085).
+ *
+ * The scheduler already gates launches on free memory (scheduler.cjs's
+ * memoryLimitedBatchSize) and on a static per-project cap
+ * (schedulerConfig.projectJobCap). Neither sees CPU. Observed 2026-09-01 on
+ * starry-night-ships: 4 concurrent executors each running a Godot test
+ * battery under its own Xvfb, loadavg 12.95 on 14 cores. Under that
+ * contention every 8-minute battery stretches, executors hit their own
+ * `timeout`, the verifier files FAIL/FATAL → needs_review → an auto-fix
+ * chain with inflated estimates launches MORE batteries. A static cap cannot
+ * see that feedback loop; the 1-minute load average can.
+ *
+ * Gate ordering at the call site (scheduler.cjs tickQueue):
+ *   global sessionSlots pool → per-project cap → memory → LOAD (innermost).
+ * This is one more predicate inside the existing pick path — never a second
+ * pool, and it only WITHHOLDS launches; running jobs are never touched.
+ *
+ * Everything here is pure and injectable (`loadavg`, `cores`, `now`) so the
+ * decision, the audit rate-limit and the escalation are unit-testable without
+ * real load or a fake clock hack on `Date`.
+ */
+
+const os = require('node:os');
+const { execFileSync } = require('node:child_process');
+const { loadGateThreshold, JOB_OVERRUN_FLOOR_MS } = require('./schedulerConfig.cjs');
+
+// One audit row per this interval while continuously gated — the poll loop
+// ticks every 60 s and a saturated box stays saturated for a while; auditing
+// every tick would bury the signal in its own noise.
+const AUDIT_INTERVAL_MS = 10 * 60_000;
+
+/**
+ * isLoadGated(loadavg1, cores, threshold) → boolean
+ *
+ * True when the 1-minute load average per core exceeds `threshold`. The 5-
+ * and 15-minute averages are deliberately NOT consulted: a finished battery
+ * should free launches within a minute or two, not a quarter hour. A
+ * threshold of 0 (or anything non-positive) disables the gate. Zero/unknown
+ * cores never gates (os.cpus() can be empty in some containers).
+ */
+function isLoadGated(loadavg1, cores, threshold) {
+  if (!(threshold > 0)) return false;
+  if (!(cores > 0)) return false;
+  if (!Number.isFinite(loadavg1) || loadavg1 <= 0) return false; // [0,0,0] on Windows/unsupported
+  return loadavg1 / cores > threshold;
+}
+
+/** Best-effort top-N CPU consumers (Linux only). Returns [] anywhere else or on error. */
+function topCpuConsumers(n = 3) {
+  if (process.platform !== 'linux') return [];
+  try {
+    const out = execFileSync('ps', ['-eo', 'pid,pcpu,comm', '--sort=-pcpu'], { encoding: 'utf8', timeout: 2000 });
+    return out.split('\n').slice(1, 1 + n).map((l) => l.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * createLoadGate(opts) → { evaluate, snapshot }
+ *
+ * Holds the small amount of state the gate needs across ticks (when it was
+ * last audited, when the current gated stretch began). `evaluate({ bypass })`
+ * returns the decision for THIS tick:
+ *   { gated, ratio, threshold, loadavg1, cores, bypassed,
+ *     shouldAudit, escalate, gatedSinceMs }
+ * - shouldAudit: true at most once per AUDIT_INTERVAL_MS while gated.
+ * - escalate: true once the current gated stretch exceeds JOB_OVERRUN_FLOOR_MS
+ *   (45 min by default) — the caller warn-logs with topCpuConsumers().
+ * - bypassed: `bypass` was set (an explicit human Run now) and the gate would
+ *   otherwise have held; the caller launches anyway and logs that it did.
+ *
+ * `snapshot()` is what buildScheduleStatePayload exposes as `loadGate`.
+ */
+function createLoadGate({
+  loadavg = () => os.loadavg(),
+  cores = () => (os.cpus() || []).length,
+  now = () => Date.now(),
+  threshold = loadGateThreshold,
+  auditIntervalMs = AUDIT_INTERVAL_MS,
+  escalateAfterMs = JOB_OVERRUN_FLOOR_MS,
+} = {}) {
+  let lastAuditAt = null; // null = never audited; the first gated tick always audits
+  let gatedSince = null;
+  let last = null;
+
+  function evaluate({ bypass = false } = {}) {
+    const t = now();
+    const [l1] = loadavg();
+    const c = cores();
+    const th = typeof threshold === 'function' ? threshold() : threshold;
+    const ratio = c > 0 && Number.isFinite(l1) ? l1 / c : 0;
+    const wouldGate = isLoadGated(l1, c, th);
+
+    if (wouldGate) {
+      if (gatedSince === null) gatedSince = t;
+    } else {
+      gatedSince = null;
+    }
+    const gated = wouldGate && !bypass;
+    const bypassed = wouldGate && bypass;
+
+    let shouldAudit = false;
+    if (gated && (lastAuditAt === null || t - lastAuditAt >= auditIntervalMs)) {
+      shouldAudit = true;
+      lastAuditAt = t;
+    }
+    const gatedSinceMs = gatedSince === null ? 0 : t - gatedSince;
+    const escalate = gated && gatedSinceMs >= escalateAfterMs;
+
+    last = {
+      gated,
+      bypassed,
+      ratio: Number(ratio.toFixed(3)),
+      threshold: th,
+      loadavg1: Number.isFinite(l1) ? Number(l1.toFixed(2)) : null,
+      cores: c,
+      gatedSinceMs,
+      at: new Date(t).toISOString(),
+    };
+    return { ...last, shouldAudit, escalate };
+  }
+
+  function snapshot() {
+    return last;
+  }
+
+  return { evaluate, snapshot };
+}
+
+module.exports = { isLoadGated, createLoadGate, topCpuConsumers, AUDIT_INTERVAL_MS };

package/src/main/lib/mcpToolCatalog.cjs

@@ -0,0 +1,285 @@
+/**
+ * mcpToolCatalog.cjs — single source of truth for what every
+ * session-manager-scheduler MCP tool does, when to reach for it, and when
+ * NOT to. Before this file, that knowledge lived only inside hand-written
+ * `description` strings in scripts/scheduler-mcp-server.cjs's TOOLS array —
+ * invisible to the app, the Home tab, the manual, and to a human debugging
+ * why a session went off-piste. scheduler-mcp-server.cjs now BUILDS each
+ * tool's live `description` from this catalog via composeDescription(), so
+ * the two can never drift.
+ *
+ * Plain CJS, no Electron dependency — requirable from both the main process
+ * and the standalone `node scripts/scheduler-mcp-server.cjs` process, same
+ * constraint workTypeLibrary.cjs already satisfies (see that file's header).
+ *
+ * Composition rule (also asserted in mcpToolCatalog.test.cjs): a tool's live
+ * description is `[purpose, whenToUse, whenNotToUse, notes].filter(Boolean)
+ * .join(' ')` — deterministic, so a catalog edit provably reaches the live
+ * MCP tool list with no separate hand-edit required.
+ */
+'use strict';
+
+const { z } = require('zod');
+
+const CatalogEntrySchema = z.object({
+  name: z.string().min(1),
+  group: z.enum(['scheduler', 'chat', 'feedback', 'help']),
+  purpose: z.string().min(1),
+  whenToUse: z.string().min(1),
+  whenNotToUse: z.string().min(1),
+  exampleArgs: z.record(z.string(), z.unknown()),
+  notes: z.string().nullable(),
+});
+
+const RecipeSchema = z.object({
+  id: z.string().min(1),
+  title: z.string().min(1),
+  steps: z.array(z.string().min(1)).min(1),
+});
+
+const MCP_TOOL_CATALOG = [
+  {
+    name: 'scheduler_reset_job',
+    group: 'scheduler',
+    purpose: "Reset a stuck scheduler job by slug via the session-manager app's admin API.",
+    whenToUse: 'Use after diagnosing why a job is stuck (e.g. via scheduler_get_prd/scheduler_list_jobs) and deciding it should re-run from pending.',
+    whenNotToUse: 'Do not use as a first move on a "needs_review" job without reading it first — reset just clears status, it does not answer the question the job raised.',
+    exampleArgs: { slug: 'add-mcp-tool-catalog', force: false },
+    notes: 'Refuses a job whose status is already "completed" unless force:true is passed — resetting a completed job re-executes already-shipped work.',
+  },
+  {
+    name: 'scheduler_list_jobs',
+    group: 'scheduler',
+    purpose: "List scheduler jobs via the session-manager app's admin API.",
+    whenToUse: 'Use for a quick overview of live queue-row status (pending/running/completed/failed/needs_review) across the machine.',
+    whenNotToUse: 'For PRD content (frontmatter/body) rather than just job status, or for filtering by cwd/Epic, use scheduler_list_prds instead.',
+    exampleArgs: {},
+    notes: null,
+  },
+  {
+    name: 'scheduler_create_prd',
+    group: 'scheduler',
+    purpose: 'THE ONLY SANCTIONED WAY to author a PRD. Write a new PRD file via the '
+      + "session-manager app's admin API. Server-side validates the frontmatter, "
+      + 'atomically allocates the NN parallel-group number, appends the engineering '
+      + 'standards, and writes the PRD file to disk. This tool ONLY writes the file — '
+      + 'it does not create a scheduler queue row. The queue row is derived '
+      + "automatically by the scheduler's next reconcile pass (typically within ~1 "
+      + 'minute); the response has `enqueued: false` for exactly this reason. Every PRD '
+      + 'must join an EXISTING, already-human-approved Epic (pass sourcePromptId) — this '
+      + 'tool never mints a new one, and refuses the write if no Epic can be resolved. '
+      + '`cwd` is OPTIONAL when called from inside an Epic session (chat or terminal, '
+      + 'including from inside that Epic\'s own git worktree pwd): the server resolves '
+      + 'the real project from the calling session\'s sourcePromptId/originClaudeSessionId, '
+      + 'never from a worktree\'s own possibly-stale active-index.json snapshot.',
+    whenToUse: 'Use whenever new work should be queued into an already-approved Epic — this is the /develop path.',
+    whenNotToUse: 'TWO DISTINCT FAILURE MODES if this tool is not usable — do not conflate them: '
+      + '(a) this tool call is PRESENT in your tool list but ERRORS as app-not-running / admin '
+      + 'API unreachable — that is the ONLY case where hand-authoring the PRD file directly on '
+      + 'disk is an acceptable DEGRADED, LAST-RESORT fallback; the caller MUST say so explicitly '
+      + 'and visibly in its report (which file, why the tool was unreachable, that it needs '
+      + 'verification) since the server-side validation, atomic NN allocation, and '
+      + 'Epic-existence check this tool performs did not run for that file. '
+      + '(b) this tool is ABSENT from your tool list entirely — you were never offered it, so '
+      + 'there is no error to catch. That means the session-manager-scheduler MCP server is not '
+      + 'registered for this project: a MISCONFIGURATION, not an offline app. In that case DO '
+      + 'NOT hand-write any PRD file — stop and tell the human the MCP server is not registered '
+      + '(fix: `claude mcp add session-manager-scheduler --scope user -- node '
+      + '<session-manager-repo>/scripts/scheduler-mcp-server.cjs`, once at user scope covers '
+      + 'every project).',
+    exampleArgs: {
+      title: 'Add unit tests for the retry backoff helper',
+      cwd: '/home/bilko/Projects/session-manager',
+      estimateMinutes: 30,
+      goal: 'Cover retryWithBackoff.cjs edge cases (zero retries, max-delay clamp) that currently have no test.',
+      acceptanceCriteria: ['New test file exercises zero-retry and max-delay-clamp cases', 'timeout 300 npm run typecheck passes', 'timeout 600 npm run test:unit passes'],
+      implementationNotes: 'See src/main/lib/retryWithBackoff.cjs and its existing __tests__ sibling for the pattern to extend.',
+      sourcePromptId: 'epic-id-of-an-already-approved-session',
+    },
+    notes: 'See /develop.',
+  },
+  {
+    name: 'scheduler_list_prds',
+    group: 'scheduler',
+    purpose: "THE ONLY SUPPORTED WAY to list scheduled PRDs (live + archived) via the session-manager app's admin API. "
+      + 'Each entry includes its real job status (pending/running/completed/failed/needs_review, or null if not yet '
+      + 'queued/reconciled). Optionally filter by project cwd, Epic id, and/or status. Results are paginated (default '
+      + 'limit 100, max 500) sorted by slug ascending — check `hasMore`/`total` in the response before assuming you '
+      + "received every PRD; page further with `offset`. Default fields are compact (no parallelGroup/estimateMinutes/"
+      + 'sourcePromptId/epicId/archivedStatus) — pass fields:"full" to restore them.',
+    whenToUse: 'Use to survey PRDs by project/Epic/status before deciding which one to read, update, reset, or archive.',
+    whenNotToUse: 'Do not assume a page without `hasMore` is the full result set without checking `total` — page further with `offset` first.',
+    exampleArgs: { cwd: '/home/bilko/Projects/session-manager', status: 'needs_review' },
+    notes: null,
+  },
+  {
+    name: 'scheduler_get_prd',
+    group: 'scheduler',
+    purpose: "THE ONLY SUPPORTED WAY to read one PRD's full body + parsed frontmatter (live or archived) via the "
+      + "session-manager app's admin API.",
+    whenToUse: 'Use before editing/resetting a PRD, or to answer what a needs_review job actually asked.',
+    whenNotToUse: 'For a fleet-wide overview instead of one PRD, use scheduler_list_prds.',
+    exampleArgs: { slug: 'add-mcp-tool-catalog' },
+    notes: null,
+  },
+  {
+    name: 'scheduler_update_prd',
+    group: 'scheduler',
+    purpose: "THE ONLY SUPPORTED WAY to edit a NOT-yet-running PRD's frontmatter and/or body via the session-manager "
+      + 'app\'s admin API. Refuses once a queue row exists for the slug and its status is anything but "pending" '
+      + '(running/completed/failed/needs_review) — editing the spec under a live or already-finished executor is refused, '
+      + 'not silently applied. Only recognized frontmatter keys (title, cwd, estimateMinutes, parallelGroup, '
+      + 'sourcePromptId, sourceTabId, tag) may be patched; unrecognized keys (e.g. dependsOn) round-trip unchanged.',
+    whenToUse: 'Use to correct a PRD scope/estimate/tag before it starts running — e.g. before resetting a needs_review job whose spec needs to change.',
+    whenNotToUse: 'Do not use once the job is running or terminal (completed/failed/needs_review) without first resetting it back to pending — the route refuses the edit.',
+    exampleArgs: { slug: 'add-mcp-tool-catalog', frontmatter: { estimateMinutes: 45 } },
+    notes: null,
+  },
+  {
+    name: 'scheduler_archive_prd',
+    group: 'scheduler',
+    purpose: "THE ONLY SUPPORTED WAY to archive one or more PRDs (move to prds-archived/) via the session-manager "
+      + "app's admin API.",
+    whenToUse: 'Use once a batch of PRDs is done and should stop showing up in default (live) listings.',
+    whenNotToUse: 'Do not archive a PRD you still expect to reset/re-run — archived PRDs are not part of the live scheduling loop.',
+    exampleArgs: { slugs: ['add-mcp-tool-catalog'] },
+    notes: null,
+  },
+  {
+    name: 'scheduler_cancel_job',
+    group: 'scheduler',
+    purpose: "THE ONLY SUPPORTED WAY to cancel a not-yet-terminal scheduler job via the session-manager app's admin "
+      + 'API. A running job is SIGTERM\'d; a pending job is simply retired. There is no "cancelled" job status, so a '
+      + 'cancelled job lands as "failed" with an error naming the cause. Refuses a slug whose job is already terminal '
+      + '(completed/failed/needs_review) — nothing to cancel.',
+    whenToUse: 'Use to stop a running or pending job that should not continue (e.g. it was queued in error, or scope changed underneath it).',
+    whenNotToUse: 'Do not use on an already-terminal job (completed/failed/needs_review) — use scheduler_reset_job if it should run again.',
+    exampleArgs: { slug: 'add-mcp-tool-catalog' },
+    notes: null,
+  },
+  {
+    name: 'scheduler_retag_prd',
+    group: 'scheduler',
+    purpose: "THE ONLY SUPPORTED WAY to rewrite a PRD's parallelGroup and/or estimateMinutes frontmatter (and, if "
+      + "parallelGroup changes, its NN- filename prefix) via the session-manager app's admin API.",
+    whenToUse: 'Use to correct an estimate or renumber a PRD file after it was created.',
+    whenNotToUse: 'Do not use parallelGroup as an ordering/dependency barrier — it is only a unique-per-PRD display hint; use dependsOn on scheduler_create_prd/scheduler_update_prd for real ordering.',
+    exampleArgs: { items: [{ slug: 'add-mcp-tool-catalog', estimateMinutes: 30 }] },
+    notes: null,
+  },
+  {
+    name: 'chat_send_prompt',
+    group: 'chat',
+    purpose: "Push a prompt into an already-open tab's chat queue via the session-manager app's admin "
+      + 'API. The renderer resolves the tab (must currently be open) and runs the prompt through '
+      + 'the same queued-vs-immediate path as a manual send.',
+    whenToUse: 'Use to programmatically continue a conversation in a tab that is already open in the running app.',
+    whenNotToUse: 'Do not use to start new work in a project you are not already chatting in — that is /develop (scheduler_create_prd) or feedback_open_session.',
+    exampleArgs: { tabId: 'a1b2c3d4-tab-id', prompt: 'Please continue with the next step.' },
+    notes: 'No-ops if the tab is unknown/closed.',
+  },
+  {
+    name: 'feedback_list_projects',
+    group: 'feedback',
+    purpose: 'List the OTHER projects on this machine that can receive feedback (i.e. that Session Manager '
+      + 'already manages — they have a session-manager-operations/ directory).',
+    whenToUse: "Call this FIRST when you need the exact `toCwd` for feedback_open_session and are not certain of it — never guess a path.",
+    whenNotToUse: 'A project missing from this list has simply never been opened in Session Manager; ask the human to open it once rather than inventing a path.',
+    exampleArgs: {},
+    notes: null,
+  },
+  {
+    name: 'feedback_open_session',
+    group: 'feedback',
+    purpose: 'THE ONLY SANCTIONED WAY to hand a finding from THIS project to a DIFFERENT project. Opens a new '
+      + "PROPOSED session in the receiving project's own Sessions queue, carrying your report as its "
+      + 'opening prompt and stamped with where it came from. Session Manager performs the cross-folder '
+      + 'write; you never write another project\'s files yourself.',
+    whenToUse: 'Use when work in this project surfaces something that is genuinely another project\'s to fix. '
+      + 'Write the report for a reader who has never seen your project: state the symptom, where you '
+      + 'observed it, what you expected, and (if you know) the file in THEIR repo that looks responsible. '
+      + 'Never assume they can see your code.',
+    whenNotToUse: 'WHEN NOT TO USE IT: for work in the project you are ALREADY in, run /develop inside the Epic you '
+      + 'are already in — this tool refuses toCwd === fromCwd outright.',
+    exampleArgs: {
+      toCwd: '/home/bilko/Projects/other-project',
+      fromCwd: '/home/bilko/Projects/session-manager',
+      title: 'Cross-project contract mismatch in the shared admin API',
+      body: 'Symptom: X. Observed while doing Y in session-manager. Expected: Z. Suspected file: <path in their repo>.',
+    },
+    notes: 'WHAT THIS DOES NOT DO: it does not start anything, queue a PRD, or spend a token. The session '
+      + 'lands as `proposed` and runs only if a human in the RECEIVING project presses "Approve & start". '
+      + 'There is no callback and no reply channel — do not wait for an answer, and do not tell the user '
+      + 'the other project has "been fixed" or "is working on it". Report only that the proposal was '
+      + 'delivered.',
+  },
+  {
+    name: 'session_manager_help',
+    group: 'help',
+    purpose: 'THE ENTRY POINT — call this tool FIRST whenever you are unsure which session-manager-scheduler '
+      + 'tool to reach for, or a call to this server just failed. Returns the same tool catalog every other '
+      + "tool's description is composed from, this project's multi-tool recipes, and this machine's "
+      + 'delegation-readiness state (tells apart "not registered", "registered but dead" — the process '
+      + 'won\'t even answer tools/list — and "registered and answering").',
+    whenToUse: 'Call with no arguments for the full grouped tool list plus recipe titles. Pass `tool` (a tool '
+      + 'name) for that one tool\'s full entry, including its exampleArgs. Pass `topic` (a recipe id) for that '
+      + 'recipe\'s step-by-step instructions. Pass both to get both sections in one call.',
+    whenNotToUse: 'Do not use this to actually perform scheduler/chat/feedback work — it is read-only '
+      + "documentation and never a substitute for calling the tool it describes.",
+    exampleArgs: {},
+    notes: 'Always returns the static catalog even when the session-manager app is not running — only the '
+      + '`readiness` section of the response depends on the admin API being reachable.',
+  },
+];
+
+const MCP_RECIPES = [
+  {
+    id: 'queue-work-via-develop',
+    title: 'Queue work into an already-approved Epic (/develop)',
+    steps: [
+      'Confirm an Epic already exists for this work (proposed or active) — scheduler_create_prd never mints one.',
+      'Call scheduler_create_prd with sourcePromptId set to that Epic id, plus title/cwd/estimateMinutes/goal/acceptanceCriteria/implementationNotes.',
+      'The response has enqueued:false — the queue row is derived by the scheduler\'s next reconcile pass (~1 minute), not by this call.',
+      'Optionally call scheduler_list_prds with cwd/status to confirm the PRD picked up a job row.',
+    ],
+  },
+  {
+    id: 'unstick-needs-review-job',
+    title: 'Unstick a job stuck in needs_review',
+    steps: [
+      'Call scheduler_list_prds with status:"needs_review" (or scheduler_list_jobs) to find the stuck slug.',
+      'Call scheduler_get_prd with that slug to read its full frontmatter + body and understand the question it raised.',
+      'If the PRD spec needs to change, call scheduler_update_prd with the slug and a frontmatter/body patch — this is only accepted while the job is not yet running or terminal.',
+      'Call scheduler_reset_job with { slug } to clear the needs_review status back to pending — force is only required if the job had already reached "completed".',
+      'The next scheduler reconcile pass re-queues the job; confirm with scheduler_list_jobs or scheduler_list_prds.',
+    ],
+  },
+  {
+    id: 'hand-finding-to-another-project',
+    title: 'Hand a finding to another project',
+    steps: [
+      'Call feedback_list_projects to get the exact toCwd for the receiving project — never guess a path.',
+      'Call feedback_open_session with toCwd, fromCwd, a one-line title, and a self-contained body (symptom, where observed, expected behavior, suspected cause).',
+      'The call only delivers a PROPOSED session in the receiving project — nothing runs until a human there presses Approve & start; there is no reply channel.',
+    ],
+  },
+];
+
+for (const entry of MCP_TOOL_CATALOG) {
+  CatalogEntrySchema.parse(entry);
+}
+for (const recipe of MCP_RECIPES) {
+  RecipeSchema.parse(recipe);
+}
+
+function composeDescription(entry) {
+  return [entry.purpose, entry.whenToUse, entry.whenNotToUse, entry.notes].filter(Boolean).join(' ');
+}
+
+module.exports = {
+  MCP_TOOL_CATALOG,
+  MCP_RECIPES,
+  CatalogEntrySchema,
+  RecipeSchema,
+  composeDescription,
+};

package/src/main/lib/opsErrorLog.cjs

@@ -14,6 +14,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { assertOpsWrite } = require('./opsOwnership.cjs');
+const { isEphemeralCwd } = require('./ephemeralCwd.cjs');
 
 // Same redaction policy as logs.cjs's sanitizeMeta — kept independent (not
 // shared/required) so this module has no dependency on the Electron `app`
@@ -31,7 +32,8 @@ function sanitizeMeta(meta) {
 }
 
 function logsDir(cwd) {
-  return path.join(cwd, 'session-manager-operations', 'logs');
+  const { opsPath } = require('./opsOwnership.cjs');
+  return opsPath(cwd, 'logs');
 }
 
 function todayFile(cwd) {
@@ -58,6 +60,15 @@ function todayFile(cwd) {
  */
 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
+  if (isEphemeralCwd(cwd)) {
+    // A worktree is torn down when its Epic/job ends and os.tmpdir() is
+    // scratch space either way — never materialize logs there. See
+    // ephemeralCwd.cjs / queueStore.cjs's projectStateDir for the sibling
+    // refusal on the scheduler namespace (verified live 2026-09-01 as a
+    // recreated /tmp/session-manager-operations/logs/ tree).
+    console.warn(`[opsErrorLog] appendError: refusing ephemeral cwd "${cwd}" (scope=${scope || 'unknown'})`);
+    return;
+  }
   const file = todayFile(cwd);
   try {
     assertOpsWrite(file, 'logs');