mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/story-follow-ups.js

@@ -0,0 +1,298 @@
+/**
+ * story-follow-ups.js — capture actionable follow-ups from a landed Story.
+ *
+ * Replaces the unwired Epic retro as the default closeout for v2: after a
+ * Story merges, read its standalone `signals.ndjson` friction stream, compose
+ * routed proposals, auto-file follow-up issues (when enabled), and upsert a
+ * structured `follow-ups` comment on the Story.
+ *
+ * @module lib/orchestration/story-follow-ups
+ */
+
+import { graduateRetroProposals } from '../feedback-loop/retro-proposals-graduator.js';
+import { DEFAULT_FRAMEWORK_REPO } from '../github/framework-repo.js';
+import { Logger } from '../Logger.js';
+import { forEachLine } from '../observability/signals-writer.js';
+import { composeRoutedProposals } from './retro-proposals.js';
+import { upsertStructuredComment } from './ticketing.js';
+
+export const FOLLOW_UPS_COMMENT_TYPE = 'follow-ups';
+
+/**
+ * @param {object} [config]
+ * @returns {{ frameworkRepo: string, consumerRepo: string, currentRepo: { owner: string, repo: string } }}
+ */
+export function resolveFollowUpRepos(config) {
+  const owner =
+    typeof config?.github?.owner === 'string' ? config.github.owner.trim() : '';
+  const repo =
+    typeof config?.github?.repo === 'string' ? config.github.repo.trim() : '';
+  const consumerRepo =
+    owner && repo ? `${owner}/${repo}` : DEFAULT_FRAMEWORK_REPO;
+  const frameworkRepo =
+    typeof config?.github?.frameworkRepo === 'string' &&
+    config.github.frameworkRepo.trim()
+      ? config.github.frameworkRepo.trim()
+      : DEFAULT_FRAMEWORK_REPO;
+  const [cOwner, cRepo] = consumerRepo.split('/');
+  return {
+    frameworkRepo,
+    consumerRepo,
+    currentRepo: {
+      owner: cOwner || 'unknown',
+      repo: cRepo || 'unknown',
+    },
+  };
+}
+
+/**
+ * @param {number} storyId
+ * @param {object} [config]
+ * @returns {Promise<Array<{ category: string, source: 'framework'|'consumer' }>>}
+ */
+export async function gatherStoryFrictionSignals(storyId, config) {
+  const signals = [];
+  await forEachLine(
+    null,
+    storyId,
+    (parsed) => {
+      if (!parsed || typeof parsed !== 'object') return;
+      const kind = parsed.kind;
+      if (kind !== 'friction' && kind !== undefined) {
+        // Prefer friction records; also accept category-bearing rows.
+      }
+      const category =
+        typeof parsed.category === 'string' ? parsed.category.trim() : '';
+      if (!category) return;
+      const source = parsed.source === 'framework' ? 'framework' : 'consumer';
+      signals.push({ category, source });
+    },
+    config,
+  );
+  return signals;
+}
+
+/**
+ * Render the empty-roll-up line.
+ *
+ * Story #4578 — an empty roll-up over a multi-Story run must NOT read as
+ * success. The pre-#4578 text ("No friction signals — nothing to follow up")
+ * was *truthful* about the stream and *false* about the run: a 7-Story
+ * delivery containing a mid-run git outage, a parked worker, and a
+ * four-round acceptance critic rendered byte-identically to a genuinely
+ * clean run. An operator cannot tell "nothing went wrong" from "the
+ * telemetry never fired", and the second is likeliest exactly when the run
+ * went worst.
+ *
+ * So the line is a function of `storyCount`:
+ *   - `storyCount <= 1` → the honest, quiet reading is retained. A single
+ *     Story that emitted nothing plausibly *was* clean, and crying wolf on
+ *     every clean Story is how a warning channel gets tuned out.
+ *   - `storyCount > 1`  → zero signals across N Stories is a **claim**, and
+ *     the surrounding text says so and names the two readings, rather than
+ *     asserting the flattering one.
+ *
+ * This mirrors the sibling precedent in `run-epilogue.js`'s
+ * `renderDiffLines`, which refuses to let an unresolvable base diff render
+ * as "0 changed files".
+ *
+ * @param {number} storyCount
+ * @returns {string[]}
+ */
+function renderEmptyRollupLines(storyCount) {
+  if (storyCount <= 1) {
+    return ['_No friction signals — nothing to follow up._'];
+  }
+  return [
+    `> ⚠️ **0 friction signals across ${storyCount} Stories — this is a claim, not a clean bill of health.**`,
+    '> Either the run was genuinely friction-free, or telemetry never fired.',
+    '> An empty stream is indistinguishable from a clean run, and it is least',
+    '> likely to fill exactly when a run is going badly and the agent is busy.',
+    '> The runtime emits friction from its own observables (`agent::blocked`',
+    '> transitions, failed closes, exhausted merge waits) — so zero here also',
+    '> means none of those fired. If the run had friction you can name, that',
+    '> gap is itself the follow-up worth filing.',
+  ];
+}
+
+/**
+ * @param {{
+ *   storyId: number,
+ *   proposals: object,
+ *   graduated: object,
+ *   storyCount?: number,
+ * }} args - `storyCount` (default 1) is how many Stories the roll-up spans;
+ *   it decides whether an empty result reads as quiet or as a flagged claim.
+ * @returns {string}
+ */
+export function buildFollowUpsCommentBody({
+  storyId,
+  proposals,
+  graduated,
+  storyCount = 1,
+}) {
+  const filed = Array.isArray(graduated?.filed) ? graduated.filed : [];
+  const framework = proposals?.framework ?? [];
+  const consumer = proposals?.consumer ?? [];
+  const discarded = proposals?.discarded ?? [];
+  const lines = [
+    '### follow-ups',
+    '',
+    `Actionable follow-ups captured from Story #${storyId} after merge.`,
+    '',
+  ];
+  if (filed.length > 0) {
+    lines.push('**Filed**');
+    for (const item of filed) {
+      lines.push(
+        `- ${item.source}: ${item.title}${item.url ? ` — ${item.url}` : ''}`,
+      );
+    }
+    lines.push('');
+  }
+  if (framework.length + consumer.length > 0 && filed.length === 0) {
+    lines.push('**Actionable (not auto-filed)**');
+    for (const item of [...framework, ...consumer]) {
+      lines.push(`- ${item.source}: ${item.title}`);
+      lines.push('');
+      lines.push('```bash');
+      lines.push(item.command);
+      lines.push('```');
+    }
+    lines.push('');
+  }
+  if (discarded.length > 0) {
+    lines.push('**Single-occurrence (not filed)**');
+    for (const item of discarded) {
+      lines.push(`- ${item.source}: \`${item.category}\` ×${item.occurrences}`);
+    }
+    lines.push('');
+  }
+  if (
+    filed.length === 0 &&
+    framework.length === 0 &&
+    consumer.length === 0 &&
+    discarded.length === 0
+  ) {
+    lines.push(...renderEmptyRollupLines(storyCount));
+    lines.push('');
+  }
+  lines.push('```json');
+  lines.push(
+    JSON.stringify(
+      {
+        storyId,
+        storyCount,
+        framework: framework.map((i) => i.category),
+        consumer: consumer.map((i) => i.category),
+        discarded: discarded.map((i) => i.category),
+        filed: filed.map((i) => ({
+          category: i.category,
+          url: i.url ?? null,
+        })),
+        // Story #4578 — an empty roll-up over N>1 Stories is a claim worth
+        // flagging, not a success. Machine-readable twin of the warning
+        // prose so a caller need not regex the body.
+        emptyRollupSuspect:
+          storyCount > 1 &&
+          filed.length === 0 &&
+          framework.length === 0 &&
+          consumer.length === 0 &&
+          discarded.length === 0,
+      },
+      null,
+      2,
+    ),
+  );
+  lines.push('```');
+  return lines.join('\n');
+}
+
+/**
+ * Capture and persist Story follow-ups. Never throws — the land must not
+ * fail because follow-up filing flaked.
+ *
+ * Story #4543 retired the `captureFollowUpsAfterConfirm` action-gate wrapper
+ * (and its `withConfirmFollowUps` sibling) that used to front this function.
+ * Re-deriving "did the merge land?" from a confirmation envelope's `action`
+ * field was the coupling that made close-and-land — the DEFAULT path — skip
+ * capture entirely: the gate only opened on the standalone CLI's `done`, and
+ * a belated manual confirm could not backfill because the Story was already
+ * `agent::done` (confirm returns `noop`, the gate never opens). The shared
+ * land tail (`single-story-close/phases/post-land.js`) now calls this
+ * directly, after the merge is already confirmed.
+ *
+ * @param {object} args
+ * @param {number} args.storyId
+ * @param {object} args.provider
+ * @param {object} [args.config]
+ * @param {string} [args.cwd]
+ * @param {(tag: string, msg: string) => void} [args.progress]
+ * @returns {Promise<object>}
+ */
+export async function captureStoryFollowUps({
+  storyId,
+  provider,
+  config,
+  cwd,
+  progress,
+}) {
+  const sid = Number(storyId);
+  if (!Number.isInteger(sid) || sid <= 0) {
+    return { ok: false, reason: 'invalid-story-id' };
+  }
+  try {
+    const signals = await gatherStoryFrictionSignals(sid, config);
+    const repos = resolveFollowUpRepos(config);
+    const proposals = composeRoutedProposals({
+      anchorId: sid,
+      anchorKind: 'story',
+      frameworkRepo: repos.frameworkRepo,
+      consumerRepo: repos.consumerRepo,
+      signals,
+      unresolvedBlockedEvents: [],
+    });
+    const graduated = await graduateRetroProposals({
+      epicId: sid,
+      provider,
+      config,
+      currentRepo: repos.currentRepo,
+      frameworkRepo: (() => {
+        const [owner, repo] = repos.frameworkRepo.split('/');
+        return { owner, repo };
+      })(),
+      routedProposals: proposals,
+      cwd,
+    });
+    const body = buildFollowUpsCommentBody({
+      storyId: sid,
+      proposals,
+      graduated,
+    });
+    await upsertStructuredComment(provider, sid, FOLLOW_UPS_COMMENT_TYPE, body);
+    progress?.(
+      'FOLLOW-UPS',
+      `Captured follow-ups for Story #${sid} (filed=${graduated.filed?.length ?? 0}).`,
+    );
+    return {
+      ok: true,
+      storyId: sid,
+      proposals,
+      graduated,
+      signalCount: signals.length,
+    };
+  } catch (err) {
+    Logger.warn(
+      `[story-follow-ups] capture failed for #${sid}: ${err?.message ?? err}`,
+    );
+    progress?.(
+      'FOLLOW-UPS',
+      `⚠️ Follow-up capture failed (close continues): ${err?.message ?? err}`,
+    );
+    return {
+      ok: false,
+      reason: 'capture-failed',
+      error: String(err?.message ?? err),
+    };
+  }
+}

package/.agents/scripts/lib/orchestration/story-init-remote.js

@@ -0,0 +1,51 @@
+import { Logger } from '../Logger.js';
+import {
+  STATE_LABELS,
+  transitionTicketState,
+  upsertStructuredComment,
+} from './ticketing.js';
+
+/**
+ * Fail closed when the repository remote cannot be verified. The Story is
+ * blocked before lease/branch/worktree mutation so a host that misses the
+ * result envelope cannot strand an executing Story.
+ */
+export async function handleRemoteVerificationFailure({
+  provider,
+  storyId,
+  remote,
+  dryRun = false,
+}) {
+  if (remote?.remoteVerified) return;
+  const message =
+    `[single-story-init] remote verification failed for Story #${storyId}: ` +
+    `${remote?.detail ?? 'origin is unavailable'}`;
+  if (!dryRun) {
+    try {
+      await upsertStructuredComment(
+        provider,
+        storyId,
+        'friction',
+        `### Remote verification blocked delivery\n\n${message}`,
+      );
+    } catch (err) {
+      Logger.warn(
+        `[single-story-init] failed to post remote-verification friction: ${err?.message ?? err}`,
+      );
+    }
+    // Story #4539 — the canonical mutator. This is the path where the
+    // skipped Projects v2 column sync (Story #2548) visibly drifts: the
+    // Story is still agent::ready (To Do) when the remote probe fails, so
+    // a direct label write leaves the board reading To Do for a blocked
+    // Story. single-story-init.js's own comment explains exactly why this
+    // must not bypass the mutator.
+    try {
+      await transitionTicketState(provider, storyId, STATE_LABELS.BLOCKED, {});
+    } catch (err) {
+      Logger.warn(
+        `[single-story-init] failed to block Story after remote verification: ${err?.message ?? err}`,
+      );
+    }
+  }
+  throw new Error(message);
+}

package/.agents/scripts/lib/orchestration/story-plan-state.js

@@ -0,0 +1,33 @@
+/**
+ * story-plan-state.js — read the v2 Story planning checkpoint.
+ *
+ * `plan-persist.js` upserts one `story-plan-state` structured comment per
+ * created Story carrying the persist receipt (when the plan completed, how many
+ * Stories it created, and their ids). Story #4542 removed the risk fields it
+ * used to carry: the planner-authored verdict, the envelope derived from it,
+ * and the review routing computed from that envelope. Nothing read any of them
+ * back — review depth is now derived from the diff at close time
+ * (`review-depth.js#deriveChangeLevel`), so no checkpoint read sits on the
+ * delivery path at all.
+ */
+
+import { parseFencedJsonComment } from './structured-comment-parser.js';
+import { findStructuredComment } from './ticketing.js';
+
+/**
+ * Read the v2 Story planning checkpoint. Missing/malformed comments degrade
+ * to null — an unplanned Story simply has no persist receipt.
+ */
+export async function readStoryPlanState({
+  provider,
+  storyId,
+  findCommentFn = findStructuredComment,
+}) {
+  const comment = await findCommentFn(
+    provider,
+    Number(storyId),
+    'story-plan-state',
+  );
+  const state = parseFencedJsonComment(comment);
+  return state && typeof state === 'object' ? state : null;
+}

package/.agents/scripts/lib/orchestration/structured-comment-parser.js

@@ -2,7 +2,7 @@
  * structured-comment-parser.js — shared parser for fenced-JSON structured
  * comments.
  *
- * Several callers (epic-runner Checkpointer, ProgressReporter
+ * Several callers (the deleted epic-runner Checkpointer/ProgressReporter,
  * `parseStoryRunProgressComment` / `parsePhaseTimingsComment`, wave-gate's
  * local `extractJsonBlock`) need to extract the `{...}` payload from the
  * fenced ```json``` block of a structured comment body. They had each open-

package/.agents/scripts/lib/orchestration/task-body-validator.js

@@ -24,16 +24,23 @@
  * name at least one path-shaped token so vague verbs ("clean up",
  * "refactor") can't slip through.
  *
- * `body.changes` items may be either:
- *   1. A string bullet (legacy shape, e.g. `"src/foo.ts: extract handler"`).
- *   2. An object `{ path: string, assumption: enum }` (Story #2636 shape).
+ * `acceptance` / `verify` are the **top-level machine contract** (Story
+ * #4541). The decomposer prompt tells authors to write those lists once at
+ * the ticket's top level and omit the matching body sections; persist syncs
+ * them into the body at assemble time. Validation runs *before* that sync,
+ * so this validator resolves each contract field from the parsed body and
+ * falls back to the ticket's top-level array when the body section is
+ * absent. Without that fallback the validator rejected the very shape its
+ * own prompt prescribes.
+ *
+ * `body.changes` items must be object-form `{ path: string, assumption: enum }`
+ * entries (Story #2636 shape). Plain string bullets are rejected at parse
+ * time and by this validator.
  *
  * Object-form items must declare an `assumption` ∈ `creates |
  * refactors-existing | exists | deletes`. The optional `body.references`
  * array uses the same object shape and is the home for paths the Story
  * reads but does not modify (test fixtures, sibling modules, etc.).
- * String-form `changes` items remain legal so legacy plans keep parsing,
- * but they emit a deprecation signal via `validateStoryFileAssumptions`.
  *
  * `body.verify` entries must either name a testing tier in parentheses
  * drawn from `VERIFY_TIER_VALUES` (e.g. `npm run test (unit)`) or be the
@@ -53,8 +60,8 @@ import { FILE_ASSUMPTION_VALUES } from './file-assumption-enum.js';
 
 /**
  * Canonical testing-tier labels that a `verify[]` entry must name (in
- * parentheses) to pass plan-time validation. Mirrors the skill contract in
- * `core/epic-plan-decompose-author/SKILL.md § verify rules`.
+ * parentheses) to pass plan-time validation. Mirrors the verify-rules contract
+ * in `.agents/scripts/lib/templates/decomposer-prompts.js`.
  *
  * Entries that do not end with `(<tier>)` and are not `manual:<reason>` are
  * rejected by `collectVerifyErrors`.
@@ -166,6 +173,39 @@ function resolveStructuredBody(ticket) {
   }
 }
 
+/**
+ * The two contract fields that live at the ticket's top level and are
+ * synced into the body by `plan-persist` at assemble time.
+ */
+const CONTRACT_FIELDS = Object.freeze(['acceptance', 'verify']);
+
+/**
+ * Resolve the body's contract fields against the ticket's top-level arrays
+ * (Story #4541). The decomposer prompt prescribes authoring `acceptance[]`
+ * / `verify[]` **once** at top level and omitting the matching body
+ * sections; `assemblePlanStories#syncContractFieldFromTopLevel` performs
+ * the sync, but it runs *after* validation. So an absent body section is
+ * not a violation when the ticket carries the list at top level — it is the
+ * preferred shape. A body section that is present and disagrees with the
+ * top level is left alone here: the sync itself fails closed on that
+ * mismatch, and duplicating the check would report it twice.
+ *
+ * @param {object} ticket
+ * @param {object} bodyObject Parsed / structured body.
+ * @returns {object} A copy of `bodyObject` with the contract fields resolved.
+ */
+function resolveContractFieldsFromTopLevel(ticket, bodyObject) {
+  const resolved = { ...bodyObject };
+  for (const field of CONTRACT_FIELDS) {
+    const bodyValue = Array.isArray(resolved[field]) ? resolved[field] : [];
+    if (bodyValue.length > 0) continue;
+    const topLevel = Array.isArray(ticket?.[field]) ? ticket[field] : [];
+    if (topLevel.length === 0) continue;
+    resolved[field] = topLevel.map(String);
+  }
+  return resolved;
+}
+
 /**
  * Validate one Story body and return every violation it exhibits. Empty
  * array means clean. Splits the per-ticket cascade out of
@@ -184,13 +224,14 @@ function resolveStructuredBody(ticket) {
  */
 export function validateTaskBodyShape(ticket) {
   const prefix = `Story "${ticket.title}" (${ticket.slug})`;
-  const { body, error } = resolveStructuredBody(ticket);
+  const { body: parsed, error } = resolveStructuredBody(ticket);
   if (error !== null) {
     return [error];
   }
-  if (body === null || typeof body !== 'object') {
-    return [`${prefix}: body must be an object, got ${typeof body}.`];
+  if (parsed === null || typeof parsed !== 'object') {
+    return [`${prefix}: body must be an object, got ${typeof parsed}.`];
   }
+  const body = resolveContractFieldsFromTopLevel(ticket, parsed);
   const errors = [];
   if (typeof body.goal !== 'string' || body.goal.trim() === '') {
     errors.push(`${prefix}: body.goal must be a non-empty string.`);
@@ -248,25 +289,17 @@ function collectChangesErrors(prefix, rawChanges) {
     return [`${prefix}: body.changes must list at least one bullet.`];
   }
   const errors = [];
-  // An entry "names a path" when it is either a path-shaped bullet
-  // string OR an object-form entry that passed the assumption schema.
-  const namesPath = (c) => {
-    if (typeof c === 'string') return bulletNamesPath(c);
-    return isObjectPathEntry(c);
-  };
+  const namesPath = (c) => isObjectPathEntry(c);
   if (changes.every((c) => !namesPath(c))) {
     errors.push(
-      `${prefix}: body.changes bullets name no path-shaped token. Use "<path>: <verb> <object>" — e.g. "src/components/Foo.tsx: extract handleSubmit". Object-form entries may also declare { path, assumption } directly.`,
+      `${prefix}: body.changes must declare at least one { path, assumption } object entry.`,
     );
   }
   for (const entry of changes) {
     if (typeof entry === 'string') {
-      const verb = vagueVerbWithoutTarget(entry);
-      if (verb) {
-        errors.push(
-          `${prefix}: body.changes bullet uses vague verb "${verb}" without a named target: "${entry}".`,
-        );
-      }
+      errors.push(
+        `${prefix}: body.changes entry must be a { path, assumption } object; plain string bullets are no longer accepted: "${entry}".`,
+      );
       continue;
     }
     if (isMalformedObjectPathEntry(entry)) {
@@ -310,7 +343,9 @@ function collectReferencesErrors(prefix, rawReferences) {
 function collectAcceptanceErrors(prefix, rawAcceptance) {
   const acceptance = Array.isArray(rawAcceptance) ? rawAcceptance : [];
   if (acceptance.length === 0) {
-    return [`${prefix}: body.acceptance must list at least one criterion.`];
+    return [
+      `${prefix}: acceptance must list at least one criterion — author it at the ticket's top level (preferred) or in the body's ## Acceptance section.`,
+    ];
   }
   return [];
 }
@@ -333,7 +368,7 @@ function collectVerifyErrors(prefix, rawVerify) {
   const verify = Array.isArray(rawVerify) ? rawVerify : [];
   if (verify.length === 0) {
     return [
-      `${prefix}: body.verify must list at least one entry. Use "manual:<reason>" only when truly unverifiable in isolation.`,
+      `${prefix}: verify must list at least one entry — author it at the ticket's top level (preferred) or in the body's ## Verify section. Use "manual:<reason>" only when truly unverifiable in isolation.`,
     ];
   }
   const errors = [];

package/.agents/scripts/lib/orchestration/ticket-lease.js

@@ -5,9 +5,19 @@
  * an exclusive, time-bounded claim on a ticket so two concurrent runs do not
  * both drive the same Story. Rather than invent a new state column, the lease
  * rides the ticket's existing **assignees** surface: the single assignee *is*
- * the lease owner. Liveness is decided by the owner's most-recent
- * `story.heartbeat` timestamp (the `operator` field added in this Story links
- * a heartbeat back to the claimant) compared against a configured TTL.
+ * the lease owner. Liveness is decided by the owner's last-heartbeat epoch-ms
+ * compared against a configured TTL.
+ *
+ * **There is no live heartbeat source.** The `story.heartbeat` emitter this
+ * module was designed against was structurally inert (it demanded an
+ * `epicId >= 1` that v2, which has no Epics, never supplies) and has been
+ * deleted. Every caller now reaches `acquireLease` through
+ * `lease-guard-shared.acquireLeaseFailClosed` with `anchorHeartbeatToNow`,
+ * which pins `heartbeatAt` to `now`: the lease **fails closed**, so any
+ * foreign claim reads as live and refuses. A stranded claim is cleared with
+ * `--steal`, never by TTL expiry. The TTL and the stale-reclaim branch below
+ * are therefore reachable only via an explicit caller-supplied `heartbeatAt`
+ * — the seam is kept, the automatic expiry is not real.
  *
  * The three exported operations are deliberately thin and provider-agnostic:
  *
@@ -31,19 +41,16 @@
  * Liveness seam: callers supply the owner's last-heartbeat epoch-ms via the
  * `heartbeatAt` option (a number, or `null`/`undefined` when no heartbeat has
  * ever been recorded for the current owner). Threading the timestamp in keeps
- * this module pure and trivially unit-testable — it does not read the
- * lifecycle ledger itself. A claim with no heartbeat is treated as stale
- * (reclaimable) so an abandoned assignment never wedges the ticket.
+ * this module pure and trivially unit-testable — it does not read any ledger
+ * itself. A claim with no heartbeat is treated as stale (reclaimable) by
+ * `isClaimLive`; note the live guards never take that branch, per the
+ * fail-closed anchoring described above.
  *
  * `now` is injectable (epoch ms) for deterministic tests; it defaults to
  * `Date.now()`.
  */
 
-import { readFileSync } from 'node:fs';
-
 import { resolveLeaseTtlMs } from '../config/limits.js';
-import { epicLedgerPath } from '../config/temp-paths.js';
-import { parseLedger } from './lifecycle/trace-logger.js';
 
 /**
  * The shipped, non-personal operator-identity placeholder (and its bare,
@@ -87,76 +94,22 @@ export function normalizeOperatorHandle(raw) {
   return trimmed;
 }
 
-/**
- * Read the most-recent `story.heartbeat` epoch-ms recorded for a given lease
- * owner from an Epic lifecycle ledger. Returns `null` when the ledger is
- * absent, unreadable, or carries no heartbeat for that owner — which the lease
- * primitive treats as a stale (reclaimable) claim.
- *
- * The ledger is NDJSON; each `story.heartbeat` record carries
- * `payload.operator` (Story #3480) and `payload.timestamp` (ISO-8601). A
- * malformed ledger downgrades to `null` rather than throwing so a corrupt
- * observability artifact never wedges the lease preflight.
- *
- * This is the shared liveness source the lease guards thread into
- * `acquireLease` via `heartbeatAt`; `/plan` and `/deliver` both
- * reuse it so a live foreign claim actually refuses.
- *
- * @param {object} args
- * @param {number} args.epicId
- * @param {string} args.owner            Lease owner whose heartbeat to find.
- * @param {object} [args.config]         Resolved config (for ledger path).
- * @param {string} [args.ledgerPath]     Explicit path override (tests).
- * @param {(eid: number, config?: object) => string} [args.ledgerPathResolver]
- *        Injectable resolver (tests). Defaults to `epicLedgerPath`.
- * @param {(p: string) => string} [args.readFile]  Injectable reader (tests).
- * @returns {number|null}
- */
-export function latestHeartbeatForOwner({
-  epicId,
-  owner,
-  config,
-  ledgerPath,
-  ledgerPathResolver = epicLedgerPath,
-  readFile = (p) => readFileSync(p, 'utf8'),
-}) {
-  if (typeof owner !== 'string' || owner.length === 0) return null;
-  const resolvedPath = ledgerPath ?? ledgerPathResolver(epicId, config);
-
-  let text;
-  try {
-    text = readFile(resolvedPath);
-  } catch (_err) {
-    // No ledger yet (fresh Epic) → no heartbeat → reclaimable.
-    return null;
-  }
-
-  let records;
-  try {
-    records = parseLedger(text);
-  } catch (_err) {
-    // Corrupt ledger is an observability problem, not a coordination blocker.
-    return null;
-  }
-
-  let latest = null;
-  for (const record of records) {
-    const payload = record?.payload;
-    if (!payload || payload.event !== 'story.heartbeat') continue;
-    if (payload.operator !== owner) continue;
-    const ts = Date.parse(payload.timestamp ?? '');
-    if (!Number.isFinite(ts)) continue;
-    if (latest === null || ts > latest) latest = ts;
-  }
-  return latest;
-}
-
 /**
  * Decide whether a foreign claim is still "live" given the owner's last
  * heartbeat and the configured TTL. A claim is live when a heartbeat exists
  * and is no older than `ttlMs`. A missing heartbeat (`null`/`undefined`) or a
  * heartbeat older than the TTL is stale and therefore reclaimable.
  *
+ * The `heartbeatAt` seam is retained, but there is no longer any in-repo
+ * heartbeat *source*: the `story.heartbeat` emitter was structurally inert
+ * (it required an `epicId >= 1` that v2 never sets) and was deleted along
+ * with the ledger reader that scanned for it. Every live caller reaches this
+ * through `lease-guard-shared.acquireLeaseFailClosed` with
+ * `anchorHeartbeatToNow`, which pins `heartbeatAt` to `now` so ANY foreign
+ * claim reads live and the guard fails closed — a stranded claim is cleared
+ * with `--steal`, not by TTL expiry. The parameter stays because that
+ * anchoring is expressed through it.
+ *
  * @param {object} args
  * @param {number|null|undefined} args.heartbeatAt  Owner's last heartbeat (epoch ms).
  * @param {number} args.ttlMs                        Lease TTL in milliseconds.