moflo 4.12.6 → 4.12.8

package/bin/gate.cjs

@@ -13,7 +13,7 @@ var STATE_FILE = path.join(PROJECT_DIR, '.claude', 'workflow-state.json');
 // the code it describes, so a change made outside Write/Edit/MultiEdit (a Bash
 // write, a branch switch, the next issue in the same session) invalidates it.
 // See creditFingerprint() for why the boolean flags alone cannot.
-var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, testsFingerprint: null, simplifyRun: false, simplifySnapshotSha: null, simplifyFingerprint: null, verifyRun: false, verifyOutcome: null, verifyFingerprint: null, interactionCount: 0, sessionStart: null, lastBlockedAt: null, lastNamespaceHint: '', lastNamespaceHintEmittedBy: {}, flMode: null, swarmInitialized: false, hiveInitialized: false, sddMode: false, activeSddSlug: null };
+var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, tasksAcknowledged: false, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, testsFingerprint: null, simplifyRun: false, simplifySnapshotSha: null, simplifyFingerprint: null, verifyRun: false, verifyOutcome: null, verifyFingerprint: null, interactionCount: 0, sessionStart: null, lastBlockedAt: null, lastNamespaceHint: '', lastNamespaceHintEmittedBy: {}, flMode: null, swarmInitialized: false, hiveInitialized: false, sddMode: false, activeSddSlug: null };
 
 // Per-actor memory-search tracking (#838). The legacy `memorySearched` boolean
 // is session-wide, so once the parent searches memory, every spawned subagent
@@ -70,9 +70,24 @@ function loadGateConfig() {
   // ships a real /verify skill and has /flo delegate to it, so leaving it off by
   // default would make the default /flo run silently skip the acceptance check.
   // Disable per-project with `verify_before_done: false` or per-run `--no-verify`.
-  var defaults = { memory_first: true, task_create_first: true, context_tracking: true, testing_gate: true, simplify_gate: true, learnings_gate: true, swarm_invocation_gate: true, verify_before_done: true, sdd_gate: true };
+  // task_status_gate is a MODE, not a boolean: 'block' | 'warn' | 'off' (#1435).
+  // #1374 shipped the open-task count as a warn-only stdout line, and a consumer
+  // still shipped a PR over four untouched tasks — a reminder that survived ten
+  // consecutive ignores in one session is not a control. Blocking is the default
+  // because the honest "these stay open on purpose" outcome is one command away
+  // (record-tasks-acknowledged), so nothing here can deadlock a run.
+  var defaults = { memory_first: true, task_create_first: true, context_tracking: true, testing_gate: true, simplify_gate: true, learnings_gate: true, swarm_invocation_gate: true, verify_before_done: true, sdd_gate: true, task_status_gate: 'block' };
   var content = MOFLO_YAML;
   if (content) {
+    // Boolean forms are accepted so this key reads like every other gate in the
+    // block: `false` is the same opt-out `testing_gate: false` is, `true` means
+    // enforce. Anything unrecognised falls through to the default rather than
+    // silently disabling the gate — a typo must not be a stealth opt-out.
+    var tsg = /task_status_gate:\s*['"]?(block|warn|off|false|true)['"]?/i.exec(content);
+    if (tsg) {
+      var mode = tsg[1].toLowerCase();
+      defaults.task_status_gate = mode === 'false' ? 'off' : mode === 'true' ? 'block' : mode;
+    }
     if (/memory_first:\s*false/i.test(content)) defaults.memory_first = false;
     if (/task_create_first:\s*false/i.test(content)) defaults.task_create_first = false;
     if (/context_tracking:\s*false/i.test(content)) defaults.context_tracking = false;
@@ -172,6 +187,25 @@ var GATE_ORIGIN_NOTE = 'This is a moflo hook, not a Claude Code permission rule
 // /verify's Step 5 memory_store carries the verdict AND stamps learnings, which
 // is why learnings has no separate step here.
 var ORDER_HINT = 'Order that satisfies all of them: tests green -> /flo-simplify (re-run tests if it edits) -> /verify -> its memory_store verdict -> gh pr create\n';
+// #1434 — the old text ('learnings have not been stored (call memory_store)')
+// named the mechanism but no quality bar, so the cheapest way past it was a
+// summary of the run — audit exhaust that displaces reusable lessons from every
+// future bounded search. Name the bar AND the no-write path here: an escape
+// hatch nobody can find is not an escape hatch (see #1332's gate deadlock).
+//
+// The escape command is built from __filename, not written as a relative path.
+// The caller is the model typing into a Bash tool, NOT a hook: $CLAUDE_PROJECT_DIR
+// is unset there (so the settings.json form would expand to "/.claude/..."), and a
+// bare `.claude/helpers/gate.cjs` breaks from any cwd but the project root. The
+// running script's own absolute path is correct on every OS and from any cwd;
+// double quotes carry Windows separators and spaces through the shell.
+var LEARNINGS_MISSING =
+  'no durable lesson recorded. A lesson qualifies only if it would help a future session ' +
+  'working on a DIFFERENT task — a reusable pattern, a trap, a decision + rationale. ' +
+  'Store one with mcp__moflo__memory_store (namespace "learnings"; use "patterns" for a ' +
+  'reusable code shape). What THIS run changed is git history — it belongs in the PR body, ' +
+  'not in memory. If this run taught nothing new, say so instead of inventing one: ' +
+  'node "' + __filename + '" record-no-durable-lesson';
 var GATE_DISABLE_NOTE = 'Disable per-gate via moflo.yaml: gates: memory_first: false';
 // #1338 — Claude Code spawns stdio MCP servers once at session start and never
 // respawns them, so a session can outlive its moflo MCP connection. Naming only
@@ -1355,6 +1389,41 @@ switch (command) {
     writeState(s);
     break;
   }
+  // #1435 — the escape from the task-status gate, for work deliberately left
+  // open. Session-scoped like `learningsStored`: it lives in STATE_DEFAULTS, so
+  // session-reset clears it, and neither applyPromptStateReset nor
+  // reset-edit-gates touches it — a decision the user made about the task list
+  // is not invalidated by the next prompt or the next source edit.
+  //
+  // A plain flag, not a count. The command is typed by the model into a Bash
+  // tool, where HOOK_TRANSCRIPT_PATH is unset (it is forwarded by gate-hook.mjs
+  // from the hook payload and exists only inside a hook), so this process cannot
+  // read the ledger to record WHICH tasks were acknowledged even if it wanted to.
+  case 'record-tasks-acknowledged': {
+    var s = readState();
+    if (!s.tasksAcknowledged) {
+      s.tasksAcknowledged = true;
+      writeState(s);
+    }
+    // writeState swallows its own errors by design — a gate must never crash the
+    // hook it runs in. That was harmless while every recorder was advisory. This
+    // one is the ONLY escape from a BLOCKING gate, so a lost write would report
+    // "satisfied" and then block the very next `gh pr create` with nothing said
+    // about why: #1332's deadlock shape exactly. Confirm it landed before
+    // claiming it did, and name the file and the way out when it did not.
+    if (!readState().tasksAcknowledged) {
+      process.stderr.write(
+        'Task-status gate NOT satisfied: the acknowledgement could not be persisted to\n' +
+        STATE_FILE + '\n' +
+        'Check that the file and its directory are writable, then run this again.\n' +
+        'To proceed without it: set gates: task_status_gate: off in moflo.yaml.\n');
+      process.exit(1);
+    }
+    process.stdout.write(
+      'Task-status gate satisfied: open tasks acknowledged as deliberately deferred.\n' +
+      'They stay visible in the task list — this records the decision, it does not close them.\n');
+    break;
+  }
   case 'record-memory-searched': {
     var s = readState();
     if (markMemorySearched(s)) writeState(s);
@@ -1417,12 +1486,48 @@ switch (command) {
     // Why it does nothing: see applyPromptStateReset().
     break;
   }
-  case 'record-learnings-stored': {
+  // #1434 — the gate demanded one memory_store per run whether or not the run
+  // produced a reusable lesson, and a mandatory write with nothing to say
+  // produces filler: a summary of this ticket, this commit, applicable never
+  // again. memory_search returns a bounded set, so each of those displaces a
+  // real lesson from every future search — the cost is retrieval quality, not
+  // disk. Declaring "nothing durable here" is the honest outcome of a run that
+  // learned nothing new, so it has to be reachable without a write; otherwise
+  // the cheapest way past the gate stays the filler write.
+  //
+  // Both credits set the same flag; they differ only in whether the run has
+  // something to say. Sharing the case body keeps that single write in one
+  // place across all three copies of this file.
+  case 'record-learnings-stored':
+  case 'record-no-durable-lesson': {
     var s = readState();
     if (!s.learningsStored) {
       s.learningsStored = true;
       writeState(s);
     }
+    if (command === 'record-no-durable-lesson') {
+      // Same reasoning as record-tasks-acknowledged above: writeState swallows
+      // its own errors so a gate never crashes the hook it runs in, and this is
+      // the ONLY escape from the BLOCKING learnings gate that does not require a
+      // memory_store. A lost write here would print "satisfied" and then block
+      // the next `gh pr create` with nothing said about why — #1332's deadlock.
+      // Verified only on this arm: record-learnings-stored is fired
+      // automatically by the PostToolUse hook on every memory_store, where a
+      // failed write leaves the gate closed but the run still has the ordinary
+      // way through, and a diagnostic on every store would be noise.
+      if (!readState().learningsStored) {
+        process.stderr.write(
+          'Learnings gate NOT satisfied: the declaration could not be persisted to\n' +
+          STATE_FILE + '\n' +
+          'Check that the file and its directory are writable, then run this again.\n' +
+          'To proceed without it: set gates: learnings_gate: false in moflo.yaml.\n');
+        process.exit(1);
+      }
+      process.stdout.write(
+        'Learnings gate satisfied: no durable lesson declared for this run.\n' +
+        'What this run did belongs in the PR body, not in memory.\n',
+      );
+    }
     break;
   }
   case 'record-test-run': {
@@ -1645,25 +1750,46 @@ switch (command) {
     // chained, piped, parenthesised, and multi-line shapes (#1410).
     var cmd = process.env.TOOL_INPUT_command || '';
     if (!isPrCreateCommand(cmd)) break;
-    // #1374 — close the loop the TaskCreate reminder opens. Advisory: stdout,
-    // no exit, and worded as a reminder, because a message may only claim to
-    // block when it blocks (#1326). An open task list is a reporting failure,
-    // not a quality failure — blocking the PR on it would be a new deadlock.
+    // #1374 opened this loop; #1435 closes it. The count itself is unchanged —
+    // what changed is that it now has teeth and, in warn mode, a delivery path.
     //
     // Deliberately ABOVE the no-source exemption below: a docs-only PR can
     // abandon a list exactly like a source PR can, and the exemption is about
     // testing/simplify/learnings, not about whether the run told the user what
-    // it did. Gated on the same `task_create_first` flag as the reminder itself
-    // so the two halves are always consistent — a project that turned the nag
-    // off is not then nagged about the other end of it.
-    if (config.task_create_first) {
+    // it did. It also exits on its own rather than joining `missing` below, for
+    // the same reason — `missing` is unreachable on an exempt diff.
+    //
+    // Gated on the same `task_create_first` flag as the reminder itself so the
+    // two halves are always consistent: a project that turned the nag off is
+    // not then blocked about the other end of it.
+    //
+    // Fail-open is load-bearing. readTaskLedger() returns null on a missing,
+    // oversized, or unreadable transcript and on a session with no TaskCreate at
+    // all, and null must never block — a gate that stops PRs because it could
+    // not read a file is worse than the reporting gap it is closing.
+    //
+    // State is read ONCE for the whole case, here — the pre-PR gate logic below
+    // reuses it and nothing writes in between. Reading it before the ledger also
+    // means an already-acknowledged run never pays for the transcript scan.
+    var s = readState();
+    if (config.task_create_first && config.task_status_gate !== 'off' && !s.tasksAcknowledged) {
       var ledger = readTaskLedger();
       if (ledger && ledger.open > 0) {
-        process.stdout.write(
-          'REMINDER: ' + ledger.created + ' task' + (ledger.created === 1 ? '' : 's') +
-          ' created this session, ' + ledger.open + ' still open. Close them with ' +
-          'TaskUpdate (status: completed), or delete the ones that no longer apply, ' +
-          'so the run does not report done over an unfinished list.\n');
+        var tally = ledger.created + ' task' + (ledger.created === 1 ? '' : 's') +
+          ' created this session, ' + ledger.open + ' still open.';
+        var closeIt = 'Close them with TaskUpdate (status: completed), or delete the ones ' +
+          'that no longer apply, so the run does not report done over an unfinished list.\n';
+        if (config.task_status_gate === 'warn') {
+          process.stdout.write('REMINDER: ' + tally + ' ' + closeIt);
+        } else {
+          process.stderr.write(
+            'BLOCKED: ' + tally + '\n' + closeIt +
+            'Deferring them on purpose is a legitimate outcome — declare it instead of\n' +
+            'closing tasks that are not done: node "' + __filename + '" record-tasks-acknowledged\n' +
+            GATE_ORIGIN_NOTE + '\n' +
+            'Report instead of blocking via moflo.yaml: gates: task_status_gate: warn   (or: off)\n');
+          process.exit(2);
+        }
       }
     }
     // No-source-files exemption (#1176, supersedes the original docs-only path).
@@ -1688,7 +1814,6 @@ switch (command) {
         break;
       }
     }
-    var s = readState();
     // Expire any credit whose fingerprint no longer matches the code before
     // reading the flags. This is what catches the mutations reset-edit-gates
     // structurally cannot see — Bash writes, git checkout/pull/merge, and the
@@ -1721,7 +1846,7 @@ switch (command) {
     var missing = [];
     if (config.testing_gate && !s.testsRun) missing.push('tests have not run green since the last code edit (run npm test, vitest, jest, pytest, or similar — a run whose output reports failures does not count)');
     if (config.simplify_gate && !s.simplifyRun) missing.push('/flo-simplify (or /distill) has not run since the last code edit');
-    if (config.learnings_gate && !s.learningsStored) missing.push('learnings have not been stored (call mcp__moflo__memory_store)');
+    if (config.learnings_gate && !s.learningsStored) missing.push(LEARNINGS_MISSING);
     if (missing.length === 0) break;
     process.stderr.write('BLOCKED: gh pr create requires the following before opening a PR:\n');
     for (var i = 0; i < missing.length; i++) {

package/bin/lib/hook-io.mjs

@@ -26,9 +26,26 @@ export async function readHookStdin() {
     let done = false;
     let timer = null;
     const parse = (s) => { try { return s ? JSON.parse(s) : {}; } catch { return {}; } };
-    const finish = () => { if (done) return; done = true; if (timer) clearTimeout(timer); res(parse(data)); };
+    const onData = (c) => { if (!done) data += c; };
+    // Detach and pause on the way out. Without this the 500ms cap is a lie for
+    // any caller that keeps running afterwards: the listeners stay attached and
+    // a flowing stdin keeps the event loop alive well past the timeout. It was
+    // invisible while every caller exited immediately after reading; #1441 made
+    // the session-start launcher the first caller with real work left to do.
+    const finish = () => {
+      if (done) return;
+      done = true;
+      if (timer) clearTimeout(timer);
+      try {
+        process.stdin.off('data', onData);
+        process.stdin.off('end', finish);
+        process.stdin.off('error', finish);
+        process.stdin.pause();
+      } catch { /* teardown must never outrank returning the payload */ }
+      res(parse(data));
+    };
     process.stdin.setEncoding('utf-8');
-    process.stdin.on('data', (c) => { if (!done) data += c; });
+    process.stdin.on('data', onData);
     process.stdin.on('end', finish);
     process.stdin.on('error', finish);
     timer = setTimeout(finish, 500);

package/bin/session-start-launcher.mjs

@@ -19,6 +19,7 @@ import { makeSyncer, contentEqual, syncDirRecursive } from './lib/file-sync.mjs'
 import { INTERNAL_SKILLS } from './lib/internal-skills.mjs';
 import { parseSkillCategories, computeExcludedSkills } from './lib/skill-categories.mjs';
 import { loadShippedScripts } from './lib/shipped-scripts.mjs';
+import { readHookStdin } from './lib/hook-io.mjs';
 import {
   readContinuityConfig,
   readGitState,
@@ -651,7 +652,7 @@ function stopDaemon(lockFile) {
     // error 'process can only be terminated forcefully'. The prior
     // implementation invoked it anyway, swallowed the error, then polled
     // alive for 3s before escalating — exactly the time-waste that pushed
-    // §3's stopDaemon past the 3000ms SessionStart hook timeout. Go
+    // §3's stopDaemon past the SessionStart hook timeout. Go
     // straight to /F /T (tree-kill, in case a worker child outlived its
     // parent) on Win.
     if (process.platform === 'win32') {
@@ -753,23 +754,155 @@ function resolveDaemonRecyclerPath() {
 }
 
 // ── 2. Reset workflow state for new session ──────────────────────────────────
-const stateDir = resolve(projectRoot, '.claude');
-const stateFile = resolve(stateDir, 'workflow-state.json');
-try {
-  if (!existsSync(stateDir)) mkdirSync(stateDir, { recursive: true });
-  writeFileSync(stateFile, JSON.stringify({
+//
+// #1441 — reset on a NEW session only. Claude Code fires SessionStart with a
+// `source` of `startup`, `resume`, `clear` or `compact`, and moflo's settings
+// entry carries no matcher, so this launcher runs for all four. A compaction
+// is the SAME session continuing with a shorter context; a resume is the same
+// session reopened. Resetting there wiped gate state mid-run, two ways:
+//
+//   1. `flMode` and `sddMode` are derived ONLY from the user's prompt text
+//      (gate.cjs applyPromptStateReset). Clearing them turned the #952
+//      swarm/hive invocation gate and the #1297 SDD gate OFF for the rest of
+//      the run — the user's next prompt is ordinary prose, so nothing ever
+//      re-armed them. A `/fl -s` run that compacted stopped enforcing
+//      swarm_init before Agent spawns, silently.
+//   2. testsRun / simplifyRun / verifyRun / learningsStored and their
+//      fingerprints were discarded, so a compaction forced a full re-run of
+//      tests, /flo-simplify and /verify before `gh pr create`.
+//
+// Unknown, absent, or unparseable source resets — byte-identical to the old
+// behaviour on a host that doesn't send the field, and the safe direction
+// (gates armed rather than silently off).
+const CONTINUING_SESSION_SOURCES = new Set(['compact', 'resume']);
+const KNOWN_SESSION_SOURCES = new Set(['startup', 'clear', 'compact', 'resume']);
+
+// …but a compaction is NOT a pure "keep everything" either. The credits above
+// describe work that still stands — tests ran, /verify passed, the diff is
+// unchanged. The memory-search credit is the one thing compaction genuinely
+// invalidates: `memorySearched` says "this actor has the search results in
+// context", and after a compaction it does not. Preserving it would hand the
+// post-compaction model a satisfied memory gate over a context that no longer
+// holds a single result — the exact "moflo isn't being used" symptom, arrived
+// at from the opposite direction.
+//
+// `memoryRequired` is re-armed for the same reason, and it also closes a second
+// hole reported against #1441: gate.cjs derives `memoryRequired` from the user's
+// prompt TEXT, and `/compact` is an 8-character non-task string, so submitting it
+// set `memoryRequired: false` and the scan/read gates went quiet until some later
+// prompt happened to qualify. SessionStart fires AFTER that UserPromptSubmit, so
+// re-arming here corrects it — and unlike a prompt-text rule it also covers AUTO
+// compaction, where no `/compact` is ever typed.
+//
+// Resume is untouched by this: it reloads the conversation, so a prior search is
+// still in context.
+//
+// Forcing `memoryRequired` on is deliberate even when the pre-compaction prompt
+// was genuinely trivial and scored false on its own merits. One memory search is
+// cheap; a context-blind model exploring files with the gate disarmed is the
+// thing this whole issue is about.
+const MEMORY_CREDIT_KEYS = ['memorySearched', 'memorySearchedBy', 'memoryRequired'];
+
+// Full shape, not the 4-field literal this used to write. gate.cjs readState()
+// merges STATE_DEFAULTS over whatever it parses, so the short shape behaved
+// identically THERE — but it left a half-populated file for every other reader
+// of workflow-state.json, and it silently drifted from STATE_DEFAULTS each time
+// a gate field was added. tests/bin/launcher-1441-compact-preserves-state.test.ts
+// pins these keys to gate.cjs's STATE_DEFAULTS so they cannot drift apart again.
+function freshWorkflowState() {
+  return {
     tasksCreated: false,
     taskCount: 0,
+    tasksAcknowledged: false,
     memorySearched: false,
-    sessionStart: new Date().toISOString()
-  }, null, 2));
-} catch {
-  // Non-fatal - workflow gate will use defaults
+    memorySearchedBy: {},
+    memoryRequired: true,
+    learningsStored: false,
+    testsRun: false,
+    testsFingerprint: null,
+    simplifyRun: false,
+    simplifySnapshotSha: null,
+    simplifyFingerprint: null,
+    verifyRun: false,
+    verifyOutcome: null,
+    verifyFingerprint: null,
+    interactionCount: 0,
+    sessionStart: new Date().toISOString(),
+    lastBlockedAt: null,
+    lastNamespaceHint: '',
+    lastNamespaceHintEmittedBy: {},
+    flMode: null,
+    swarmInitialized: false,
+    hiveInitialized: false,
+    sddMode: false,
+    activeSddSlug: null,
+  };
+}
+
+// Derived from freshWorkflowState(), not a second literal: a re-armed memory
+// gate is by definition the fresh-session value of those keys, and one place to
+// change beats two that agree only by inspection.
+function rearmedMemoryState() {
+  const fresh = freshWorkflowState();
+  return Object.fromEntries(MEMORY_CREDIT_KEYS.map((key) => [key, fresh[key]]));
+}
+
+// Bounded at 500ms by readHookStdin and short-circuited on a TTY, so a withheld
+// stdin cannot eat the 5000ms SessionStart budget (hook-block-hash.ts). Read
+// here rather than at the top of the file so the cost lands next to its only
+// consumer.
+const hookPayload = await readHookStdin();
+const sessionSource = typeof hookPayload?.source === 'string' ? hookPayload.source : '';
+// A source we don't recognise still resets — but say so. Falling through in
+// silence is how a renamed or newly-added "continuing" source would re-open
+// this bug with nothing to notice it by; the reset is only the safe default
+// while the set above is accurate.
+if (sessionSource && !KNOWN_SESSION_SOURCES.has(sessionSource)) {
+  emitWarning(
+    `unrecognized SessionStart source "${sessionSource}" — resetting workflow state. ` +
+    'If this source continues an existing session, it belongs in §2\'s skip list (#1441).',
+  );
+}
+const stateDir = resolve(projectRoot, '.claude');
+const stateFile = resolve(stateDir, 'workflow-state.json');
+if (!CONTINUING_SESSION_SOURCES.has(sessionSource)) {
+  try {
+    if (!existsSync(stateDir)) mkdirSync(stateDir, { recursive: true });
+    writeFileSync(stateFile, JSON.stringify(freshWorkflowState(), null, 2));
+  } catch {
+    // Non-fatal - workflow gate will use defaults
+  }
+} else if (sessionSource === 'compact') {
+  // Merge, never rewrite: everything the run has earned stays, only the memory
+  // credit is re-armed. Skipped entirely when there is no state file yet — a
+  // compaction before any prompt has nothing to re-arm, and writing a partial
+  // file here would defeat freshWorkflowState()'s shape guarantee.
+  //
+  // Read-modify-write, unsynchronised, like gate.cjs's own writeState. Safe
+  // here because a compaction quiesces the session: no tool hook is mid-flight
+  // to race with, and the next UserPromptSubmit is strictly after this hook.
+  // Leaving an unparseable file alone is also correct rather than merely
+  // tolerable — gate.cjs readState() falls back to STATE_DEFAULTS on a parse
+  // failure, which arms the memory gate. Repairing it here would only convert a
+  // fail-safe into an equivalent write.
+  try {
+    if (existsSync(stateFile)) {
+      const parsed = JSON.parse(readFileSync(stateFile, 'utf-8'));
+      writeFileSync(
+        stateFile,
+        JSON.stringify({ ...parsed, ...rearmedMemoryState() }, null, 2),
+      );
+    }
+  } catch (err) {
+    // Non-fatal, but not silent (#854): a failure here leaves the memory gate
+    // credited over a context that no longer holds the results.
+    emitWarning(`could not re-arm the memory gate after compaction (${errMessage(err)})`);
+  }
 }
 
 // ── 2a. Recycle daemon when behind installed version (#1054 follow-up) ──────
 // Promoted from §3a-pre to run BEFORE §3's file-sync work. The launcher has
-// a 3000ms SessionStart hook timeout (src/cli/services/hook-block-hash.ts);
+// a 5000ms SessionStart hook timeout (src/cli/services/hook-block-hash.ts);
 // §0c (DB repair) + §3 (file-sync, manifest, cherry-pick) + stopDaemon's
 // up-to-4s graceful poll routinely exceeds it on upgrade sessions, killing
 // the launcher mid-§3. Result: §3a-pre never ran on the very sessions that
@@ -1470,7 +1603,7 @@ try {
 
 // ── 3a-pre. (removed) Daemon-version-skew recycle moved to §2a. ─────────────
 // The previous version of this block ran AFTER §3's heavy file-sync work,
-// which routinely exceeded the 3000ms SessionStart hook timeout and was
+// which routinely exceeded the then-3000ms SessionStart hook timeout and was
 // killed before reaching this point. §2a now runs early and force-kills the
 // stale daemon before §3 can starve out. Don't restore §3a-pre — keep the
 // recycle in one place so the two paths can't drift.