claude-code-session-manager 0.117.0 → 0.119.0

package/src/main/scheduler.cjs

@@ -99,7 +99,8 @@ const sessionsStore = require('./sessionsStore.cjs');
 const { enqueueExternalPrompt } = require('./chatRunner.cjs');
 const { appendResponseEventIfKnown, appendResponseEventWithReason } = require('./promptSessionEvents.cjs');
 const { buildReviewNotice, selectDueReviewNotices, formatReviewNotice, holdMsFromEnv } = require('./lib/scheduler/reviewNotice.cjs');
-const { maybeEnqueueValidationPrompt } = require('./lib/epic/epicValidationHook.cjs');
+const epicValidationHook = require('./lib/epic/epicValidationHook.cjs');
+const prdCreate = require('./lib/prd/prdCreate.cjs');
 const { parseValidationSentinels } = require('./lib/scheduler/validationSentinels.cjs');
 const { hasDownstreamValidator } = require('./lib/prd/planValidator.cjs');
 const promptSessionTranscript = require('./promptSessionTranscript.cjs');
@@ -3018,6 +3019,29 @@ async function resolveFixPlanPath(failedJob) {
   return { fixPath, fixSlug, group, livePrdDir };
 }
 
+/**
+ * defaultScheduleSettle — production wiring for notifyOriginatingTab's
+ * scheduleSettle option: arms the debounced Epic settle runner with live deps.
+ * `remote` is defined later in the module but only read at call time.
+ */
+function defaultScheduleSettle({ cwd, epicId }) {
+  const deps = {
+    loadJobs: async () => (await readQueue()).jobs || [],
+    loadHistory: () => queueHistory.readHistory({ limit: 500 }),
+    createPrd: (input) => prdCreate.createPrd(input, remote),
+    resolveBaseSha: async (c, commit) => {
+      try {
+        return String(await execGitAt(c, ['rev-parse', `${commit}^`])).trim() || null;
+      } catch {
+        return null;
+      }
+    },
+    sendPrompt: enqueueExternalPrompt,
+    appendResponseEvent: appendResponseEventIfKnown,
+  };
+  epicValidationHook.scheduleEpicSettle({ cwd, epicId }, (args) => epicValidationHook.runEpicSettle(args, deps));
+}
+
 /**
  * notifyOriginatingTab(job) → void
  *
@@ -3056,12 +3080,7 @@ async function notifyOriginatingTab(job, {
   appendResponseEvent = appendResponseEventIfKnown,
   appendTranscriptTurn = promptSessionTranscript.appendTurn,
   readResultFromLog = extractResultTextFromLog,
-  enqueueValidation = maybeEnqueueValidationPrompt,
-  // PRD 1408: same queue rows spawnJob/tickQueue already use — read fresh
-  // here (not threaded through the terminal-transition snapshot) since this
-  // fires well after dispatch, when the plan may have gained/dropped a
-  // trailing validator row since this job was spawned.
-  loadJobs = async () => (await readQueue()).jobs || [],
+  scheduleSettle = defaultScheduleSettle,
 } = {}) {
   try {
     const prd = await resolveNotifyPrd(job, parsePrdRaw);
@@ -3174,55 +3193,22 @@ async function notifyOriginatingTab(job, {
         prdSlug: job.slug,
         outcome: job.status,
         validation: 'unvalidated',
+        ...(typeof job.agentType === 'string' ? { agentType: job.agentType } : {}),
       }).catch((e) => {
         console.error('[scheduler] notifyOriginatingTab appendResponseEvent error', job?.slug, e);
         return false;
       });
       if (routed) {
-        // PRD 986: a successful check-in append triggers ONE validation
-        // prompt into the authoring Epic's own session, asking it to verify
-        // every acceptance criterion against the real working tree and reply
-        // VERIFIED or REFUTED. Fire-and-forget, same convention as this
-        // function's own call site in tickQueue: a failure to enqueue is
-        // logged inside the hook, never thrown, and never blocks the job's
-        // status transition or the response-event append (which already
-        // happened above). All gating (kill-switch SM_EPIC_VALIDATION_DISABLE,
-        // active-Epic check, once-per-(epicId, prdSlug), loop guard, slot-pool
-        // routing) lives in lib/epic/epicValidationHook.cjs.
-        //
-        // PRD 1407: a validator job's own check-in never enqueues a
-        // validation prompt for itself — it IS the plan's validation pass,
-        // not a work-item awaiting one.
-        //
-        // PRD 1408: nor does an ordinary work-item whose plan already ends in
-        // a trailing validator job depending on it — that validator's own
-        // check-in (above) is the single validation pass for the whole plan,
-        // so a per-PRD prompt here would be a second, redundant ask into the
-        // same (Opus/Fable-tier) authoring session.
-        if (job.agentType !== 'validator') {
-          let skipForDownstreamValidator = false;
-          try {
-            skipForDownstreamValidator = hasDownstreamValidator(job, await loadJobs());
-          } catch (e) {
-            console.error('[scheduler] notifyOriginatingTab loadJobs error', job?.slug, e);
-          }
-          if (!skipForDownstreamValidator) {
-            try {
-              enqueueValidation(
-                {
-                  cwd: job.cwd || null,
-                  epicId,
-                  prdSlug: job.slug,
-                  prdPath: prd?.path || prdPaths.archivedPrdPathForJob(job) || null,
-                  outcome: job.status,
-                  eventValidation: 'unvalidated',
-                },
-                { sendPrompt },
-              );
-            } catch (e) {
-              console.error('[scheduler] notifyOriginatingTab enqueueValidation error', job?.slug, e);
-            }
-          }
+        // The debounced Epic settle runner (lib/epic/epicValidationHook.cjs)
+        // owns all validation messaging now (replaces the per-PRD prompts of
+        // PRDs 986/1407/1408): every successful terminal check-in, a
+        // validator's own included (its finish usually settles the Epic),
+        // just re-arms the per-Epic debounce. A finished PRD never sends a
+        // chat prompt into its authoring Epic by itself.
+        try {
+          scheduleSettle({ cwd: job.cwd || null, epicId });
+        } catch (e) {
+          console.error('[scheduler] notifyOriginatingTab scheduleSettle error', job?.slug, e);
         }
         return;
       }
@@ -6456,17 +6442,10 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null, sib
     let mechanicalRecoveryTarget = null;
     let terminalNotifySnapshot = null;
     const newlyCompletedPrds = [];
-    // PRD 1408: captured inside the mutate() below (the one in-memory read of
-    // `s.jobs` this finalize pass already does) so notifyOriginatingTab's own
-    // hasDownstreamValidator check can reuse it instead of a second, redundant
-    // readQueue() — that call federates queue.json shards across every known
-    // project cwd on the machine, not just this job's own project.
-    let jobsSnapshotForNotify = null;
     // Base HEAD for the mechanical-recovery futility check — read here, never inside mutate() (no I/O).
     const finalizeHeadSha = worktreeIntegrationDetail && worktreeIntegrationDetail.failureKind === 'content_conflict'
       ? await gitTreeGuard.gitHead(guardCwd) : null;
     await mutate((s) => {
-      jobsSnapshotForNotify = s.jobs.slice();
       const i2 = s.jobs.findIndex((x) => x.slug === job.slug);
       // A job already moved off 'running' by someone else (namely
       // remote.cancelJob, PRD 1024 — it SIGTERMs the process then finalizes
@@ -6883,9 +6862,7 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null, sib
     });
 
     if (terminalNotifySnapshot) {
-      notifyOriginatingTab(terminalNotifySnapshot, {
-        loadJobs: async () => jobsSnapshotForNotify || [],
-      }).catch((e) => {
+      notifyOriginatingTab(terminalNotifySnapshot).catch((e) => {
         console.error('[scheduler] notifyOriginatingTab error', job.slug, e);
       });
     }

package/src/main/templates/PRD_AUTHORING.md

@@ -1,4 +1,4 @@
-<!-- PRD_AUTHORING.md v5 -->
+<!-- PRD_AUTHORING.md v6 -->
 # PRD Authoring Guide — Scheduler Safety Rules
 
 Rule: every PRD you queue follows the rules below.
@@ -125,6 +125,9 @@ A short Epic-context digest is prepended automatically for orientation only —
 
 The executor can't ask you anything: no `ScheduleWakeup`, Cron, Monitor, `AskUserQuestion`, plan mode, or worktree tools; background tasks are off (a `timeout` command is always on PATH — the app installs a shim on macOS). It must never stop to ask a question — it makes the safest reasonable call and reports it, so write the PRD so that call is obvious.
 
+Worktree reach: every PRD runs in an isolated git worktree holding tracked files plus symlinked `node_modules`/`.venv`/`venv` only. A step that needs gitignored runtime state (databases, `downloads/`, browser profiles, logs) or a live side effect must address the main checkout by absolute path (e.g. `$HOME/Projects/<repo>/...`), be artifact-only (a deliverable artifact + `artifactPaths`, no tracked edits), and `dependsOn` the PRD that lands its tracked edits. Host crontab installs stay human-only (see §15).
+Why: burrow PRD 1516 halted because its relative `.venv` python against `downloads/fb-tracker.db`, `scripts/install-cron.sh` and `pipeline-cron.sh --now` resolved inside the worktree (no runtime state; install-cron would bake a temporary worktree path into crontab), while sibling 1494 succeeded the same day using an absolute main-checkout path and artifact-only output. `scheduler_create_prd` warns on relative gitignored paths.
+
 ---
 
 ## §8 Scope sizing — target ≤10 min, ceiling 15
@@ -228,6 +231,7 @@ Before queueing a new PRD, verify each of these:
 - [ ] **§5 Frontmatter:** `title`, `cwd` (exists on this machine), `estimateMinutes` present; `dependsOn` used for ordering, not `parallelGroup`.
 - [ ] **§6 Gate and files:** `gate` follows every rule in §6 (or is `["none"]` alone); `files` is 1–50 repo-relative paths, no overlap with a concurrent PRD.
 - [ ] **§7 Self-contained:** no reference to "the conversation" or outside context; paths/identifiers inline; clean UTF-8, no NUL bytes (`grep -qP '\x00' file && echo BAD`).
+- [ ] **§7 Worktree reach:** no relative path to a gitignored file; live-run steps use absolute main-checkout paths in an artifact-only PRD. Why: the job worktree has no gitignored runtime state, so relative paths fail or bake a temporary path into host config (burrow 1516).
 - [ ] **§8 Scope:** targets ≤10 min, ceiling 15; e2e/publish sharded to one spec per PRD.
 - [ ] **§9 Failure surfacing:** errors exit 1 with a diagnostic line; no silent `|| true`.
 - [ ] **§10 Negative assertions:** every "should find nothing" check is inverted to exit 0 on the clean case.

package/src/main/webRemote.cjs

@@ -53,6 +53,8 @@ const BACKOFF_MULT = 2;
 
 // Heartbeat (ADR §2.3)
 const PING_INTERVAL_MS = 30_000;
+// Relay sends protocol pings every 30s; 100s = just over 3 missed beats.
+const RELAY_PING_SILENCE_MS = 100_000;
 const PONG_TIMEOUT_MS = 10_000;
 const MAX_MISSED_PONGS = 3;
 
@@ -81,6 +83,7 @@ let _backoffMs = BACKOFF_INIT_MS;
 let _pingTimer = null;
 let _pongTimer = null;
 let _missedPongs = 0;
+let _lastRelayPingAt = 0; // last protocol-level relay ping (or socket open)
 let _configCache = null;
 let _configCacheAt = 0;
 let _repairNeeded = false; // relay rejected the device token (invalid_token / 401): terminal until re-pair
@@ -308,10 +311,26 @@ function stopHeartbeat() {
   if (_pongTimer) { clearTimeout(_pongTimer); _pongTimer = null; }
 }
 
+// The relay can evict a live conn from its device map (stale close of a prior
+// socket). App-level pongs still arrive, but protocol pings stop — terminate so
+// the close handler reconnects and re-registers.
+function checkRelayLiveness(now = Date.now()) {
+  if (!_ws || _ws.readyState !== WebSocket.OPEN) return false;
+  if (_lastRelayPingAt <= 0 || now - _lastRelayPingAt <= RELAY_PING_SILENCE_MS) return false;
+  logs.writeLine({
+    scope: 'webRemote', level: 'warn',
+    message: 'relay heartbeat silent — reconnecting',
+    meta: { silentMs: now - _lastRelayPingAt },
+  });
+  _ws.terminate();
+  return true;
+}
+
 function startHeartbeat() {
   stopHeartbeat();
   _pingTimer = setInterval(() => {
     if (!_ws || _ws.readyState !== WebSocket.OPEN) { stopHeartbeat(); return; }
+    if (checkRelayLiveness()) return;
     const pingId = crypto.randomUUID();
     _ws.send(JSON.stringify({ type: 'ping', id: pingId, ts: Date.now() }));
     _pongTimer = setTimeout(() => {
@@ -429,6 +448,7 @@ async function connect() {
     logs.writeLine({ scope: 'webRemote', level: 'info', message: 'connected to relay' });
     _backoffMs = BACKOFF_INIT_MS;
     _missedPongs = 0;
+    _lastRelayPingAt = Date.now();
     startHeartbeat();
     // Update lastConnectedAt without exposing token
     invalidateConfigCache(); // a pin written since the last cached read must not be overwritten
@@ -481,7 +501,10 @@ async function connect() {
   // too. This keeps the session up even if the relay ever stops answering the
   // app-level pings (the exact failure that silently dropped sessions every ~100s
   // before the relay learned to pong). node 'ws' auto-replies to the ping itself.
-  ws.on('ping', () => { _missedPongs = 0; });
+  // It is also the orphaned-conn signal: the relay's stale close of a previous
+  // socket can evict this live conn from its map, after which only app-level
+  // pongs arrive and relay protocol pings stop (see checkRelayLiveness).
+  ws.on('ping', () => { _missedPongs = 0; _lastRelayPingAt = Date.now(); });
 }
 
 async function handleTokenRevoked(deviceId) {
@@ -1550,6 +1573,9 @@ module.exports = {
     getDispatchMap,
     buildRemoteSessionList,
     setWs: (ws) => { _ws = ws; },
+    checkRelayLiveness,
+    setLastRelayPingAt: (ts) => { _lastRelayPingAt = ts; },
+    RELAY_PING_SILENCE_MS,
     connect,
     hasReconnectTimer: () => _reconnectTimer !== null,
     cancelReconnect,