@smartmemory/compose 0.4.1 → 0.5.1

package/lib/tool-inventory.js

@@ -35,7 +35,6 @@ export const EFFECTS = /** @type {const} */ (['read', 'mutating', 'setup']);
  */
 export const CANON_IDS = new Set([
   'roadmap', 'changelog', 'feature-json', 'judgment',
-  'override-ledger', 'override-attest', 'override-grants',
 ]);
 
 /**

package/lib/version-check.js

@@ -75,10 +75,16 @@ async function fetchLatest(pkg) {
 export function compareVersions(a, b) {
   if (typeof a !== 'string' || typeof b !== 'string') return null
   const parse = (s) => {
-    const [core, pre] = s.split('-')
-    const parts = core.split('.').map(n => Number.parseInt(n, 10))
+    const buildIndex = s.indexOf('+')
+    const withoutBuild = buildIndex === -1 ? s : s.slice(0, buildIndex)
+    const prereleaseIndex = withoutBuild.indexOf('-')
+    const core = prereleaseIndex === -1 ? withoutBuild : withoutBuild.slice(0, prereleaseIndex)
+    const pre = prereleaseIndex === -1 ? null : withoutBuild.slice(prereleaseIndex + 1)
+    // parseInt is lenient: '3garbage' -> 3. A strict all-digits test is what makes
+    // the NaN guard below actually fire for trailing junk (COMP-SEMVER-STRICT).
+    const parts = core.split('.').map(n => (/^\d+$/.test(n) ? Number(n) : NaN))
     if (parts.length !== 3 || parts.some(n => Number.isNaN(n))) return null
-    return { parts, pre: pre ?? null }
+    return { parts, pre }
   }
   const pa = parse(a)
   const pb = parse(b)

package/lib/wave-checkpoint.js

@@ -0,0 +1,100 @@
+/** Git object/ref plumbing. Never checks out a branch or changes the real index. */
+import { execFileSync } from 'node:child_process';
+import { withTemporaryIndex, snapshotWorkingTree } from './consumer-fanout.js';
+
+export class WaveCheckpointError extends Error {
+  constructor(code, message) { super(message); this.name = 'WaveCheckpointError'; this.code = code; }
+}
+const fail = (code, message) => { throw new WaveCheckpointError(code, message); };
+function git(cwd, args, opts = {}) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: 'pipe', maxBuffer: 512 * 1024 * 1024, ...opts }).trim();
+}
+function symbolicRef(cwd, ref) {
+  try { return git(cwd, ['symbolic-ref', '-q', ref]); }
+  catch (error) { if (error.status === 1) return null; throw error; }
+}
+function validateRef(cwd, ref) {
+  if (typeof ref !== 'string' || !ref.startsWith('refs/heads/compose/wave/')) fail('WAVE_CHECKPOINT_DIVERGED', 'Expected a Compose wave ref');
+  try { git(cwd, ['check-ref-format', ref]); }
+  catch { fail('WAVE_CHECKPOINT_DIVERGED', 'Invalid wave ref'); }
+  if (symbolicRef(cwd, ref)) fail('WAVE_CHECKPOINT_DIVERGED', 'Symbolic wave refs are not allowed');
+  // Include other linked worktrees: updating their checked-out branch moves HEAD too.
+  const worktrees = git(cwd, ['worktree', 'list', '--porcelain']);
+  if (worktrees.split('\n').includes(`branch ${ref}`)) fail('WAVE_CHECKPOINT_DIVERGED', 'Wave ref is checked out in a worktree');
+}
+export function readCheckpointRef({ cwd, ref }) {
+  validateRef(cwd, ref);
+  try { return git(cwd, ['show-ref', '--verify', '--hash', ref]); }
+  catch (error) { if (error.status === 1 || error.status === 128 && /not a valid ref/.test(error.stderr?.toString())) return null; throw error; }
+}
+export function prepareCheckpoint({ cwd, ref, parentCommit, tree, workingTree, message, commitMetadata }) {
+  validateRef(cwd, ref);
+  if (typeof parentCommit !== 'string' || !/^[a-f0-9]{40,64}$/.test(parentCommit)) fail('WAVE_CHECKPOINT_EVIDENCE_MISSING', 'Parent must be a commit OID');
+  const parent = git(cwd, ['rev-parse', '--verify', `${parentCommit}^{commit}`]);
+  const capturedTree = tree ?? (workingTree === true ? snapshotWorkingTree(cwd) : workingTree);
+  if (!capturedTree) fail('WAVE_CHECKPOINT_EVIDENCE_MISSING', 'Checkpoint needs a tree or workingTree:true');
+  const treeId = git(cwd, ['rev-parse', '--verify', `${capturedTree}^{tree}`]);
+  const metadata = structuredClone(commitMetadata ?? {
+    authorName: git(cwd, ['config', 'user.name']), authorEmail: git(cwd, ['config', 'user.email']),
+    date: new Date().toISOString(),
+  });
+  if (!metadata.authorName || !metadata.authorEmail || !Number.isFinite(Date.parse(metadata.date))) fail('WAVE_CHECKPOINT_EVIDENCE_MISSING', 'Invalid pinned commit metadata');
+  metadata.date = new Date(metadata.date).toISOString();
+  if (typeof message !== 'string' || !message) fail('WAVE_CHECKPOINT_EVIDENCE_MISSING', 'Checkpoint message is required');
+  const env = { ...process.env, GIT_AUTHOR_NAME: metadata.authorName, GIT_COMMITTER_NAME: metadata.authorName,
+    GIT_AUTHOR_EMAIL: metadata.authorEmail, GIT_COMMITTER_EMAIL: metadata.authorEmail,
+    GIT_AUTHOR_DATE: metadata.date, GIT_COMMITTER_DATE: metadata.date };
+  const commit = git(cwd, ['commit-tree', treeId, '-p', parent], { input: message, env });
+  return { ref, parentCommit: parent, tree: treeId, commit, message, commitMetadata: metadata };
+}
+export function publishCheckpoint({ cwd, ref, expected, commit }) {
+  validateRef(cwd, ref);
+  git(cwd, ['cat-file', '-e', `${commit}^{commit}`]);
+  const zero = '0'.repeat(git(cwd, ['rev-parse', 'HEAD']).length);
+  try { git(cwd, ['update-ref', ref, commit, expected ?? zero]); }
+  catch (error) { fail('WAVE_CHECKPOINT_DIVERGED', `Checkpoint compare-and-swap refused: ${error.message}`); }
+  return commit;
+}
+export function worktreeBaseFor({ journal, ref }) {
+  const wave = journal?.wave;
+  if (!wave) return null;
+  if (wave.checkpoints.some(checkpoint => checkpoint.state !== 'published')) fail('WAVE_CHECKPOINT_EVIDENCE_MISSING', 'Checkpoint publication is pending');
+  const expected = wave.checkpoints.at(-1)?.commit ?? null;
+  if (ref !== expected) fail('WAVE_CHECKPOINT_DIVERGED', 'Wave ref differs from the published journal tip');
+  return expected ?? wave.baseCommit;
+}
+export function squashOntoBase({ cwd, ref, base }) {
+  if (git(cwd, ['rev-parse', 'HEAD']) !== base) fail('WAVE_CHECKPOINT_DIVERGED', 'HEAD moved from the pinned base');
+  const tip = readCheckpointRef({ cwd, ref });
+  if (!tip) fail('WAVE_CHECKPOINT_EVIDENCE_MISSING', 'Wave ref is missing');
+  return withTemporaryIndex(cwd, env => {
+    git(cwd, ['read-tree', base], { env });
+    const diff = execFileSync('git', ['diff', '--binary', base, tip, '--'], { cwd, encoding: 'utf8', maxBuffer: 512 * 1024 * 1024 });
+    if (diff) git(cwd, ['apply', '--cached', '--binary', '-'], { env, input: diff });
+    const tree = git(cwd, ['write-tree'], { env });
+    if (tree !== git(cwd, ['rev-parse', `${tip}^{tree}`])) fail('WAVE_CHECKPOINT_DIVERGED', 'Squashed tree differs from checkpoint');
+    return tree;
+  });
+}
+export function removeCheckpointRef({ cwd, ref, expected }) {
+  validateRef(cwd, ref);
+  if (!expected) fail('WAVE_CHECKPOINT_EVIDENCE_MISSING', 'Deletion requires the expected tip');
+  git(cwd, ['update-ref', '-d', ref, expected]);
+}
+/** Pure resume-table classification; all supplied decisions are durable ordinal evidence. */
+export function reconcileCheckpoint({ journalEntry: entry, refValue }) {
+  if (!entry) return refValue == null ? 'ADMIT_FROM_BASE' : 'WAVE_CHECKPOINT_DIVERGED';
+  if (entry.evidenceMissing) return 'WAVE_CHECKPOINT_EVIDENCE_MISSING';
+  if (entry.diverged) return 'WAVE_CHECKPOINT_DIVERGED';
+  if (!entry.commit) {
+    if (refValue !== (entry.previousCommit ?? null)) return 'WAVE_CHECKPOINT_DIVERGED';
+    return entry.gateOutcome === 'approve' ? 'PREPARE_AND_PUBLISH' : 'RECOVER_WAITING_GATE';
+  }
+  if (refValue === entry.commit) {
+    if (entry.state === 'prepared') return 'MARK_PUBLISHED';
+    return entry.terminal ? 'PRESERVE_PUBLISHED' : 'ALREADY_PUBLISHED';
+  }
+  if (refValue === entry.parentCommit || refValue == null && entry.waveNumber === 1) return 'REPLAY_AND_PUBLISH';
+  if (entry.knownAncestorCommits?.includes(refValue)) return 'RECONCILE_IN_ORDER';
+  return 'WAVE_CHECKPOINT_DIVERGED';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartmemory/compose",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Structured AI dev pipeline: your agent writes the code, Compose makes it prove it. Gated design decisions, enforced postconditions, and independent review from goal to shipped code.",
   "author": "SmartMemory",
   "license": "MIT",
@@ -20,11 +20,11 @@
     "dev:client": "vite",
     "build": "vite build",
     "preview": "vite preview",
-    "test": "node --import ./test/suppress-expected-drift.js --test --test-timeout=300000 test/*.test.js test/comp-obs-branch/*.test.js test/integration/*.test.js test/golden/*.test.js && npm run test:ui && npm run test:tracker",
+    "test": "node --import ./test/suppress-expected-drift.js --test --test-timeout=900000 test/*.test.js test/comp-obs-branch/*.test.js test/integration/*.test.js test/golden/*.test.js && npm run test:ui && npm run test:tracker",
     "test:ui": "vitest run",
     "test:tracker": "vitest run --config vitest.tracker.config.js",
-    "test:integration": "node --test --test-timeout=300000 test/integration/*.test.js",
-    "test:wave-6": "node --test --test-timeout=300000 test/wave-6-integration.test.js test/wave-6-contract-compliance.test.js",
+    "test:integration": "node --test --test-timeout=900000 test/integration/*.test.js",
+    "test:wave-6": "node --test --test-timeout=900000 test/wave-6-integration.test.js test/wave-6-contract-compliance.test.js",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -55,6 +55,8 @@
   },
   "files": [
     ".compose-deps.json",
+    ".claude/agents/**",
+    ".claude/hooks/**",
     ".claude/skills/**",
     "bin/**",
     "server/**",
@@ -86,7 +88,7 @@
     "@radix-ui/react-toggle-group": "^1.1.11",
     "@radix-ui/react-tooltip": "^1.2.8",
     "@smartmemory/sdk-js": "^1.4.60",
-    "@smartmemory/stratum": "^0.4.5",
+    "@smartmemory/stratum": "^0.5.2",
     "@tanstack/react-virtual": "^3.13.23",
     "ajv": "^8.18.0",
     "ajv-formats": "^3.0.1",

package/presets/team-fable-astra.profiles.json

@@ -0,0 +1,18 @@
+{
+  "plan": "claude:orchestrator:coordinator",
+  "execute": { "default": "codex:implementer:critical", "tier_from": "item.tier" },
+  "verify": "claude:orchestrator:standard",
+  "review": "codex:read-only-reviewer:critical",
+  "assess": "claude:orchestrator:coordinator",
+  "assess_gate": {
+    "decide_from": {
+      "step": "assess", "field": "action",
+      "approve": ["complete"], "revise": ["repair", "implement"], "kill": ["blocked"]
+    },
+    "validators": [{ "name": "WaveDecision", "review_step": "review", "tasks_field": "tasks" }]
+  },
+  "_consumer": {
+    "execute": { "ownership": "item.files_owned", "independent": true, "checkpoint_gate": "execute_merge" }
+  },
+  "_costCeiling": { "input": "cost_ceiling_usd", "default": 150, "gates": ["assess_gate"] }
+}

package/presets/team-fable-astra.stratum.yaml

@@ -0,0 +1,236 @@
+# TEAM PRESET: fable-astra
+#
+# Purpose:     Fable plans and assesses bounded waves; Astra implements and reviews.
+# Pattern:     Plan → parallel execute → merge → verify → fresh review → assess
+#              → repair/implement another wave, ship on complete, or kill on blocked.
+# Capability:  Per-task Codex tiers; fresh read-only Astra reviewer; Fable decisions.
+# Isolation:   worktree, literal file ownership; sequential merge and checkpoints.
+# Use with:    compose build <feature-code> --team fable-astra
+# Customize:   Copy BOTH team-fable-astra.stratum.yaml AND its .profiles.json
+#              sidecar into your project's pipelines/ and edit them together.
+# Ruling:      Concurrency is literal 3, customized by copying this preset, rather
+#              than an input as designed (TS schema accepts numeric literals only).
+#              cost_ceiling_usd remains an optional flow input, default 150 in the
+#              sidecar; compose build --cost-ceiling-usd overrides that ceiling.
+# Carry rules: References use ${} only, never when/set/ensure/iterate.until.
+#              Every wave consumer must descend from plan, be reset by the
+#              assess_gate revise closure, and precede that gate through after.
+#              execute_merge retries preserve wave; assess_gate replaces it.
+
+version: 1
+
+contracts:
+  Task:
+    id: string
+    description: string
+    files_owned: string[]
+    files_read: string[]
+    depends_on: string[]
+    tier: critical|standard|fast
+    tier_rationale: string
+  TaskGraph:
+    tasks: Task[]
+  Verification:
+    commands: string[]
+    outcomes: string[]
+  TaskResult:
+    outcome: string
+    summary: string
+    files_changed: string[]
+    verification: Verification
+  VerifyResult:
+    tests_pass: boolean
+    summary: string
+    verification: Verification
+    merged_diff: string
+  Finding:
+    severity: string
+    files: string[]
+    claim: string
+    evidence: string
+  ReviewFindings:
+    findings: Finding[]
+    blocking: boolean
+  WaveDecision:
+    action: repair|implement|complete|blocked
+    tasks: Task[]
+    rationale: string
+    addressed_findings: Finding[]
+    open_findings: Finding[]
+    blocking: boolean
+    open_count: integer
+  ShipResult:
+    phase: string
+    artifact: string
+    outcome: string
+    summary: string
+    files_changed: string[]?
+    commit_hash: string?
+
+flows:
+  entry: team_fable_astra
+  team_fable_astra:
+    input:
+      featureCode: string
+      description: string
+      # Accept the existing feature-build envelope; providers stay pinned below.
+      implementer_agent: string?
+      reviewer_agent: string?
+      pre_merge_gate: string[]?
+      cost_ceiling_usd: number?
+    output:
+      from: "${ship.output}"
+      contract: ShipResult
+    max_rounds: 4
+    carry:
+      wave:
+        initial: "${plan.output.tasks}"
+        on_revise:
+          assess_gate: "${assess.output.tasks}"
+    steps:
+      - id: plan
+        agent: claude
+        do: |
+          Plan wave 1 for ${input.featureCode}. Goal and acceptance criteria:
+          ${input.description}
+          Read the feature's design, brief, plan and acceptance criteria before planning.
+          MUST checklist:
+          - Return TaskGraph with 1..6 tasks, each with id, description, files_owned,
+            files_read, depends_on, tier and a one-line tier_rationale.
+          - Wave 1 must contain only mutually independent tasks: depends_on is empty
+            for every task. Waves carry dependencies; dependent work goes in later
+            waves after its prerequisite checkpoint, not into this wave.
+          - No two tasks may share files_owned. Redo the graph if ownership overlaps.
+          - files_owned must be literal repo-relative paths, never globs or directories.
+          - Use critical for tasks with design judgment or root-causing, standard
+            for brief-bounded implementation, fast for transcription-level edits; repair
+            waves default to the tier of the task being repaired or higher, never lower.
+          - Each task must fit one focused session; target 2-4 tasks for a typical feature.
+          Return the task graph only; do not implement or commit.
+        out: TaskGraph
+        ensure:
+          - expr: "len(result.tasks) >= 1"
+          - expr: "len(result.tasks) <= 6"
+        attempts: 3
+
+      - id: execute
+        after: [plan]
+        fanout:
+          over: "${wave}"
+          dispatch: consumer
+          concurrency: 3
+          isolation: worktree
+          require: all
+          merge: sequential
+          steps:
+            - agent: codex
+              do: |
+                Implement the task described by ${item} using TDD. Write the test
+                first, watch it fail, implement, and watch it pass. Honor the
+                item's id, description, files_owned (you may create/modify these)
+                and files_read (you may read but NOT modify these).
+                MUST touch only files_owned — anything else fails the task at merge.
+                MUST return {outcome, summary, files_changed, verification}, with
+                verification {commands, outcomes}: exact commands and corresponding
+                observed outcomes, including failures. Do not commit.
+              out: TaskResult
+
+      - id: execute_merge
+        after: [execute]
+        gate:
+          on_approve: verify
+          on_revise: execute
+          on_kill: null
+          max_rounds: 2
+
+      - id: verify
+        after: [execute_merge]
+        agent: claude
+        do: |
+          Verify the integrated tree for ${input.featureCode} against the goal and
+          acceptance criteria: ${input.description}
+          MUST run the project's relevant tests and integration checks on the merged
+          tree, check for merge conflicts, and record exact commands and outcomes.
+          MUST capture the full cumulative merged diff: git diff HEAD -- for tracked
+          files, plus git ls-files --others --exclude-standard and added-file diffs
+          using git diff --no-index -- /dev/null <path> for each new feature file
+          (exit 1 means differences). HEAD remains the build base until ship; new
+          merged files can still be untracked. Return VerifyResult with tests_pass,
+          summary, verification {commands, outcomes}, and merged_diff. Describe only
+          observed verification evidence; never copy worker summaries. Do not edit.
+          Report failures truthfully so review and assess can request a repair wave.
+        out: VerifyResult
+        ensure:
+          - expr: "len(result.summary) > 0"
+
+      - id: review
+        after: [verify]
+        agent: codex
+        do: |
+          Fresh independent read-only review of ${input.featureCode}.
+          Goal and acceptance criteria: ${input.description}
+          VerifyResult (including the cumulative merged diff): ${verify.output}
+          MUST checklist:
+          - Read the feature's design, brief and plan for its acceptance criteria.
+            Read the merged diff against the goal, those criteria and VerifyResult;
+            inspect the integrated source and affected callers.
+          - Probe cross-module wiring: a green unit suite is not evidence that the
+            user-facing path reaches the implementation. Cite the actual call path.
+          - Never read worker summaries, TaskResults, worker journals or transcripts.
+            Form your judgment from the diff, source, criteria and verification only.
+          - Return one finding per defect, with severity, files (literal repo-relative
+            paths), claim and concrete evidence. Include failed verification and unmet
+            criteria as findings; set blocking when any defect prevents completion.
+          - Return ReviewFindings {findings, blocking}. Do not edit or commit.
+        out: ReviewFindings
+
+      - id: assess
+        after: [review]
+        agent: claude
+        do: |
+          Assess ${input.featureCode} against its goal and acceptance criteria:
+          ${input.description}
+          Current tasks: ${wave}
+          TaskResults with verification evidence: ${execute.output}
+          VerifyResult and cumulative merged diff: ${verify.output}
+          Fresh ReviewFindings: ${review.output}
+          MUST checklist:
+          - Address every finding: reproduce its full finding object in exactly one
+            of addressed_findings or open_findings; justify dispositions in rationale.
+          - Copy blocking from review. Set open_count to len(open_findings).
+          - repair tasks must each own at least one file named by an open finding.
+            Dispatch only affected work; do not repeat accepted unaffected tasks.
+          - For repair or implement return 1..6 mutually independent tasks with empty
+            depends_on, disjoint literal repo-relative files_owned, and all Task fields.
+            Later waves start from the previous checkpoint containing prerequisites.
+          - Use critical for tasks with design judgment or root-causing, standard
+            for brief-bounded implementation, fast for transcription-level edits; repair
+            waves default to the tier of the task being repaired or higher, never lower.
+          - Choose implement when additional scoped work is needed; repair for defects.
+          - complete only when all acceptance criteria are met, verification passes,
+            there are zero open findings and blocking is false; return tasks: [].
+          - blocked when repair cannot proceed; retain the open findings (open_count
+            must be positive), explain why, and return tasks: [].
+          Return WaveDecision only. Do not edit or commit.
+        out: WaveDecision
+        ensure:
+          - expr: "result.action != 'complete' || (result.open_count == 0 && result.blocking == false)"
+          - expr: "result.action != 'blocked' || result.open_count > 0"
+          - expr: "result.open_count >= 0"
+
+      - id: assess_gate
+        after: [assess]
+        gate:
+          on_approve: ship
+          on_revise: execute
+          on_kill: null
+          max_rounds: 2
+
+      # Compose intercepts ship: squash the wave checkpoints and selectively commit.
+      - id: ship
+        after: [assess_gate]
+        agent: claude
+        do: |
+          Ship ${input.featureCode}: run final tests and squash the accepted wave
+          changes into one commit whose parent is the build base. Return ShipResult.
+        out: ShipResult

package/server/build-stream-bridge.js

@@ -45,18 +45,26 @@ export class BuildStreamBridge {
   #debounceTimer = null;
   #crashTimer = null;
   #polling = false;
+  #safetyInterval = null;
+  #watchFn;
+  #pollIntervalMs;
 
   /**
    * @param {string} composeDir  Path to .compose directory
    * @param {Function} broadcast  broadcast(msg) function from agent-server
    * @param {object} [opts]
    * @param {number} [opts.crashTimeoutMs]  Crash detection timeout (default 5min)
+   * @param {number} [opts.pollIntervalMs]  Safety re-read cadence (default 2s)
+   * @param {Function} [opts.watchFn]  Injected for tests that need a watcher
+   *   which never delivers — the condition the safety poll exists to survive.
    */
   constructor(composeDir, broadcast, opts = {}) {
     this.#composeDir = composeDir;
     this.#filePath = join(composeDir, JSONL_FILENAME);
     this.#broadcast = broadcast;
     this.#crashTimeoutMs = opts.crashTimeoutMs ?? DEFAULT_CRASH_TIMEOUT_MS;
+    this.#pollIntervalMs = opts.pollIntervalMs ?? POLL_INTERVAL_MS;
+    this.#watchFn = opts.watchFn ?? watch;
   }
 
   /**
@@ -97,6 +105,10 @@ export class BuildStreamBridge {
       clearInterval(this.#pollInterval);
       this.#pollInterval = null;
     }
+    if (this.#safetyInterval) {
+      clearInterval(this.#safetyInterval);
+      this.#safetyInterval = null;
+    }
     if (this.#debounceTimer) {
       clearTimeout(this.#debounceTimer);
       this.#debounceTimer = null;
@@ -112,8 +124,11 @@ export class BuildStreamBridge {
   // ---------------------------------------------------------------------------
 
   _startWatching() {
+    // The safety poll is armed FIRST and unconditionally, because the watcher
+    // cannot be trusted to be listening (see _startSafetyPoll).
+    this._startSafetyPoll();
     try {
-      this.#watcher = watch(this.#composeDir, (eventType, filename) => {
+      this.#watcher = this.#watchFn(this.#composeDir, (eventType, filename) => {
         if (filename === JSONL_FILENAME || filename === null) {
           this._debouncedRead();
         }
@@ -129,6 +144,33 @@ export class BuildStreamBridge {
     }
   }
 
+  /**
+   * Re-read on a timer for as long as we are tailing, regardless of the watcher.
+   *
+   * `fs.watch` is an OPTIMISATION here, never the guarantee. It is not armed
+   * when the call returns: on macOS libuv registers the FSEvents stream
+   * asynchronously, so writes landing between `watch()` returning and the stream
+   * actually listening are delivered to nobody. `start()` arms the watcher and
+   * then reads synchronously, which is exactly that window — and under load the
+   * window stretches to cover a whole build's first events.
+   *
+   * Measured before this existed (600 runs of the scenario, 6 concurrent
+   * processes, full suite as load): 14/450 runs saw the watcher deliver NOTHING
+   * after start, so the bridge broadcast the pre-existing lines and then went
+   * permanently deaf — no periodic re-check existed to recover it. The same 450
+   * runs with a settle delay before the writes: 0 failures. That was a live
+   * cockpit stream that silently never starts, not a test-timing problem.
+   *
+   * A missed event is therefore recoverable rather than terminal. `_readNewLines`
+   * exits on a single `statSync` when the file has not grown, so the standing
+   * cost is one stat per interval.
+   */
+  _startSafetyPoll() {
+    if (this.#safetyInterval) return;
+    this.#safetyInterval = setInterval(() => this._readNewLines(), this.#pollIntervalMs);
+    this.#safetyInterval.unref();
+  }
+
   _pollForDirectory() {
     if (this.#polling) return;
     this.#polling = true;

package/server/cc-session-watcher.js

@@ -68,6 +68,8 @@ export class CCSessionWatcher {
     // COMP-OBS-DRIFT: optional deps for post-lineage drift broadcast
     emitDriftAxes = null,
     projectRoot = null,
+    // Backstop-poll cadence. Injectable so a test need not wait 2s for it.
+    pollIntervalMs = 2000,
   }) {
     if (!projectsRoot) throw new Error('projectsRoot required');
     if (!sessionsFile) throw new Error('sessionsFile required');
@@ -87,6 +89,7 @@ export class CCSessionWatcher {
     // COMP-OBS-DRIFT: optional drift emitter
     this._emitDriftAxes = emitDriftAxes;
     this._projectRoot = projectRoot;
+    this.pollIntervalMs = pollIntervalMs;
 
     // featureCode → (cc_session_id → BranchOutcome[])
     this._accum = new Map();
@@ -272,6 +275,29 @@ export class CCSessionWatcher {
     if (scanned) await this._flush([scanned.featureCode]);
   }
 
+  /**
+   * Dispatch one file change, never concurrently with another.
+   *
+   * `_flush` is idempotent SEQUENTIALLY — the lineage POST is a replace-by-key
+   * (`updateLifecycleExt`), and a fork already in `emitted_event_ids` is not
+   * re-broadcast. It is NOT idempotent CONCURRENTLY: `emitted.add(eventId)` runs
+   * only after `await postBranchLineage`, so two overlapping flushes both see
+   * the same fork as new and both broadcast its DecisionEvent.
+   *
+   * With the watcher as the sole dispatcher that overlap was rare. Arming the
+   * safety poll beside it (see `start`) would have made it ordinary, so
+   * dispatch is serialised here rather than left to chance — which also closes
+   * the same pre-existing overlap between `fullScan()` and a watcher event.
+   */
+  _dispatch(jsonlPath) {
+    this._chain = (this._chain ?? Promise.resolve())
+      .then(() => this._onFileChange(jsonlPath))
+      .catch(err => {
+        console.warn(`[cc-watcher] change handler failed: ${err.message}`);
+      });
+    return this._chain;
+  }
+
   start() {
     // C5: the fs.watch fallback leaves `_watcher` null, so guarding on it alone
     // let every resume() start ANOTHER poll interval — one leaked per switch.
@@ -279,6 +305,20 @@ export class CCSessionWatcher {
     if (!fs.existsSync(this.projectsRoot)) {
       fs.mkdirSync(this.projectsRoot, { recursive: true });
     }
+    // The poll is armed ALONGSIDE the watcher, not only when fs.watch throws.
+    //
+    // A watcher that stops delivering does not throw and does not emit 'error';
+    // it simply goes quiet, and every subsequent session write is lost with no
+    // symptom. Polling used to be reachable only from the synchronous throw
+    // below, so the one failure mode that actually needs recovery — a live
+    // watcher that has silently stopped — had none, and missed CC sessions meant
+    // branch DecisionEvents that never fire and never self-heal.
+    //
+    // (Unlike the build-stream bridge, the fs.watch ARMING window is not the
+    // hazard here: CC sessions are written minutes after start, not in the
+    // microseconds between `watch()` returning and the stream listening. The
+    // justification is dead-watcher recovery.)
+    this._startPolling();
     try {
       this._watcher = fs.watch(this.projectsRoot, { recursive: true }, (_evt, filename) => {
         if (!filename || !filename.endsWith('.jsonl')) return;
@@ -287,9 +327,16 @@ export class CCSessionWatcher {
         const now = Date.now();
         if (now - last < DEFAULT_DEBOUNCE_MS) return;
         this._debounce.set(full, now);
-        this._onFileChange(full).catch(err => {
-          console.warn(`[cc-watcher] change handler failed: ${err.message}`);
-        });
+        this._dispatch(full);
+      });
+      // A watcher can die AFTER construction. Without this the failure is
+      // completely silent; the poll below is already running, so recovery is
+      // just dropping the dead handle.
+      this._watcher.on?.('error', (err) => {
+        console.warn(`[cc-watcher] watcher died, polling continues: ${err?.message}`);
+        try { this._watcher?.close(); } catch { /* already gone */ }
+        this._watcher = null;
+        this._startPolling();
       });
     } catch (err) {
       console.warn(`[cc-watcher] fs.watch unavailable, falling back to polling: ${err.message}`);
@@ -297,7 +344,7 @@ export class CCSessionWatcher {
     }
   }
 
-  _startPolling(intervalMs = 2000) {
+  _startPolling(intervalMs = this.pollIntervalMs ?? 2000) {
     if (this._pollTimer) return;
     this._pollTimer = setInterval(async () => {
       const files = listJsonlFiles(this.projectsRoot);
@@ -308,10 +355,12 @@ export class CCSessionWatcher {
         const last = this._debounce.get(key) || 0;
         if (stat.mtimeMs > last) {
           this._debounce.set(key, stat.mtimeMs);
-          await this._onFileChange(f);
+          await this._dispatch(f);
         }
       }
     }, intervalMs);
+    // Never hold the process open on this alone — it is a backstop, not work.
+    this._pollTimer.unref?.();
   }
 
   stop() {