mandrel 2.0.0 → 2.2.0

package/.agents/scripts/lib/git-merge-orchestrator.js

@@ -1,261 +0,0 @@
-/* node:coverage ignore file -- ephemeral merge orchestrator over live git state; conflict triage tested via integration. Unit-mocking requires asserting only the mock structure */
-
-/**
- * git-merge-orchestrator.js — Ephemeral Candidate Branch Merge Logic
- *
- * Encapsulates the complete merge-and-conflict-resolution lifecycle for
- * a single Task integration candidate. Extracted from the legacy
- * integration script to satisfy SRP: the orchestrator owns only Git
- * state transitions.
- *
- * Responsibilities:
- *   - Create and tear down the ephemeral candidate branch.
- *   - Detect and triage merge conflicts (major vs minor threshold).
- *   - Auto-resolve minor conflicts (accept theirs) with audit logging.
- */
-
-import { resolveConfig } from './config-resolver.js';
-import { gitSpawn } from './git-utils.js';
-
-/**
- * Analyse conflict severity using git's binary-safe diff --check.
- *
- * @param {string} cwd - Project root.
- * @returns {{ files: number, lines: number, fileList: string[] }}
- */
-function analyzeConflicts(cwd) {
-  const unmerged = gitSpawn(cwd, 'diff', '--name-only', '--diff-filter=U');
-  if (!unmerged.stdout) return { files: 0, lines: 0, fileList: [] };
-
-  const fileList = unmerged.stdout.split('\n').filter(Boolean);
-  const check = gitSpawn(cwd, 'diff', '--check');
-  const markerMatches = check.stdout.match(/leftover conflict marker/g);
-
-  return {
-    files: fileList.length,
-    lines: markerMatches ? markerMatches.length : 0,
-    fileList,
-  };
-}
-
-/**
- * Merge the feature branch into the current (candidate) branch.
- * Handles conflict triage and auto-resolution.
- *
- * @param {string}   cwd           - Project root.
- * @param {string}   featureBranch - Branch name to merge in.
- * @param {Function} vlog          - `(level, context, message, meta)` warn helper for conflict triage output.
- * @param {object}   [opts]
- * @param {string}   [opts.message] - Explicit merge commit message (passed as `-m`).
- * @returns {{ merged: true } | { merged: false, major: true } | never}
- *   Returns `{ merged: true }` on clean merge or resolved minor conflicts.
- *   Returns `{ merged: false, major: true }` on major conflict (caller should exit 2).
- *   Throws on internal git errors.
- */
-/**
- * Pure: classify a conflict snapshot as `'major'` (caller aborts) or
- * `'minor'` (caller auto-resolves). Thresholds default to the values in
- * `delivery.mergeThresholds` and fall back to file=3, line=20.
- *
- * @param {{ files: number, lines: number }} conflicts
- * @param {{ files?: number, lines?: number } | undefined} thresholds
- * @returns {'major' | 'minor'}
- */
-export function classifyConflictSeverity(conflicts, thresholds = {}) {
-  const fileCap = thresholds.files ?? 3;
-  const lineCap = thresholds.lines ?? 20;
-  if (conflicts.files >= fileCap || conflicts.lines >= lineCap) return 'major';
-  return 'minor';
-}
-
-/**
- * Auto-resolve a minor merge conflict by accepting the feature-branch version
- * for each file in `conflicts.fileList`, capturing the discarded line counts
- * for the audit trailer. Side effects: shells out to git checkout/add.
- *
- * @returns {Array<{ file: string, discardedLines: number }>}
- */
-function autoResolveAcceptingTheirs(cwd, conflicts, vlog) {
-  const autoResolvedFiles = [];
-  for (const file of conflicts.fileList) {
-    const ourVersion = gitSpawn(cwd, 'show', `:2:${file}`);
-    const discardedLines = ourVersion.stdout
-      ? ourVersion.stdout.split('\n').length
-      : 0;
-    autoResolvedFiles.push({ file, discardedLines });
-    if (ourVersion.stdout) {
-      vlog(
-        'warn',
-        'integration',
-        `Auto-resolving "${file}" to theirs — discarding base version (${discardedLines} lines)`,
-        {
-          file,
-          discardedLines,
-          discardedPreview: ourVersion.stdout.substring(0, 500),
-        },
-      );
-    }
-    gitSpawn(cwd, 'checkout', '--theirs', file);
-    gitSpawn(cwd, 'add', file);
-  }
-  return autoResolvedFiles;
-}
-
-/**
- * Commit the auto-resolved working tree. When the caller supplied an explicit
- * merge message, append the audit trailer; otherwise use git's default
- * `--no-edit` message.
- */
-function commitAutoResolution(cwd, opts, autoResolvedFiles) {
-  const trailer = buildAutoResolveTrailer(autoResolvedFiles);
-  const finalMessage = opts.message ? `${opts.message}\n\n${trailer}` : null;
-  const commitArgs = finalMessage
-    ? ['commit', '-m', finalMessage]
-    : ['commit', '--no-edit'];
-  const commitResult = gitSpawn(cwd, ...commitArgs);
-  if (commitResult.status !== 0) {
-    throw new Error(`Auto-resolution commit failed: ${commitResult.stderr}`);
-  }
-}
-
-// Epic #3078: pre-commit hooks (notably lint-staged's stash/restore dance)
-// can leave `git merge --no-ff` exiting 0 without recording the commit.
-// Verify HEAD advanced; distinguish silent failure from "Already up to date".
-function classifyZeroExitMerge({
-  headBefore,
-  headAfter,
-  mergeStdout,
-  featureBranch,
-}) {
-  if (headAfter !== headBefore) return { merged: true };
-  if (/Already up to date/i.test(mergeStdout)) {
-    return { merged: true, alreadyMerged: true };
-  }
-  throw new Error(
-    `git merge --no-ff ${featureBranch} exited 0 but HEAD did not advance ` +
-      `(was ${headBefore || '<unknown>'}). Most likely a pre-commit hook ` +
-      `(commonly lint-staged) accepted the merge content into the index ` +
-      `without recording the commit. Inspect the index and any active ` +
-      `stash, commit the merge content manually if appropriate, then ` +
-      `re-run story-close with --resume. See Epic #3078 for incident notes.`,
-  );
-}
-
-export function mergeFeatureBranch(cwd, featureBranch, vlog, opts = {}) {
-  const headBefore = gitSpawn(cwd, 'rev-parse', 'HEAD').stdout;
-  const mergeArgs = ['merge', '--no-ff', featureBranch];
-  if (opts.message) mergeArgs.push('-m', opts.message);
-  const merge = gitSpawn(cwd, ...mergeArgs);
-  if (merge.status === 0) {
-    return classifyZeroExitMerge({
-      headBefore,
-      headAfter: gitSpawn(cwd, 'rev-parse', 'HEAD').stdout,
-      mergeStdout: merge.stdout,
-      featureBranch,
-    });
-  }
-
-  const conflicts = analyzeConflicts(cwd);
-
-  // `git merge` exited non-zero but the index has no unmerged entries and
-  // no leftover conflict markers. The merge either already landed (a hook
-  // emitted a non-zero exit after the merge commit was created) or was a
-  // no-op (feature branch is already an ancestor / does not exist). In
-  // both cases there is nothing to auto-resolve and nothing to commit —
-  // attempting `git commit` here fails with "nothing to commit", which
-  // turns a successful merge into a fatal and strands story-close work.
-  if (conflicts.files === 0 && conflicts.lines === 0) {
-    return { merged: true, alreadyMerged: true };
-  }
-
-  vlog('warn', 'integration', 'Merge conflict detected', {
-    files: conflicts.files,
-    lines: conflicts.lines,
-    fileList: conflicts.fileList,
-  });
-
-  // Epic #2880 / F14B: read mergeThresholds from the canonical resolved
-  // config (`delivery.mergeThresholds`). The legacy `agentSettings`
-  // pointer is gone — destructuring it throws `Cannot read properties of
-  // undefined`. The threshold block remains optional; `classifyConflict
-  // Severity` falls back to file=3/line=20 when undefined.
-  const config = resolveConfig();
-  const severity = classifyConflictSeverity(
-    conflicts,
-    config?.delivery?.mergeThresholds,
-  );
-  if (severity === 'major') {
-    gitSpawn(cwd, 'merge', '--abort');
-    return { merged: false, major: true, conflicts };
-  }
-
-  const autoResolvedFiles = autoResolveAcceptingTheirs(cwd, conflicts, vlog);
-  commitAutoResolution(cwd, opts, autoResolvedFiles);
-  return { merged: true, autoResolved: true, conflicts, autoResolvedFiles };
-}
-
-/**
- * Build a merge-commit message body + trailer documenting which files were
- * auto-resolved by accepting the feature-branch version and how many lines
- * of the base version were discarded.
- *
- * The output is split into three blocks separated by blank lines so
- * commitlint's per-line caps (`body-max-line-length` and
- * `footer-max-line-length`, both default 100) all pass:
- *
- *   1. Header sentence.
- *   2. Body prose listing each file and its discarded line count.
- *   3. `Auto-resolved-file:` trailers — one per file, path only, so the
- *      verbose line count never appears on the footer line.
- *
- * Paths that would still bust the per-line cap are middle-truncated with
- * an ellipsis. This is a last-resort safety net for pathological repo
- * layouts; the common case (short relative paths) emits the full path.
- *
- * Exported for contract testing of the cap behaviour.
- *
- * @param {Array<{ file: string, discardedLines: number }>} resolved
- * @param {{ maxLineLength?: number }} [opts]
- * @returns {string}
- */
-export function buildAutoResolveTrailer(resolved, opts = {}) {
-  const maxLineLength = opts.maxLineLength ?? 100;
-  const header =
-    'Auto-resolved-conflicts: accepted feature branch for the following file(s).';
-
-  const bodyLines = resolved.map((r) => {
-    const suffix = `: discarded ${r.discardedLines} base line(s)`;
-    const prefix = '- ';
-    const available = maxLineLength - prefix.length - suffix.length;
-    return `${prefix}${truncatePathForLine(r.file, available)}${suffix}`;
-  });
-
-  const trailerKey = 'Auto-resolved-file: ';
-  const trailerLines = resolved.map((r) => {
-    const available = maxLineLength - trailerKey.length;
-    return `${trailerKey}${truncatePathForLine(r.file, available)}`;
-  });
-
-  return `${header}\n\n${bodyLines.join('\n')}\n\n${trailerLines.join('\n')}`;
-}
-
-/**
- * Middle-truncate a path with an ellipsis so it fits within `max`
- * characters. When `max` is too small to keep any meaningful slice
- * (≤ 4 chars after the ellipsis), the leading characters win — the
- * tail is dropped and an ellipsis is appended. Pure helper, no I/O.
- *
- * @param {string} p
- * @param {number} max
- * @returns {string}
- */
-function truncatePathForLine(p, max) {
-  if (max <= 0) return '…';
-  if (p.length <= max) return p;
-  const ellipsis = '…';
-  const keep = max - ellipsis.length;
-  if (keep <= 4) return `${p.slice(0, max - 1)}${ellipsis}`;
-  const head = Math.ceil(keep / 2);
-  const tail = Math.floor(keep / 2);
-  return `${p.slice(0, head)}${ellipsis}${p.slice(p.length - tail)}`;
-}

package/.agents/scripts/lib/observability/baseline-refresh-rate.js

@@ -1,221 +0,0 @@
-/**
- * baseline-refresh-rate.js — pure reporter for the per-Epic baseline-refresh
- * commit rate (Epic #1386, Story #1400).
- *
- * The "baseline-refresh discipline" (Story #1124, Tech Spec #902) requires
- * that every Story whose merge introduces baseline drift land an explicit
- * `baseline-refresh:` commit in the same close PR (or, post Story #1398,
- * fold the refresh into the close commit itself). The 90% target — that
- * at least 90% of merged Stories per Epic land without leaving baseline
- * drift behind — needs a measurable signal so retros can spot regressions
- * before they leak into `main`.
- *
- * This module exports a single pure function that takes a fixture of
- * commit records (one per Story-attributable commit on `epic/<id>` over
- * the trailing window) and returns:
- *
- *   - per-Epic counts of `baseline-refresh:` commits
- *   - per-Epic counts of merged Stories
- *   - per-Epic percentage of merged Stories that did NOT land a
- *     baseline-refresh commit (the "clean-merge" rate)
- *
- * The caller (analyze-execution.js) is responsible for shelling out to
- * `git log` and resolving each commit to its parent Epic ID — this
- * module touches no I/O so the test fixture can pin behavior without a
- * temp git repo or stubbed spawn.
- *
- * Default window is 4 weeks (28 days). Pass `windowDays` to override
- * (e.g., `windowDays: 14` for a fortnightly retro).
- *
- * Aligned with `perf-aggregator.js`: empty input yields a well-formed
- * empty payload, malformed records are silently skipped, the function
- * never throws on bad data.
- */
-
-import { isObject } from '../json-utils.js';
-import { RESOLVES_TRAILER_RE } from '../orchestration/resolves-token.js';
-
-const BASELINE_REFRESH_PREFIX = 'baseline-refresh:';
-const DEFAULT_WINDOW_DAYS = 28;
-
-/**
- * Coerce an ISO-8601 date string to epoch ms. Returns NaN for malformed
- * input so the caller's window filter drops the record.
- */
-function toEpochMs(iso) {
-  if (typeof iso !== 'string' || iso.length === 0) return Number.NaN;
-  const ms = Date.parse(iso);
-  return Number.isFinite(ms) ? ms : Number.NaN;
-}
-
-/**
- * Classify a commit by its subject line.
- *
- *   - `baseline-refresh:` prefix → refresh commit
- *   - subject containing `(resolves #N)` → Story-merge commit
- *   - everything else → ignored (chore commits, baseline-only fixes, etc.)
- *
- * The classification is deliberately disjoint: a `baseline-refresh:`
- * commit is never counted as a Story merge, and a Story merge is never
- * counted as a baseline-refresh — even if the subject happens to mention
- * both keywords. This matches the on-the-ground convention: refreshes
- * land as their own commit (or amended into the close), Stories land as
- * `feat: ... (resolves #N)`.
- */
-function classifySubject(subject) {
-  if (typeof subject !== 'string' || subject.length === 0) return 'other';
-  if (subject.startsWith(BASELINE_REFRESH_PREFIX)) return 'refresh';
-  if (RESOLVES_TRAILER_RE.test(subject)) return 'story';
-  return 'other';
-}
-
-/**
- * Compute the trailing-window cutoff in epoch ms. Exported on the
- * exported function via the `now` option so tests can pin the clock.
- */
-function computeCutoffMs(nowMs, windowDays) {
-  const days =
-    Number.isFinite(windowDays) && windowDays > 0
-      ? windowDays
-      : DEFAULT_WINDOW_DAYS;
-  return nowMs - days * 24 * 60 * 60 * 1000;
-}
-
-/**
- * Pure reporter for the per-Epic baseline-refresh commit rate.
- *
- * @param {Iterable<{
- *   sha?: string,
- *   isoDate: string,
- *   subject: string,
- *   epicId: number | string | null,
- * }>} commits
- *   Commit records from the caller. Records missing `epicId` (the commit
- *   isn't on any Epic branch) are dropped. Records older than the window
- *   are also dropped. Order does not matter — the function aggregates by
- *   Epic regardless of input ordering.
- *
- * @param {object} [opts]
- * @param {number} [opts.windowDays] — trailing window in days (default 28).
- * @param {() => Date | number} [opts.now] — clock injector for tests.
- *   Accepts either a Date or epoch-ms; defaults to `() => Date.now()`.
- *
- * @returns {{
- *   kind: 'baseline-refresh-rate',
- *   windowDays: number,
- *   generatedAt: string,
- *   cutoffAt: string,
- *   perEpic: Array<{
- *     epicId: number | string,
- *     storyMerges: number,
- *     baselineRefreshes: number,
- *     cleanMergeRate: number,
- *   }>,
- *   totals: {
- *     storyMerges: number,
- *     baselineRefreshes: number,
- *     cleanMergeRate: number,
- *   },
- * }}
- *
- * `cleanMergeRate` is the fraction of merged Stories that did NOT need a
- * baseline-refresh commit follow-up (or amend), in `[0, 1]` rounded to
- * 4 decimal places. The 90% target is `cleanMergeRate >= 0.9`. When
- * `storyMerges === 0`, the rate is `1` (vacuously clean — no Stories,
- * no drift) so a quiet Epic doesn't show up as red.
- */
-export function computeBaselineRefreshRate(commits, opts = {}) {
-  const nowFn = opts.now ?? (() => Date.now());
-  const nowVal = nowFn();
-  const nowMs = nowVal instanceof Date ? nowVal.getTime() : Number(nowVal);
-  const windowDays =
-    Number.isFinite(opts.windowDays) && opts.windowDays > 0
-      ? Math.floor(opts.windowDays)
-      : DEFAULT_WINDOW_DAYS;
-  const cutoffMs = computeCutoffMs(nowMs, windowDays);
-
-  // Map<epicId, { storyMerges, baselineRefreshes }>. Insertion order is
-  // preserved so the output array is stable for snapshot-style assertions.
-  const perEpic = new Map();
-  const ensureBucket = (epicId) => {
-    if (!perEpic.has(epicId)) {
-      perEpic.set(epicId, { storyMerges: 0, baselineRefreshes: 0 });
-    }
-    return perEpic.get(epicId);
-  };
-
-  for (const raw of commits ?? []) {
-    if (!isObject(raw)) continue;
-    const epicId = raw.epicId;
-    if (epicId == null || epicId === '') continue;
-    const ts = toEpochMs(raw.isoDate);
-    if (!Number.isFinite(ts)) continue;
-    if (ts < cutoffMs) continue;
-
-    const klass = classifySubject(raw.subject);
-    if (klass === 'other') continue;
-
-    const bucket = ensureBucket(epicId);
-    if (klass === 'refresh') bucket.baselineRefreshes += 1;
-    else if (klass === 'story') bucket.storyMerges += 1;
-  }
-
-  const perEpicRows = [];
-  let totalStories = 0;
-  let totalRefreshes = 0;
-  for (const [epicId, counts] of perEpic) {
-    const cleanMergeRate =
-      counts.storyMerges === 0
-        ? 1
-        : Math.max(
-            0,
-            Math.min(
-              1,
-              (counts.storyMerges - counts.baselineRefreshes) /
-                counts.storyMerges,
-            ),
-          );
-    perEpicRows.push({
-      epicId,
-      storyMerges: counts.storyMerges,
-      baselineRefreshes: counts.baselineRefreshes,
-      cleanMergeRate: roundRate(cleanMergeRate),
-    });
-    totalStories += counts.storyMerges;
-    totalRefreshes += counts.baselineRefreshes;
-  }
-
-  const totalsClean =
-    totalStories === 0
-      ? 1
-      : Math.max(
-          0,
-          Math.min(1, (totalStories - totalRefreshes) / totalStories),
-        );
-
-  return {
-    kind: 'baseline-refresh-rate',
-    windowDays,
-    generatedAt: new Date(nowMs).toISOString(),
-    cutoffAt: new Date(cutoffMs).toISOString(),
-    perEpic: perEpicRows,
-    totals: {
-      storyMerges: totalStories,
-      baselineRefreshes: totalRefreshes,
-      cleanMergeRate: roundRate(totalsClean),
-    },
-  };
-}
-
-function roundRate(rate) {
-  if (!Number.isFinite(rate)) return 0;
-  return Math.round(rate * 10000) / 10000;
-}
-
-// Exported for unit tests that want to assert the classifier directly
-// without round-tripping through the aggregator.
-export const __test__ = {
-  classifySubject,
-  computeCutoffMs,
-  DEFAULT_WINDOW_DAYS,
-};

package/.agents/scripts/lib/observability/hook-heartbeat.js

@@ -1,187 +0,0 @@
-/**
- * hook-heartbeat.js — Epic #4476 (M5): heartbeats OFF the token stream.
- *
- * Before M5, the `story.heartbeat` / `slice.heartbeat` forward-progress
- * signal that idle-watchdog consumers read from the lifecycle ledger was an
- * **LLM obligation**: the delivery workflow instructed the agent to run
- * `story-phase.js` / `slice-phase.js --event heartbeat` at least once per
- * meaningful step, and every such call was a full-priced LLM turn re-reading
- * ~100k of cached context just to append one NDJSON line.
- *
- * This module makes that liveness signal a **free byproduct of the agent
- * doing any work**. It is invoked from the existing PostToolUse trace hook
- * (`tool-trace-hook.js`), so every tool call the agent makes refreshes the
- * heartbeat — no dedicated bookkeeping turn required. The record it appends is
- * byte-for-byte the same `story.heartbeat` / `slice.heartbeat` shape the
- * watchdog already consumes (emitted through the same
- * `emit-story-heartbeat.js` / `emit-slice-lifecycle.js` emitters), so the
- * watchdog needs no change: the signal is preserved, only its emission
- * mechanism moves off the token stream.
- *
- * ## Robustness contract (mirrors `tool-trace-hook.js`)
- *   - **No-op outside an active Story with an Epic-scoped ledger.** When a
- *     valid `{ CC_EPIC_ID, CC_STORY_ID }` pair is not present in the
- *     environment (v2 standalone Stories omit `CC_EPIC_ID`), `emitHeartbeatFromHook`
- *     returns without touching the filesystem.
- *   - **Best-effort.** Every failure is swallowed. A heartbeat is
- *     observability, not state; a hook must never block tool execution.
- *   - **Throttled across processes.** Command hooks are spawned as fresh
- *     `node` processes per tool call, so in-process state cannot throttle. The
- *     throttle is anchored to the **mtime of a sidecar marker file** under the
- *     Epic temp dir: at most one heartbeat per `HEARTBEAT_MIN_INTERVAL_MS`
- *     lands, regardless of how many tool calls fire in that window. This keeps
- *     the ledger from ballooning while still refreshing liveness faster than
- *     the watchdog's threshold.
- */
-
-import { statSync, utimesSync, writeFileSync } from 'node:fs';
-import path from 'node:path';
-
-import { epicTempDir } from '../config/temp-paths.js';
-import { emitStoryHeartbeat } from '../orchestration/lifecycle/emit-story-heartbeat.js';
-
-/**
- * Default minimum wall-clock gap between two hook-emitted heartbeats for the
- * same target. Comfortably below the watchdog's default 30-minute staleness
- * threshold, so an actively-working agent never trips a false stall, while
- * still bounding ledger growth to ~1 line/minute of activity.
- */
-const HEARTBEAT_MIN_INTERVAL_MS = 60_000;
-
-/**
- * Resolve the heartbeat target from the active-Story / active-slice env vars.
- *
- * A `story.heartbeat` requires a parent `epicId` (its schema pins
- * `epicId >= 1`), so a **standalone** Story (`CC_STORY_ID` set, `CC_EPIC_ID`
- * absent) yields `null` — there is no Epic-scoped ledger to write to and the
- * standalone path is not watched by the Epic idle watchdog. The trace hook
- * still records that context's traces; only the heartbeat is skipped.
- *
- * Inert `slice.*` lifecycle (and `CC_SLICE_ID` heartbeats) were removed in
- * the v2 ceremony lock-in — `## Slicing` is prose-only.
- *
- * @param {NodeJS.ProcessEnv} [env]
- * @returns {{ kind: 'story', epicId: number, storyId: number, operator?: string }
- *          | null}
- */
-export function resolveHeartbeatTarget(env = process.env) {
-  const epicRaw = env.CC_EPIC_ID;
-  const storyRaw = env.CC_STORY_ID;
-  const operator =
-    typeof env.CC_OPERATOR === 'string' && env.CC_OPERATOR.length > 0
-      ? env.CC_OPERATOR
-      : undefined;
-
-  const epicId = epicRaw ? Number.parseInt(epicRaw, 10) : Number.NaN;
-  const epicOk = Number.isInteger(epicId) && epicId > 0;
-
-  if (storyRaw) {
-    const storyId = Number.parseInt(storyRaw, 10);
-    if (!Number.isInteger(storyId) || storyId <= 0) return null;
-    // story.heartbeat has no meaning without a parent Epic ledger.
-    if (!epicOk) return null;
-    return {
-      kind: 'story',
-      epicId,
-      storyId,
-      ...(operator ? { operator } : {}),
-    };
-  }
-
-  return null;
-}
-
-/**
- * Stable, filesystem-safe marker basename for a target. The marker's mtime is
- * the throttle anchor; its contents are irrelevant.
- *
- * @param {{ kind: string, storyId?: number, sliceId?: string }} target
- * @returns {string}
- */
-export function heartbeatMarkerName(target) {
-  return `.heartbeat-story-${target.storyId}`;
-}
-
-/**
- * Throttle predicate. Returns `true` when no marker exists yet, or the marker
- * is older than `intervalMs`. Any stat error (missing file / unreadable) is
- * treated as "emit" — the safe direction for a liveness signal.
- *
- * @param {{ markerPath: string, now: Date, intervalMs: number, statFn?: typeof statSync }} args
- * @returns {boolean}
- */
-export function shouldEmitHeartbeat({
-  markerPath,
-  now,
-  intervalMs,
-  statFn = statSync,
-}) {
-  try {
-    const st = statFn(markerPath);
-    return now.getTime() - st.mtimeMs >= intervalMs;
-  } catch {
-    return true;
-  }
-}
-
-/**
- * Update (or create) the throttle marker so its mtime is `now`. Best-effort:
- * a failure here at worst lets the next tool call emit a second heartbeat.
- *
- * @param {string} markerPath
- * @param {Date} now
- */
-function touchMarker(markerPath, now) {
-  try {
-    writeFileSync(markerPath, '', { flag: 'a' });
-    utimesSync(markerPath, now, now);
-  } catch {
-    // swallow — throttle degrades to "emit again next call", never fatal.
-  }
-}
-
-/**
- * Emit one throttled heartbeat for the active target, if any. The whole body
- * is best-effort: any failure returns a `{ emitted: false }` envelope rather
- * than throwing, so the calling PostToolUse hook never blocks the tool.
- *
- * @param {object} [opts]
- * @param {NodeJS.ProcessEnv} [opts.env]        Defaults to `process.env`.
- * @param {Date} [opts.now]                     Injected clock (tests).
- * @param {number} [opts.intervalMs]            Throttle window.
- * @param {object} [opts.config]                Resolved config (tempRoot).
- * @returns {{ emitted: boolean, reason?: string, kind?: string, ledgerPath?: string }}
- */
-export function emitHeartbeatFromHook({
-  env = process.env,
-  now = new Date(),
-  intervalMs = HEARTBEAT_MIN_INTERVAL_MS,
-  config,
-} = {}) {
-  try {
-    const target = resolveHeartbeatTarget(env);
-    if (!target) return { emitted: false, reason: 'no-target' };
-
-    const markerPath = path.join(
-      epicTempDir(target.epicId, config),
-      heartbeatMarkerName(target),
-    );
-    if (!shouldEmitHeartbeat({ markerPath, now, intervalMs })) {
-      return { emitted: false, reason: 'throttled', kind: target.kind };
-    }
-
-    const timestamp = now.toISOString();
-    const res = emitStoryHeartbeat({
-      epicId: target.epicId,
-      storyId: target.storyId,
-      phase: 'implementing',
-      timestamp,
-      ...(target.operator ? { operator: target.operator } : {}),
-      config: config ?? undefined,
-    });
-    touchMarker(markerPath, now);
-    return { emitted: true, kind: target.kind, ledgerPath: res?.ledgerPath };
-  } catch {
-    return { emitted: false, reason: 'error' };
-  }
-}