claude-code-session-manager 0.86.0 → 0.87.0

package/src/main/lib/effectiveModelInfo.cjs

@@ -0,0 +1,333 @@
+'use strict';
+
+/**
+ * effectiveModelInfo.cjs — read-only observer answering "what will this
+ * Epic's agentType actually run as": the persona's model alias, the
+ * concrete model id evidence points at, and the provenance of each. Sits
+ * BESIDE agentModelResolve.cjs (which decides what a launch actually passes
+ * to `--model`) rather than replacing it — nothing here feeds a spawn
+ * decision, and agentModelResolve.cjs's own resolution is unchanged.
+ *
+ * Provenance is the entire point: a caller must be able to tell "we KNOW
+ * this alias last ran as claude-opus-5 because a real run resolved it" from
+ * "we don't know; the CLI resolves this alias at launch." The two must
+ * never collapse into one optimistic string.
+ *
+ * Effort-level resolution is deliberately NOT here — it already exists,
+ * unused, in the renderer's `useEffectiveSettings.ts` (a scope-chain reader
+ * with a file watcher). This module supplies only the half that genuinely
+ * needs main-process filesystem access: persona lookup (overlay-aware) and
+ * concrete-model evidence (scheduler run logs, session transcripts).
+ *
+ * Never throws — every lookup failure degrades a field to null, same
+ * contract as agentModelResolve.cjs's resolveEpicModel.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { splitFrontmatter } = require('./prdFrontmatter.cjs');
+const { encodeCwd } = require('./encodeCwd.cjs');
+
+// Mirrors rawSessionModel.ts's RAW_MODELS — duplicated rather than imported
+// because that file is a renderer ES module and this is a main-process CJS
+// module (CLAUDE.md: "No CommonJS in renderer, no ES modules in main").
+// Anything NOT in this set is treated as an already-concrete pinned model id
+// (e.g. 'claude-opus-5'), never as an alias needing evidence.
+const KNOWN_MODEL_ALIASES = new Set(['opus', 'sonnet', 'haiku', 'fable']);
+
+// Run-log evidence (scheduler.cjs's executeJob, ~line 4473) is written
+// essentially at dispatch time, before any of the run's own stdout streams
+// in — so a bounded HEAD read (not a tail) is both correct and cheap even
+// against a run log that grows to tens of MB. O(min(size, cap)) time/space.
+const MAX_RUN_LOG_HEAD_BYTES = 64 * 1024;
+
+// Same bound epicDelegationStats.cjs's readTranscriptTail uses for a single
+// pass over a transcript that can reach tens of MB. O(min(size, cap)).
+const MAX_TRANSCRIPT_TAIL_BYTES = 8 * 1024 * 1024;
+
+// Mirrors scheduler.cjs's own ROOT/RUNS_DIR constants (same convention as
+// queueStore.cjs's LEGACY_QUEUE_PATH, which duplicates this literal rather
+// than requiring scheduler.cjs's ~530KB module graph for one path).
+function runsDir(homeDir) {
+  return path.join(homeDir, '.claude', 'session-manager', 'scheduled-plans', 'runs');
+}
+
+function isConcreteModelId(modelAlias) {
+  return Boolean(modelAlias) && !KNOWN_MODEL_ALIASES.has(modelAlias);
+}
+
+/**
+ * True when this app's spawn path (cleanEnv.cjs's cleanChildEnv) would strip
+ * an effort env var before a child ever saw it — i.e. whether the settings
+ * schema's env-var effort configuration path is actually reachable for an
+ * app-launched session. Derived by probing cleanChildEnv itself rather than
+ * hardcoding a boolean, so this self-corrects if that deletion list ever
+ * changes instead of silently drifting stale.
+ */
+function computeEffortReachable(deps) {
+  try {
+    const { cleanChildEnv } = deps.cleanEnv || require('./cleanEnv.cjs');
+    const probe = cleanChildEnv({ CLAUDE_EFFORT: 'high', CLAUDE_CODE_EFFORT_LEVEL: 'high' });
+    return Boolean(probe.CLAUDE_EFFORT || probe.CLAUDE_CODE_EFFORT_LEVEL);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolves a persona's model alias, overlay-aware (agentLibrary.cjs's
+ * getPersonaBody: project overlay at `<cwd>/.claude/agents/<name>.md` wins
+ * over the global `~/.claude/agents/<name>.md` — the same precedence
+ * `resolvePrdPersonaForSpawn` already uses, unlike `listPersonas`/
+ * `readPersonaModel`, which only ever see the global directory).
+ *
+ * Never throws: a missing/unreadable persona (dangling agentType) resolves
+ * to `{ modelAlias: null, modelSource: 'fallback' }` without logging —
+ * agentModelResolve.cjs's own `logDanglingPersonaOnce`/`reportDanglingAgentTypeOnce`
+ * dedup-per-(cwd,agentType) already covers that diagnostic on the LAUNCH
+ * path; this read-only observer deliberately does not add a second logger
+ * for the same dangling reference.
+ */
+async function resolvePersonaModelAlias(cwd, agentType, deps) {
+  const getPersonaBody = deps.getPersonaBody || require('../agentLibrary.cjs').getPersonaBody;
+  const resolvePersonaPaths = deps.resolvePersonaPaths || require('./epicMint.cjs').resolvePersonaPaths;
+
+  let persona;
+  try {
+    persona = await getPersonaBody({ cwd, name: agentType });
+  } catch {
+    persona = null;
+  }
+  if (!persona) return { modelAlias: null, modelSource: 'fallback' };
+
+  const { fm } = splitFrontmatter(persona.text);
+
+  let fromOverlay = false;
+  try {
+    const { projectPath } = resolvePersonaPaths(cwd, agentType);
+    fromOverlay = Boolean(projectPath) && path.resolve(projectPath) === path.resolve(persona.path);
+  } catch {
+    // Best-effort overlay signal only — a resolution failure here just means
+    // "assume global", never a reason to fail the whole lookup.
+  }
+
+  if (fm.model && fm.model !== 'inherit') {
+    return { modelAlias: fm.model, modelSource: fromOverlay ? 'persona-overlay' : 'persona' };
+  }
+  return { modelAlias: null, modelSource: 'inherit' };
+}
+
+/** Best-effort read of `<cwd>/session-manager-operations/scheduler/state/queue.json`'s hot jobs[]. */
+function readHotJobsForCwd(cwd, deps) {
+  const { projectQueuePath } = deps.queueStore || require('./queueStore.cjs');
+  try {
+    const data = JSON.parse(fs.readFileSync(projectQueuePath(cwd), 'utf8'));
+    return Array.isArray(data.jobs) ? data.jobs : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Best-effort read of `<cwd>/session-manager-operations/scheduler/state/history.jsonl`'s archived rows. */
+function readHistoryEntriesForCwd(cwd, deps) {
+  const { projectHistoryPath } = deps.queueStore || require('./queueStore.cjs');
+  let text;
+  try {
+    text = fs.readFileSync(projectHistoryPath(cwd), 'utf8');
+  } catch {
+    return [];
+  }
+  const entries = [];
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const j = JSON.parse(line);
+      // needs_review_entry/needs_review_resolution lines (needsReviewLedger.cjs)
+      // share history.jsonl with terminal job rows but carry no `agentType` —
+      // findLatestSchedulerModel's own `j.agentType === agentType` filter
+      // already excludes them, but skip explicitly here too so this reader
+      // stays correct even if a future ledger line shape happens to pick up
+      // an agentType-shaped field.
+      if (j?.kind && j.kind !== 'terminal') continue;
+      entries.push(j);
+    } catch {
+      // corrupt/partial line — skip
+    }
+  }
+  return entries;
+}
+
+function jobTimestampMs(job) {
+  return Date.parse(job?.finishedAt || job?.startedAt || job?.queuedAt || 0) || 0;
+}
+
+/** Bounded HEAD read of an absolute file path; null on any read failure. */
+function readHead(filePath, maxBytes, deps) {
+  const statSync = deps.statSync || fs.statSync;
+  const openSync = deps.openSync || fs.openSync;
+  const readSync = deps.readSync || fs.readSync;
+  const closeSync = deps.closeSync || fs.closeSync;
+  try {
+    const size = statSync(filePath).size;
+    const length = Math.min(maxBytes, size);
+    const buffer = Buffer.alloc(length);
+    const fd = openSync(filePath, 'r');
+    try {
+      readSync(fd, buffer, 0, length, 0);
+    } finally {
+      closeSync(fd);
+    }
+    return buffer.toString('utf8');
+  } catch {
+    return null;
+  }
+}
+
+/** Bounded TAIL read of an absolute file path; null on any read failure. */
+function readTail(filePath, maxBytes, deps) {
+  const statSync = deps.statSync || fs.statSync;
+  const openSync = deps.openSync || fs.openSync;
+  const readSync = deps.readSync || fs.readSync;
+  const closeSync = deps.closeSync || fs.closeSync;
+  try {
+    const size = statSync(filePath).size;
+    const start = Math.max(0, size - maxBytes);
+    const length = size - start;
+    const buffer = Buffer.alloc(length);
+    const fd = openSync(filePath, 'r');
+    try {
+      readSync(fd, buffer, 0, length, start);
+    } finally {
+      closeSync(fd);
+    }
+    const text = buffer.toString('utf8');
+    return start > 0 ? text.slice(text.indexOf('\n') + 1) : text;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Evidence source 1: the scheduler already logs the persona-resolved model
+ * at dispatch (scheduler.cjs's executeJob, ~line 4473: `[scheduler]
+ * agentType=... persona=... model=...`). Scans this project's hot queue.json
+ * jobs[] AND its archived history.jsonl for the most recent job whose
+ * agentType matches, then reads that job's own run log for the line. O(J log
+ * J) to sort J candidate jobs, O(min(logSize, cap)) per log read.
+ */
+function findLatestSchedulerModel(cwd, agentType, deps) {
+  const jobs = [...readHotJobsForCwd(cwd, deps), ...readHistoryEntriesForCwd(cwd, deps)];
+  const matches = jobs.filter((j) => j && j.agentType === agentType && j.runId && j.slug);
+  matches.sort((a, b) => jobTimestampMs(b) - jobTimestampMs(a));
+
+  const homeDir = deps.homeDir || os.homedir();
+  const re = /\[scheduler\] agentType=\S+ persona=.*? model=(\S+)/g;
+  for (const job of matches) {
+    const logPath = path.join(runsDir(homeDir), job.runId, `${job.slug}.log`);
+    const head = readHead(logPath, MAX_RUN_LOG_HEAD_BYTES, deps);
+    if (!head) continue;
+    let match;
+    let last = null;
+    while ((match = re.exec(head))) last = match[1];
+    if (last) return last;
+  }
+  return null;
+}
+
+/**
+ * Evidence source 2: the most recent Epic (active-index.json entry) created
+ * with this agentType, read via its own claude-session transcript's last
+ * `"model":"..."` occurrence. O(E log E) to sort E candidate Epics,
+ * O(min(transcriptSize, cap)) per transcript read.
+ */
+function findLatestTranscriptModel(cwd, agentType, deps) {
+  const readActiveIndex = deps.readActiveIndex || require('./epicMint.cjs').readActiveIndex;
+  let sessions;
+  try {
+    ({ sessions } = readActiveIndex(cwd));
+  } catch {
+    return null;
+  }
+  const matches = Object.values(sessions || {}).filter((s) => s && s.agentType === agentType && s.claudeSessionId);
+  matches.sort((a, b) => (Date.parse(b.createdAt || 0) || 0) - (Date.parse(a.createdAt || 0) || 0));
+
+  const homeDir = deps.homeDir || os.homedir();
+  const encodeCwdFn = deps.encodeCwd || encodeCwd;
+  const re = /"model":"([^"]+)"/g;
+  for (const session of matches) {
+    const filePath = path.join(homeDir, '.claude', 'projects', encodeCwdFn(cwd), `${session.claudeSessionId}.jsonl`);
+    const tail = readTail(filePath, MAX_TRANSCRIPT_TAIL_BYTES, deps);
+    if (!tail) continue;
+    let match;
+    let last = null;
+    while ((match = re.exec(tail))) last = match[1];
+    if (last) return last;
+  }
+  return null;
+}
+
+/**
+ * resolveEffectiveModelInfo({ cwd, agentType, deps? }) →
+ *   { agentType, modelAlias, modelSource, resolvedModelId, resolvedFrom, effortReachable }
+ *
+ * Never throws. `cwd` is normalized through the same worktree/ops-internal
+ * -aware resolver every ops-root reader goes through, so a job worktree cwd
+ * resolves to its main project tree before anything is looked up.
+ */
+async function resolveEffectiveModelInfo({ cwd, agentType, deps = {} } = {}) {
+  const effortReachable = computeEffortReachable(deps);
+  const miss = {
+    agentType: agentType || null,
+    modelAlias: null,
+    modelSource: 'fallback',
+    resolvedModelId: null,
+    resolvedFrom: null,
+    effortReachable,
+  };
+  if (!cwd || !agentType) return miss;
+
+  try {
+    const { projectRootOf } = deps.activeSessions || require('./activeSessions.cjs');
+    const normalizedCwd = projectRootOf(path.resolve(cwd));
+    if (!normalizedCwd) return miss;
+
+    const { modelAlias, modelSource } = await resolvePersonaModelAlias(normalizedCwd, agentType, deps);
+    const result = { agentType, modelAlias, modelSource, resolvedModelId: null, resolvedFrom: null, effortReachable };
+
+    if (isConcreteModelId(modelAlias)) {
+      // Already a concrete pinned id — echo it back, fabricate no evidence.
+      result.resolvedModelId = modelAlias;
+      return result;
+    }
+
+    // Evidence is never derived via historyAggregator.cjs's resolvePricingKey
+    // (which buckets any unknown id to 'sonnet' with estimated:true) —
+    // deliberately: that is a pricing heuristic, and borrowing it here would
+    // turn "we don't know" into a confident wrong answer.
+    const schedulerHit = findLatestSchedulerModel(normalizedCwd, agentType, deps);
+    if (schedulerHit) {
+      result.resolvedModelId = schedulerHit;
+      result.resolvedFrom = 'scheduler-run';
+      return result;
+    }
+
+    const transcriptHit = findLatestTranscriptModel(normalizedCwd, agentType, deps);
+    if (transcriptHit) {
+      result.resolvedModelId = transcriptHit;
+      result.resolvedFrom = 'transcript';
+      return result;
+    }
+
+    return result;
+  } catch {
+    return miss;
+  }
+}
+
+module.exports = {
+  resolveEffectiveModelInfo,
+  isConcreteModelId,
+  computeEffortReachable,
+  KNOWN_MODEL_ALIASES,
+};

package/src/main/lib/ephemeralCwd.cjs

@@ -37,7 +37,7 @@
 
 const os = require('node:os');
 const path = require('node:path');
-const { worktreeMainRootOf } = require('../../../scripts/lib/activeSessions.cjs');
+const { worktreeMainRootOf } = require('./activeSessions.cjs');
 const { KIND_CONFIG } = require('./gitWorktree.cjs');
 
 const TMPDIR = path.resolve(os.tmpdir());

package/src/main/lib/epicMint.cjs

@@ -161,7 +161,7 @@ function resolvePersonaPaths(cwd, agentType, deps = {}) {
  * a readable `.md` persona file, checking the project overlay before the
  * global agents dir. Never throws (a traversal attempt or missing file is
  * treated as "doesn't exist", same fail-closed spirit as
- * agentModelResolve.cjs's readPersonaModel).
+ * agentModelResolve.cjs's readOverlayAwarePersonaModel).
  */
 function personaFileExists(cwd, agentType, deps = {}) {
   const projectDir = deps.projectDir || path.join(cwd, '.claude', 'agents');
@@ -289,8 +289,8 @@ function ensureEpic(cwd, { goalText, tag, epicId: explicitEpicId, status = 'prop
     }
 
     // WRITE-TIME FK CHECK (throw on write, report on read — see this file's
-    // header + agentModelResolve.cjs's readPersonaModel, which is the READ
-    // side of this same FK and stays permissive on purpose). A mint whose
+    // header + agentModelResolve.cjs's readOverlayAwarePersonaModel, which is
+    // the READ side of this same FK and stays permissive on purpose). A mint whose
     // agentType names a persona that doesn't resolve is a bug in the caller
     // (a typo, or a persona deleted between the picker loading and the mint
     // landing) — refuse it now rather than silently orphaning the Epic.

package/src/main/lib/gitWorktree.cjs

@@ -54,6 +54,7 @@ const path = require('node:path');
 const os = require('node:os');
 const crypto = require('node:crypto');
 const { execFile } = require('node:child_process');
+const { OPS_ROOT_DIR } = require('./opsOwnership.cjs');
 
 // Per-kind configuration. Roots are kept OUTSIDE any project's own tree
 // (os.tmpdir(), not `<cwd>/.git/...`) so a managed worktree never shows up in
@@ -304,7 +305,7 @@ async function removeWorktreeDir(cwd, dir) {
  * <name>` segment stripped off.
  *
  * Round-trip verified before being trusted, mirroring the same defense
- * `scripts/lib/activeSessions.cjs`'s `worktreeMainRootOf` already applies: a
+ * `src/main/lib/activeSessions.cjs`'s `worktreeMainRootOf` already applies: a
  * `.git` pointer file is a plain text file, so its content must not be
  * trusted to redirect `git worktree remove --force` at an arbitrary path
  * without the candidate main tree's OWN admin dir
@@ -481,29 +482,58 @@ async function sweepStaleWorktreeCheckouts(kind, opts = {}) {
  * copy of the human's WIP stays in `cwd` the whole time. Nothing here ever
  * `git add`s or commits the carried paths on the job's behalf, and nothing
  * ever restores them back into `cwd` — they were never removed from it.
+ *
+ * The diff itself is captured via `git diff --output=<file>` so git writes
+ * the patch straight to disk — never through Node's stdout buffer. A prior
+ * version piped the patch through `execFile`'s default-`maxBuffer` stdout
+ * capture, which overflowed on a real dirty tree of ~240 changed paths
+ * (`stdout maxBuffer length exceeded`, job 1192) and silently fell back to
+ * running the job in the SHARED working tree — the exact moment isolation
+ * matters most. `--output` removes the buffer ceiling entirely regardless of
+ * how large the tree's outstanding diff is. The temp patch file lives
+ * inside `dir` (the job's own fresh worktree checkout, not a bare
+ * `os.tmpdir()` path) so it is guaranteed to be cleaned up either by the
+ * explicit `fsp.rm` below or, on any earlier failure, by the caller tearing
+ * the whole `dir` down.
  */
 async function captureAndCarryBaseDiff({ cwd, dir }) {
   let paths = [];
-  let patch = '';
   try {
     const nameOut = await execGit(['diff', 'HEAD', '--name-only'], { cwd, timeout: 15_000 });
     paths = nameOut.split('\n').map((l) => l.trim()).filter(Boolean);
-    patch = await execGit(['diff', 'HEAD', '--binary'], { cwd, timeout: 30_000 });
   } catch (e) {
-    return { ok: false, reason: `capturing base diff failed: ${(e && (e.stderrText || e.message)) || e}` };
+    return { ok: false, reason: `listing changed paths failed: ${(e && (e.stderrText || e.message)) || e}` };
   }
-  if (!patch || !patch.trim()) return { ok: true, paths: [] };
 
-  const patchFile = path.join(os.tmpdir(), `sm-worktree-carry-${crypto.randomBytes(8).toString('hex')}.patch`);
+  // Everything from here on operates on a real (or attempted) file at
+  // `patchFile` — wrapped in one try/finally so the temp file is removed on
+  // EVERY exit path, including a `git diff` that errors after partially
+  // writing it, not just the clean-success path.
+  const patchFile = path.join(dir, `.sm-worktree-carry-${crypto.randomBytes(8).toString('hex')}.patch`);
   try {
-    await fsp.writeFile(patchFile, patch, 'utf8');
-    await execGit(['apply', '--binary', patchFile], { cwd: dir, timeout: 30_000 });
-  } catch (e) {
-    return { ok: false, reason: `git apply failed: ${(e && (e.stderrText || e.message)) || e}` };
+    try {
+      await execGit(['diff', 'HEAD', '--binary', `--output=${patchFile}`], { cwd, timeout: 120_000 });
+    } catch (e) {
+      return { ok: false, reason: `capturing base diff failed: ${(e && (e.stderrText || e.message)) || e}` };
+    }
+
+    let stat;
+    try {
+      stat = await fsp.stat(patchFile);
+    } catch (e) {
+      return { ok: false, reason: `reading captured diff file failed: ${(e && e.message) || e}` };
+    }
+    if (stat.size === 0) return { ok: true, paths: [] };
+
+    try {
+      await execGit(['apply', '--binary', patchFile], { cwd: dir, timeout: 30_000 });
+    } catch (e) {
+      return { ok: false, reason: `git apply failed: ${(e && (e.stderrText || e.message)) || e}` };
+    }
+    return { ok: true, paths };
   } finally {
     try { await fsp.rm(patchFile, { force: true }); } catch { /* best-effort */ }
   }
-  return { ok: true, paths };
 }
 
 /**
@@ -1273,7 +1303,7 @@ async function reclaimTerminalJobOrphans({ cwd, terminalSlugs, isLive }) {
     }
     const dirtyPaths = statusOut.split('\n').map((l) => l.slice(3).trim()).filter(Boolean);
     const opsOnly = dirtyPaths.every(
-      (p) => p === 'session-manager-operations' || p.startsWith('session-manager-operations/')
+      (p) => p === OPS_ROOT_DIR || p.startsWith(`${OPS_ROOT_DIR}/`)
     );
     if (!opsOnly) continue; // real non-ops dirty content present — leave for a human
 

package/src/main/lib/guardShims.cjs

@@ -0,0 +1,156 @@
+/**
+ * guardShims.cjs — stable, app-upgrade-proof indirection for the three
+ * PreToolUse guard hooks that delegationReadiness.cjs installs into an
+ * adopting project's `.claude/settings.json`.
+ *
+ * Why this exists: those installers used to bake
+ * `path.resolve(__dirname, '../../../scripts/hooks/guard-*.cjs')` — THIS
+ * app's own copy of the script — directly into the hook command. Run via
+ * `npx claude-code-session-manager@latest` (the normal install path), that
+ * resolves under `~/.npm/_npx/<hash>/node_modules/claude-code-session-manager/`
+ * — a directory scoped to ONE npx resolution. The next `npx ...@latest` (a
+ * new release) or an npm cache prune creates/removes a different hash dir, so
+ * every previously-installed hook decays into a dead path. A PreToolUse
+ * command pointing at a missing script exits non-zero WITHOUT exit code 2 (a
+ * non-blocking error to the harness), so it silently guards nothing — while
+ * checkPrdWriteGuard correctly flips the readiness banner back to red. That
+ * decay is why "Delegation not ready" reappears across projects even after a
+ * successful install.
+ *
+ * Fix: install a STABLE shim under the user's home
+ * (`~/.claude/session-manager/hooks/guard-<name>.cjs`) that never moves
+ * across app upgrades. The shim contains no guard logic of its own — CLAUDE.md's
+ * "adopt by REFERENCE, never vendor" law — it reads a pointer file
+ * (`app-root.json`, rewritten on every app boot with the CURRENTLY running
+ * app's root) and `require()`s the real `scripts/hooks/guard-<name>.cjs` from
+ * there. An app upgrade (a new npx hash dir) just rewrites the pointer on the
+ * next boot; every already-installed project hook keeps resolving through
+ * the same shim path with no re-install.
+ *
+ * The guard scripts run their logic as a require-time side effect (stdin ->
+ * decision -> process.exit, not gated on `require.main === module`), so a
+ * plain `require()` from the shim is enough to invoke them.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { writeJson, writeTextAtomic, addAllowedRoot } = require('../config.cjs');
+
+// src/main/lib -> app root (three levels up) — the same resolution
+// delegationReadiness.cjs's *_GUARD_SCRIPT constants use.
+const APP_ROOT = path.resolve(__dirname, '..', '..', '..');
+
+const GUARD_NAMES = ['guard-prd-writes.cjs', 'guard-destructive-git.cjs', 'guard-inline-implementation.cjs', 'guard-self-schedule.cjs'];
+
+function hooksDir(homeDir = os.homedir()) {
+  return path.join(homeDir, '.claude', 'session-manager', 'hooks');
+}
+
+function pointerPath(homeDir = os.homedir()) {
+  return path.join(hooksDir(homeDir), 'app-root.json');
+}
+
+function shimPath(guardName, homeDir = os.homedir()) {
+  return path.join(hooksDir(homeDir), guardName);
+}
+
+function shimBody(guardName) {
+  return `'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const ptr = JSON.parse(fs.readFileSync(path.join(__dirname, 'app-root.json'), 'utf8'));
+require(path.join(ptr.appRoot, 'scripts', 'hooks', '${guardName}'));
+`;
+}
+
+/**
+ * Write the pointer file + all three shims under `homeDir`. Idempotent: a
+ * re-run with the same `appRoot` produces byte-identical files; a re-run with
+ * a DIFFERENT `appRoot` (an app upgrade) rewrites only the pointer, which is
+ * exactly what lets already-installed project hooks follow the upgrade with
+ * no re-install. Never throws — returns `{ ok, error }` so a boot-time caller
+ * can fire-and-forget and an installer can refuse cleanly rather than writing
+ * a hook command that points at a shim that doesn't exist.
+ */
+async function writeGuardShims({ homeDir = os.homedir(), appRoot = APP_ROOT } = {}) {
+  try {
+    addAllowedRoot(homeDir);
+    await writeJson(pointerPath(homeDir), { appRoot });
+    for (const name of GUARD_NAMES) {
+      await writeTextAtomic(shimPath(name, homeDir), shimBody(name));
+    }
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err?.message ?? String(err) };
+  }
+}
+
+/** True when every shim + the pointer file already exist on disk under `homeDir`. */
+function guardShimsExist(homeDir = os.homedir()) {
+  return fs.existsSync(pointerPath(homeDir)) && GUARD_NAMES.every((name) => fs.existsSync(shimPath(name, homeDir)));
+}
+
+/**
+ * Given an absolute script path a hook command resolved to, determine
+ * whether it's actually a guard SHIM (its directory carries a sibling
+ * `app-root.json`) rather than a direct app-root script. A direct script has
+ * no pointer and is trivially "real" once `fs.existsSync` is true — the
+ * caller doesn't need this function for that case.
+ *
+ * For a shim, existence of the shim FILE is not enough: the shim's own
+ * require() target is `ptr.appRoot/scripts/hooks/<name>.cjs`, resolved only
+ * at hook-invocation time. If the pointer is missing, unparseable, or now
+ * names a script that's gone, the shim silently guards nothing the next time
+ * a hook actually fires — decay one hop downstream of the hook command
+ * itself. Returns `null` when `scriptAbsPath` is not a shim (no sibling
+ * pointer) — the caller's plain existence check already covers that case.
+ * Throws when it IS a shim and the pointer has decayed.
+ */
+function resolveShimTarget(scriptAbsPath) {
+  const dir = path.dirname(scriptAbsPath);
+  const ptrFile = path.join(dir, 'app-root.json');
+  if (!fs.existsSync(ptrFile)) return null;
+
+  const guardName = path.basename(scriptAbsPath);
+  let appRoot;
+  try {
+    appRoot = JSON.parse(fs.readFileSync(ptrFile, 'utf8'))?.appRoot;
+  } catch (err) {
+    throw new Error(`guard shim pointer ${ptrFile} is unparseable: ${err?.message ?? err}`);
+  }
+  if (typeof appRoot !== 'string' || !appRoot) {
+    throw new Error(`guard shim pointer ${ptrFile} has no appRoot`);
+  }
+  const real = path.join(appRoot, 'scripts', 'hooks', guardName);
+  if (!fs.existsSync(real)) {
+    throw new Error(`guard shim pointer ${ptrFile} resolves to a script that no longer exists: ${real}`);
+  }
+  return real;
+}
+
+/**
+ * `writeGuardShims({ homeDir })`, but returns `null` on success and an
+ * install-function-shaped error object (`{ ok:false, action:'error', error }`)
+ * on failure — the one call every `install*Guard` in delegationReadiness.cjs
+ * needs before it can safely write a hook command pointing at the shim.
+ */
+async function ensureGuardShimsOrError(homeDir) {
+  const result = await writeGuardShims({ homeDir });
+  if (result.ok) return null;
+  return { ok: false, action: 'error', error: `could not write the stable guard shim under ${hooksDir(homeDir)}: ${result.error}` };
+}
+
+module.exports = {
+  APP_ROOT,
+  GUARD_NAMES,
+  hooksDir,
+  pointerPath,
+  shimPath,
+  shimBody,
+  writeGuardShims,
+  guardShimsExist,
+  resolveShimTarget,
+  ensureGuardShimsOrError,
+};

package/src/main/lib/jobDirtFilter.cjs

@@ -27,8 +27,13 @@
  * must still park.
  */
 
-/** The one app-owned root. Matches at any depth, and only as a path segment. */
-const OPS_ROOT_SEGMENT = 'session-manager-operations';
+/**
+ * The one app-owned root. Matches at any depth, and only as a path segment.
+ * Sourced from opsOwnership.cjs (the single-writer law's own root name)
+ * rather than a second hardcoded literal — this file matches git-porcelain
+ * RELATIVE paths, never builds an fs path, so opsPath() itself doesn't apply.
+ */
+const { OPS_ROOT_DIR: OPS_ROOT_SEGMENT } = require('./opsOwnership.cjs');
 
 /** True when `p` lives under an app-owned operations root. Pure. */
 function isAppOwnedChurn(p) {

package/src/main/lib/launchFailure.cjs

@@ -309,9 +309,10 @@ function evaluateLaunchGate(block, { now, claudeVersion } = {}) {
  * closed set so operators never have to open a transcript to tell a
  * non-start from an implementation failure from a verifier downgrade.
  */
-function deriveTerminalReason({ effectiveStatus, exitCode, verifyResult, sigtermOverride, worktreeIntegrationFailure }) {
+function deriveTerminalReason({ effectiveStatus, exitCode, verifyResult, sigtermOverride, worktreeIntegrationFailure, budgetKill }) {
   if (worktreeIntegrationFailure) return 'worktree_integration_failed';
   if (effectiveStatus === 'completed') return 'completed';
+  if (budgetKill) return 'budget_exceeded';
   if (sigtermOverride) return 'signal_kill_with_commit';
   if (exitCode === 143 || exitCode === 137) return 'signal_kill';
   if (typeof exitCode === 'number' && exitCode !== 0) return `impl_failed:exit_${exitCode}`;

package/src/main/lib/mcpToolCatalog.cjs

@@ -75,7 +75,10 @@ const MCP_TOOL_CATALOG = [
       + '`tag` and `agentType` are two DIFFERENT, independent fields — `tag` is WHAT KIND '
       + 'of work this PRD is (feature/bug/build/...); `agentType` is WHO executes it (a '
       + 'persona name, e.g. "dev-lead"). `agentType` defaults to "dev-lead" when omitted, '
-      + 'and is rejected at write time if it does not name a real persona file.',
+      + 'and is rejected at write time if it does not name a real persona file. '
+      + 'If this PRD has no dependsOn of its own AND the target Epic already has incomplete PRDs, '
+      + '`disposition` ("append" or "new-head") is REQUIRED — the write is refused without it (a '
+      + 'headless job caller instead gets a logged "append" default, since no human is present to ask).',
     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 '