claude-code-session-manager 0.98.0 → 0.101.0

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/projectPages.cjs

@@ -1,12 +1,15 @@
 'use strict';
 
 /**
- * projectPages.cjs — read-only backend for Project Home. The whole feature is
- * ONE self-contained HTML file, `session-manager-operations/project-pages/
- * home.html`, written by the `project_home_write` admin route
- * (lib/projectHomeAdminRoutes.cjs). This module only reads it: get() plus a
- * refcounted per-cwd watcher that pushes `project-pages:changed`. It never
- * writes content (watch()'s mkdir creates an empty directory only).
+ * projectPages.cjs — read-only backend for Project Home. Project Home has two
+ * self-contained generated artifacts under
+ * `session-manager-operations/project-pages/`: `home.html` (written by the
+ * `project_home_write` admin route) and `demo-video/index.html` (written by
+ * the `project_demo_video_write` admin route) — both in
+ * lib/projectHomeAdminRoutes.cjs. This module only reads them: get() returns
+ * home.html's content plus the demo video's { path, mtimeMs }, and a
+ * refcounted per-cwd watcher pushes `project-pages:changed` for either. It
+ * never writes content (watch()'s mkdir creates an empty directory only).
  */
 
 const { ipcMain } = require('electron');
@@ -26,6 +29,22 @@ function homePath(cwd) {
   return opsPath(cwd, 'project-pages', 'home.html');
 }
 
+function demoVideoPath(cwd) {
+  return opsPath(cwd, 'project-pages', 'demo-video', 'index.html');
+}
+
+/** -> { path: string, mtimeMs: number } | null */
+async function getDemoVideo(realCwd) {
+  const file = demoVideoPath(realCwd);
+  try {
+    const stat = await fs.promises.stat(file);
+    return { path: file, mtimeMs: stat.mtimeMs };
+  } catch (e) {
+    if (e.code === 'ENOENT') return null;
+    throw e;
+  }
+}
+
 /**
  * Resolve `cwd`'s home.html path, treating the opsOwnership "ephemeral cwd"
  * throw (a tmpdir/linked-worktree project root) as "no path available"
@@ -40,14 +59,15 @@ function tryHomePath(realCwd) {
   }
 }
 
-/** -> { html: string|null, mtimeMs: number|null } */
+/** -> { html: string|null, mtimeMs: number|null, demoVideo: {path, mtimeMs}|null } */
 async function get({ cwd }) {
   const realCwd = config.validatePath(cwd);
   const { file, ephemeral } = tryHomePath(realCwd);
-  if (ephemeral) return { html: null, mtimeMs: null };
+  if (ephemeral) return { html: null, mtimeMs: null, demoVideo: null };
   const res = await config.readText(file);
-  if (!res.exists) return { html: null, mtimeMs: null };
-  return { html: res.text, mtimeMs: res.mtimeMs };
+  const demoVideo = await getDemoVideo(realCwd);
+  if (!res.exists) return { html: null, mtimeMs: null, demoVideo };
+  return { html: res.text, mtimeMs: res.mtimeMs, demoVideo };
 }
 
 // ─── Push channel ─────────────────────────────────────────────────────────
@@ -90,21 +110,31 @@ async function watchOutput(cwd) {
   const dir = path.dirname(file);
   fs.mkdirSync(dir, { recursive: true });
 
+  const demoVideoFile = demoVideoPath(realCwd);
   const push = async (changedPath) => {
-    if (changedPath && path.resolve(changedPath) !== path.resolve(file)) return; // only home.html
+    // Only home.html or demo-video/index.html — ignore every other sibling file.
+    if (changedPath) {
+      const resolved = path.resolve(changedPath);
+      if (resolved !== path.resolve(file) && resolved !== path.resolve(demoVideoFile)) return;
+    }
     let result;
     try {
       result = await get({ cwd: realCwd });
     } catch {
       return; // best-effort; the renderer keeps its last-known output
     }
-    sendIfAlive(mainWindow, 'project-pages:changed', { cwd: realCwd, html: result.html, mtimeMs: result.mtimeMs });
+    sendIfAlive(mainWindow, 'project-pages:changed', {
+      cwd: realCwd,
+      html: result.html,
+      mtimeMs: result.mtimeMs,
+      demoVideo: result.demoVideo,
+    });
   };
 
   const watcher = chokidar.watch(dir, {
     ignoreInitial: true,
     persistent: true,
-    depth: 0,
+    depth: 1,
     // Same 50ms/25ms shape config.cjs's generic watcher uses.
     awaitWriteFinish: { stabilityThreshold: 50, pollInterval: 25 },
   });

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,