claude-code-session-manager 0.98.0 → 0.100.0

package/src/main/lib/timeoutShim.cjs

@@ -0,0 +1,123 @@
+/**
+ * timeoutShim.cjs — installs a dependency-free `timeout` shim under the
+ * user's home, for machines whose `timeout` is missing or non-GNU (stock
+ * macOS ships none at all), and exposes `withTimeoutShimOnPath` so a child
+ * spawn's PATH can fall back to it.
+ *
+ * Mirrors guardShims.cjs's pattern: a stable path under
+ * `~/.claude/session-manager/`, written with `writeTextAtomic`, idempotent
+ * (a re-run with unchanged content writes nothing), and `addAllowedRoot`
+ * called first so a test's temp "home" passes config.cjs's write-boundary
+ * check the same way the real home does.
+ *
+ * `timeout-shim.cjs` under the shim dir is a verbatim copy of
+ * timeoutShimScript.cjs, read from disk at call time (not inlined here) so
+ * the installed copy can never drift from the source file. `timeout` is a
+ * tiny POSIX launcher that runs it with `node`, falling back to the current
+ * Electron binary (`execPath`) with ELECTRON_RUN_AS_NODE=1 when no `node` is
+ * on PATH.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { writeTextAtomic, addAllowedRoot } = require('../config.cjs');
+
+function shimDir(homeDir = os.homedir()) {
+  return path.join(homeDir, '.claude', 'session-manager', 'bin');
+}
+
+function shimPath(homeDir = os.homedir()) {
+  return path.join(shimDir(homeDir), 'timeout');
+}
+
+function scriptDestPath(homeDir = os.homedir()) {
+  return path.join(shimDir(homeDir), 'timeout-shim.cjs');
+}
+
+// Single-quote the exec path for POSIX sh: close the quote, escape any
+// literal `'` as `'\''`, reopen it. A plain path with no `'` in it just
+// comes back wrapped in quotes.
+function quoteForShell(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
+
+function launcherBody(execPath) {
+  return `#!/bin/sh
+SHIM_DIR=$(dirname "$0")
+if command -v node >/dev/null 2>&1; then
+  exec node "$SHIM_DIR/timeout-shim.cjs" "$@"
+fi
+ELECTRON_RUN_AS_NODE=1 exec ${quoteForShell(execPath)} "$SHIM_DIR/timeout-shim.cjs" "$@"
+`;
+}
+
+function readIfExists(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Writes the shim pair under `<homeDir>/.claude/session-manager/bin`.
+ * Each file is written only when its content differs from what's already on
+ * disk. The launcher's own write sets its mode to 0755 on the temp file
+ * BEFORE the rename, so the path at `launcherDest` never exists without the
+ * exec bit — a gate that races the install can only ever see "not there yet"
+ * or "there and runnable", never "there but exit 126". The chmod right after
+ * is a second, unconditional pass (even on a no-op run) so a permission
+ * change made outside this function self-heals on the next call. Never
+ * throws: returns `{ok:true, changed, path}` (`path` is the launcher path) on
+ * success, `{ok:false, error}` on failure, and `{ok:false, skipped:true}` on
+ * win32, where there is no POSIX shell to run the launcher.
+ */
+async function ensureTimeoutShim({ homeDir = os.homedir(), execPath = process.execPath } = {}) {
+  if (process.platform === 'win32') return { ok: false, skipped: true };
+  try {
+    addAllowedRoot(homeDir);
+    const scriptDest = scriptDestPath(homeDir);
+    const launcherDest = shimPath(homeDir);
+    const scriptContent = fs.readFileSync(path.join(__dirname, 'timeoutShimScript.cjs'), 'utf8');
+    const launcherContent = launcherBody(execPath);
+
+    let changed = false;
+    if (readIfExists(scriptDest) !== scriptContent) {
+      await writeTextAtomic(scriptDest, scriptContent);
+      changed = true;
+    }
+    if (readIfExists(launcherDest) !== launcherContent) {
+      await writeTextAtomic(launcherDest, launcherContent, { mode: 0o755 });
+      changed = true;
+    }
+    // Repairs a mode changed by hand; the write above already set 0o755
+    // before the rename, so this is a no-op in the common case.
+    fs.chmodSync(launcherDest, 0o755);
+    return { ok: true, changed, path: launcherDest };
+  } catch (err) {
+    return { ok: false, error: err?.message ?? String(err) };
+  }
+}
+
+/**
+ * Appends the shim dir to `pathValue`, at the end, so a real `timeout`
+ * earlier on PATH (GNU coreutils, Homebrew, ...) keeps winning. No-op when
+ * the shim dir is already anywhere in `pathValue` — never adds a duplicate.
+ */
+function withTimeoutShimOnPath(pathValue, homeDir = os.homedir()) {
+  const dir = shimDir(homeDir);
+  const current = pathValue == null ? '' : String(pathValue);
+  const parts = current.split(path.delimiter).filter(Boolean);
+  if (parts.includes(dir)) return current;
+  if (!parts.length) return dir;
+  return `${current}${path.delimiter}${dir}`;
+}
+
+module.exports = {
+  shimDir,
+  shimPath,
+  ensureTimeoutShim,
+  withTimeoutShimOnPath,
+};

package/src/main/lib/timeoutShimScript.cjs

@@ -0,0 +1,275 @@
+'use strict';
+
+/**
+ * timeoutShimScript.cjs — a dependency-free stand-in for GNU coreutils'
+ * `timeout`, for machines that don't ship one (stock macOS has no `timeout`
+ * binary at all, so a PRD gate command that starts with `timeout <seconds>
+ * ...` fails outright there).
+ *
+ * This file is copied byte-for-byte (see timeoutShim.cjs's ensureTimeoutShim)
+ * to `~/.claude/session-manager/bin/timeout-shim.cjs` and run from there by a
+ * tiny POSIX launcher. It must never require anything outside Node's own
+ * builtins, so it keeps working no matter where it lands or which Node it
+ * runs under (plain `node`, or Electron with ELECTRON_RUN_AS_NODE=1 — both
+ * launch this file as the main module with the same `process.argv` shape).
+ *
+ * Usage: timeout [OPTION] DURATION COMMAND [ARG]...
+ *
+ * This covers only the GNU `timeout` forms a PRD gate actually uses. It adds
+ * no option GNU timeout lacks.
+ *
+ * DURATION is a number (float allowed), optionally suffixed s/m/h/d
+ * (default s). 0 means no limit. A duration above Node's signed-32-bit
+ * setTimeout cap (2,147,483,647 ms, about 24.8 days) is re-armed in chunks —
+ * see setLongTimeout below — rather than passed straight to setTimeout,
+ * which would silently fire after 1ms instead of waiting.
+ *
+ * Options: -s/--signal=SIGNAL (name or number, with or without the SIG
+ * prefix; default TERM), -k/--kill-after=DURATION, --foreground,
+ * --preserve-status, -v/--verbose, --help, --version, -- to end options.
+ *
+ * SIGNAL must name a real signal: a number must be a nonzero value from
+ * os.constants.signals, and a name must match a key of os.constants.signals
+ * once uppercased and SIG-prefixed. Anything else — including an empty
+ * value, e.g. `--signal=` — is a usage error (exit 125), never a silent
+ * fallback to the default. --kill-after=0 means no kill-after at all (same
+ * as omitting -k), matching GNU: it does not arm a timer that fires
+ * immediately.
+ *
+ * Rule: on timeout, signal the whole process group, not just the direct
+ * child. Why: a child that is itself a wrapper (a shell, a test runner) can
+ * spawn a grandchild that keeps running after the direct child is gone — only
+ * a group-wide signal reaches it too.
+ *
+ * Exit codes (GNU-compatible):
+ *   124    COMMAND timed out (unless --preserve-status)
+ *   125    this script's own usage error
+ *   126    COMMAND found but not runnable (EACCES)
+ *   127    COMMAND not found (ENOENT)
+ *   128+N  COMMAND was killed by signal N — covers 137 (128+SIGKILL), the
+ *          case where DURATION expired, COMMAND ignored the first signal,
+ *          and -k's follow-up SIGKILL was the one that actually landed
+ *   otherwise  COMMAND's own exit code
+ */
+
+const { spawn } = require('node:child_process');
+const os = require('node:os');
+
+const HELP = `Usage: timeout [OPTION] DURATION COMMAND [ARG]...
+Start COMMAND, and kill it if it is still running after DURATION.
+
+  -s, --signal=SIGNAL    signal to send on timeout (name or number; default TERM)
+  -k, --kill-after=DUR   also send KILL after DUR if COMMAND is still running
+      --foreground       do not put COMMAND in its own process group
+      --preserve-status  exit with COMMAND's own status, even after a timeout
+  -v, --verbose          log signals sent to stderr
+      --help             show this help and exit
+      --version          show version and exit
+
+DURATION is a number, optionally followed by s/m/h/d (default s). 0 means no limit.
+`;
+
+const FORWARDED_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+
+function usageError(message) {
+  process.stderr.write(`timeout: ${message}\n`);
+  process.stderr.write(`Try 'timeout --help' for more information.\n`);
+  process.exit(125);
+}
+
+/** Parses a GNU-style DURATION token into milliseconds. Returns null when the
+ *  token is not a valid duration. Uses String#match rather than
+ *  RegExp#exec — same result shape for a non-global pattern, just a form
+ *  that doesn't read as a shell-exec call at a glance. */
+function parseDurationMs(token) {
+  const m = String(token).match(/^(\d+(?:\.\d+)?)([smhd]?)$/);
+  if (!m) return null;
+  const multiplier = { '': 1, s: 1, m: 60, h: 3600, d: 86400 }[m[2]];
+  return Number(m[1]) * multiplier * 1000;
+}
+
+/** Normalizes a signal option value (name with or without SIG prefix, or a
+ *  number) to what node:child_process.kill expects. Returns null when the
+ *  value names no known signal — including an empty value, which is a usage
+ *  error, not a request for the default (the default is applied by
+ *  parseArgs's own initial `opts.signal = 'SIGTERM'`, before this function
+ *  ever runs). A numeric value is valid only when it is a nonzero entry of
+ *  os.constants.signals — not just any digit string. */
+function normalizeSignal(raw) {
+  const token = String(raw).trim();
+  if (/^\d+$/.test(token)) {
+    const n = Number(token);
+    if (n === 0 || !Object.values(os.constants.signals).includes(n)) return null;
+    return n;
+  }
+  let name = token.toUpperCase();
+  if (!name.startsWith('SIG')) name = `SIG${name}`;
+  if (!(name in os.constants.signals)) return null;
+  return name;
+}
+
+function signalNumber(sigName) {
+  return os.constants.signals[sigName] || 0;
+}
+
+// Node's setTimeout takes a signed 32-bit ms value. A delay above
+// MAX_SETTIMEOUT_MS (2,147,483,647 ms, about 24.8 days) wraps and fires
+// after 1ms instead of waiting — so `timeout 30d cmd` would kill `cmd`
+// immediately. setLongTimeout re-arms in MAX_SETTIMEOUT_MS chunks until the
+// full delay has elapsed, then calls `fn` once. Returns a handle for
+// clearLongTimeout; one handle covers every chunk, so clearing mid-wait
+// still works.
+const MAX_SETTIMEOUT_MS = 2_147_483_647;
+
+function setLongTimeout(fn, ms) {
+  const handle = { timer: null, cancelled: false };
+  function arm(remaining) {
+    const step = Math.min(remaining, MAX_SETTIMEOUT_MS);
+    handle.timer = setTimeout(() => {
+      if (handle.cancelled) return;
+      const left = remaining - step;
+      if (left > 0) arm(left);
+      else fn();
+    }, step);
+  }
+  arm(Math.max(0, ms));
+  return handle;
+}
+
+function clearLongTimeout(handle) {
+  if (!handle) return;
+  handle.cancelled = true;
+  if (handle.timer) clearTimeout(handle.timer);
+}
+
+/** Pure argv parser. Returns either {help:true}, {version:true},
+ *  {error:string}, or the parsed option bag with `.rest` holding
+ *  [DURATION, COMMAND, ...COMMAND_ARGS]. */
+function parseArgs(argv) {
+  const opts = { signal: 'SIGTERM', killAfter: null, foreground: false, preserveStatus: false, verbose: false };
+  let i = 0;
+  while (i < argv.length) {
+    const a = argv[i];
+    if (a === '--') { i += 1; break; }
+    if (a === '--help') return { help: true };
+    if (a === '--version') return { version: true };
+    if (a === '--foreground') { opts.foreground = true; i += 1; continue; }
+    if (a === '--preserve-status') { opts.preserveStatus = true; i += 1; continue; }
+    if (a === '-v' || a === '--verbose') { opts.verbose = true; i += 1; continue; }
+    if (a === '-s' || a === '--signal') {
+      if (argv[i + 1] === undefined) return { error: `option '${a}' requires an argument` };
+      opts.signal = argv[i + 1]; i += 2; continue;
+    }
+    if (a.startsWith('--signal=')) { opts.signal = a.slice('--signal='.length); i += 1; continue; }
+    if (a === '-k' || a === '--kill-after') {
+      if (argv[i + 1] === undefined) return { error: `option '${a}' requires an argument` };
+      opts.killAfter = argv[i + 1]; i += 2; continue;
+    }
+    if (a.startsWith('--kill-after=')) { opts.killAfter = a.slice('--kill-after='.length); i += 1; continue; }
+    if (a.startsWith('-') && a !== '-') return { error: `unrecognized option '${a}'` };
+    break;
+  }
+  opts.rest = argv.slice(i);
+  return opts;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) { process.stdout.write(HELP); process.exit(0); return; }
+  if (opts.version) { process.stdout.write('timeout-shim (session-manager) 1.0\n'); process.exit(0); return; }
+  if (opts.error) { usageError(opts.error); return; }
+
+  const rest = opts.rest || [];
+  if (rest.length < 1) { usageError('missing operand'); return; }
+  const [durationToken, command, ...commandArgs] = rest;
+  if (!command) { usageError(`missing command after DURATION '${durationToken}'`); return; }
+
+  const durationMs = parseDurationMs(durationToken);
+  if (durationMs === null) { usageError(`invalid time interval '${durationToken}'`); return; }
+
+  let killAfterMs = null;
+  if (opts.killAfter != null) {
+    killAfterMs = parseDurationMs(opts.killAfter);
+    if (killAfterMs === null) { usageError(`invalid time interval '${opts.killAfter}'`); return; }
+  }
+
+  const signal = normalizeSignal(opts.signal);
+  if (signal === null) { usageError(`invalid signal '${opts.signal}'`); return; }
+
+  let child = null;
+  let settled = false;
+  let timedOut = false;
+  let killAfterFired = false;
+  let timer = null;
+  let killAfterTimer = null;
+
+  const forwardHandlers = {};
+  for (const sig of FORWARDED_SIGNALS) {
+    forwardHandlers[sig] = () => { if (child) killGroup(sig); };
+    process.on(sig, forwardHandlers[sig]);
+  }
+
+  function finish(code) {
+    if (settled) return;
+    settled = true;
+    if (timer) clearLongTimeout(timer);
+    if (killAfterTimer) clearLongTimeout(killAfterTimer);
+    for (const sig of FORWARDED_SIGNALS) process.removeListener(sig, forwardHandlers[sig]);
+    process.exit(code);
+  }
+
+  // Signal the whole process group first (so a grandchild the direct child
+  // spawned, without detaching further, dies too); fall back to the direct
+  // pid only when the group signal itself fails (e.g. --foreground, where
+  // the child shares OUR group rather than leading its own).
+  function killGroup(sig) {
+    try {
+      process.kill(-child.pid, sig);
+    } catch {
+      try { process.kill(child.pid, sig); } catch { /* already gone */ }
+    }
+  }
+
+  try {
+    child = spawn(command, commandArgs, { stdio: 'inherit', detached: !opts.foreground });
+  } catch (err) {
+    finish(err && err.code === 'EACCES' ? 126 : 127);
+    return;
+  }
+
+  if (durationMs > 0) {
+    timer = setLongTimeout(() => {
+      timedOut = true;
+      if (opts.verbose) process.stderr.write(`timeout: sending signal ${String(signal)} to command '${command}'\n`);
+      killGroup(signal);
+      // killAfterMs === 0 means "no kill-after", same as -k not given at
+      // all — GNU timeout never arms a kill timer that fires immediately.
+      if (killAfterMs != null && killAfterMs > 0) {
+        killAfterTimer = setLongTimeout(() => {
+          killAfterFired = true;
+          if (opts.verbose) process.stderr.write(`timeout: sending signal KILL to command '${command}'\n`);
+          killGroup('SIGKILL');
+        }, killAfterMs);
+      }
+    }, durationMs);
+  }
+
+  child.on('error', (err) => {
+    finish(err && err.code === 'EACCES' ? 126 : 127);
+  });
+
+  child.on('exit', (code, sig) => {
+    if (sig) {
+      // Died from a signal. If that signal was OUR timeout's original
+      // (not-yet-escalated-to-KILL) signal, report the conventional 124 —
+      // unless the caller asked to see the command's real status instead.
+      if (timedOut && !killAfterFired && !opts.preserveStatus) { finish(124); return; }
+      finish(128 + signalNumber(sig));
+      return;
+    }
+    if (timedOut && !opts.preserveStatus) { finish(124); return; }
+    finish(code == null ? 0 : code);
+  });
+}
+
+if (require.main === module) main();

package/src/main/lib/upgradeDrain.cjs

@@ -24,6 +24,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const schedulerPaths = require('./schedulerPaths.cjs');
+const atomicFs = require('./atomicFs.cjs');
 
 // Observed max job run is 240 min; 4 h converts a stuck drain to an abort.
 const DEFAULT_DRAIN_DEADLINE_MS = 4 * 60 * 60_000;
@@ -32,19 +33,12 @@ const DEFAULT_DRAIN_DEADLINE_MS = 4 * 60 * 60_000;
 const RESTARTING_MARKER_TTL_MS = 5 * 60_000;
 
 function writeJsonAtomicSync(file, value) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
-  fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n', 'utf8');
-  fs.renameSync(tmp, file);
+  atomicFs.writeJsonAtomicSync(file, value);
 }
 
 function readJsonSafe(file) {
-  try {
-    const v = JSON.parse(fs.readFileSync(file, 'utf8'));
-    return v && typeof v === 'object' ? v : null;
-  } catch {
-    return null;
-  }
+  const v = atomicFs.readJsonOrSync(file, null);
+  return v && typeof v === 'object' ? v : null;
 }
 
 // ---------- request file ----------

package/src/main/lib/watchdogHelpers.cjs

@@ -7,6 +7,8 @@ const fs = require('node:fs');
 const path = require('node:path');
 const schedulerPaths = require('./schedulerPaths.cjs');
 const { isRestartingMarkerActive } = require('./upgradeDrain.cjs');
+const { pidAlive: pidAliveCore } = require('./pidAlive.cjs');
+const atomicFs = require('./atomicFs.cjs');
 
 
 
@@ -142,23 +144,14 @@ function evaluateDispatchLiveness(entry, now = Date.now(), { deadMs = DEFAULT_DI
 /**
  * isPidAlive(pid) → boolean
  *
- * Plain liveness check via process.kill(pid, 0) (no signal sent). Single
- * source of truth for the "is this recorded pid still alive" check used by
- * checkAppLiveness's defense-in-depth relaunch gate.
- *
- * EPERM (pid exists, owned by another user) counts as alive — only ESRCH
- * (no such process) means dead. Watchdog and app run as the same user in
- * practice, so this distinction rarely matters here, but treating EPERM as
- * "dead" would be wrong on its face (the process demonstrably exists).
+ * Thin alias over pidAlive.cjs's shared pidAlive() — single source of truth
+ * for the "is this recorded pid still alive" check used by
+ * checkAppLiveness's defense-in-depth relaunch gate. Kept as a named export
+ * here (rather than inlining the require at every call site) so existing
+ * imports of `isPidAlive` from this module keep working unchanged.
  */
 function isPidAlive(pid) {
-  if (typeof pid !== 'number' || !Number.isFinite(pid)) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (e) {
-    return e?.code === 'EPERM';
-  }
+  return pidAliveCore(pid);
 }
 
 // Offline queue.json reconciliation (orphaned 'running' jobs whose pid died
@@ -213,12 +206,9 @@ function readRelaunchState(statePath = schedulerPaths.watchdogRelaunchStatePath(
   }
 }
 
-/** Atomic write: tmp-<pid>-<ts> → rename (mirrors config.cjs writeJsonSync). */
+/** Atomic write via atomicFs.cjs (mirrors config.cjs writeJsonSync). */
 function writeRelaunchState(statePath, state) {
-  fs.mkdirSync(path.dirname(statePath), { recursive: true });
-  const tmpPath = `${statePath}.tmp-${process.pid}-${Date.now()}`;
-  fs.writeFileSync(tmpPath, JSON.stringify(state, null, 2) + '\n', 'utf8');
-  fs.renameSync(tmpPath, statePath);
+  atomicFs.writeJsonAtomicSync(statePath, state);
 }
 
 function logRelaunchLine(logPath, message) {
@@ -343,12 +333,9 @@ function readStampDate(stampPath) {
   }
 }
 
-/** Atomic write: tmp-<pid>-<ts> → rename (mirrors config.cjs writeJsonSync). */
+/** Atomic write via atomicFs.cjs (mirrors config.cjs writeJsonSync). */
 function writeStampDate(stampPath, date) {
-  fs.mkdirSync(path.dirname(stampPath), { recursive: true });
-  const tmpPath = `${stampPath}.tmp-${process.pid}-${Date.now()}`;
-  fs.writeFileSync(tmpPath, date, 'utf8');
-  fs.renameSync(tmpPath, stampPath);
+  atomicFs.writeTextAtomicSync(stampPath, date);
 }
 
 /**

package/src/main/lib/workTypeLibrary.cjs

@@ -27,11 +27,16 @@ const WORK_TYPES = Object.freeze([
   'discussion',
   'build',
   'project-home-builder',
-  'bilko-host-publisher',
 ]);
 
 const WorkTypeSchema = z.enum(WORK_TYPES);
 
+// Tag ids that used to be in WORK_TYPES and must still parse on an old
+// on-disk Epic/persona record — never thrown on, always dropped. Single
+// source of truth for promptSessionSchema.cjs / agentPersonaSchema.cjs's
+// legacy-drop preprocessing.
+const LEGACY_WORK_TYPES = Object.freeze(['bilko-host-publisher']);
+
 // A 'discussion'-tagged ticket never reaches PRD authoring (a domain
 // invariant unrelated to the Epic/PRD tag unification above), so the PRD
 // frontmatter `tag` field — parsed in prdFrontmatter.cjs/.ts and patched via
@@ -45,4 +50,5 @@ module.exports = {
   WorkTypeSchema,
   PRD_WORK_TYPES,
   PrdWorkTypeSchema,
+  LEGACY_WORK_TYPES,
 };

package/src/main/promptSessionEvents.cjs

@@ -46,11 +46,21 @@ function mintEventId() {
 /**
  * If `sourcePromptId` resolves to a known, still-active PromptSession under
  * `cwd`'s active-index.json, appends a 'response' event chained to that
- * session's current tail and returns true. Returns false (never throws) for
- * every case the caller must fall back on: missing cwd/id, no index file,
- * unknown id, a completed session, an empty event chain, or any I/O error —
- * so notifyOriginatingTab's existing tab-external-ticket path stays the
- * safety net, not a special case.
+ * session's current tail and returns `{ ok: true }`. Returns `{ ok: false,
+ * reason }` (never throws) for every case the caller must fall back on:
+ *
+ *   'missing-args' — cwd or sourcePromptId not given.
+ *   'no-index'     — no active-index.json for this cwd, or it has no data.
+ *   'no-session'   — sourcePromptId is not a known session.
+ *   'not-active'   — the session exists but has already completed.
+ *   'no-events'    — the session has no event chain to append onto.
+ *   'error'        — a caught exception (e.g. a disk read/write failure).
+ *
+ * `'error'` is the only reason worth retrying — every other reason means the
+ * session or event chain genuinely is not there to append to, and trying
+ * again later cannot change that. flushDueReviewNotices (scheduler.cjs)
+ * uses exactly that split to decide whether to hold a notice back for one
+ * more pass or give up on it.
  *
  * The optional 4th argument stamps `prdSlug`/`outcome` onto the appended
  * event (PRD 976) — which PRD checked in and whether it completed, failed,
@@ -64,19 +74,20 @@ function mintEventId() {
  * `undefined`-valued keys, so events appended without them serialize
  * identically to before.
  */
-async function appendResponseEventIfKnown(cwd, sourcePromptId, text, meta = {}) {
-  if (!cwd || !sourcePromptId) return false;
+async function appendResponseEventWithReason(cwd, sourcePromptId, text, meta = {}) {
+  if (!cwd || !sourcePromptId) return { ok: false, reason: 'missing-args' };
   const path = promptSessionActiveIndexPath(cwd);
   try {
     return await withPathLock(path, async () => {
       const result = await config.readJson(path);
-      if (!result.exists || !result.data) return false;
+      if (!result.exists || !result.data) return { ok: false, reason: 'no-index' };
       const data = result.data;
       const session = data.sessions && data.sessions[sourcePromptId];
-      if (!session || session.status !== 'active') return false;
+      if (!session) return { ok: false, reason: 'no-session' };
+      if (session.status !== 'active') return { ok: false, reason: 'not-active' };
       const events = (data.events && data.events[sourcePromptId]) || [];
       const tail = events.length > 0 ? events[events.length - 1] : null;
-      if (!tail) return false;
+      if (!tail) return { ok: false, reason: 'no-events' };
       const event = {
         id: mintEventId(),
         promptSessionId: sourcePromptId,
@@ -91,16 +102,29 @@ async function appendResponseEventIfKnown(cwd, sourcePromptId, text, meta = {})
       data.events[sourcePromptId] = [...events, event];
       await config.writeJson(path, data, { writer: 'scheduler' });
       broadcast(EVENT_APPENDED_CHANNEL, { cwd, promptSessionId: sourcePromptId, event });
-      return true;
+      return { ok: true };
     });
   } catch (e) {
-    console.error('[promptSessionEvents] appendResponseEventIfKnown error', cwd, sourcePromptId, e);
-    return false;
+    console.error('[promptSessionEvents] appendResponseEventWithReason error', cwd, sourcePromptId, e);
+    return { ok: false, reason: 'error' };
   }
 }
 
+/**
+ * appendResponseEventIfKnown(cwd, sourcePromptId, text, meta) → Promise<boolean>
+ *
+ * Boolean-only wrapper around appendResponseEventWithReason, for every
+ * caller that only needs "did it go out", not why — notifyOriginatingTab's
+ * existing tab-external-ticket fallback stays keyed on this boolean.
+ */
+async function appendResponseEventIfKnown(cwd, sourcePromptId, text, meta = {}) {
+  const result = await appendResponseEventWithReason(cwd, sourcePromptId, text, meta);
+  return result.ok;
+}
+
 module.exports = {
   appendResponseEventIfKnown,
+  appendResponseEventWithReason,
   promptSessionActiveIndexPath,
   attachWindow,
   EVENT_APPENDED_CHANNEL,