mandrel 1.57.0 → 1.59.0

package/.agents/scripts/lib/orchestration/code-review.js

@@ -16,7 +16,7 @@
  * chain are unchanged.
  *
  * Public API:
- *   - `runCodeReview({ epicId, provider, logger, bus, ... })` →
+ *   - `runCodeReview({ scope, ticketId, provider, logger, bus, ... })` →
  *       `{ status, severity, posted, report, halted, blockerReason }`.
  *
  * Behaviour:
@@ -302,88 +302,104 @@ function buildCodeReviewEndPayload({ epicId, result, durationMs }) {
 }
 
 /**
- * Resolve the scope envelope from the (legacy `epicId` + optional
- * `baseBranch`) shape OR the (new `scope`/`ticketId`/`headRef`/
- * `commentTargetId`) shape into a single normalized record. Extracted to
- * keep `runCodeReview` body below the CRAP-cyclomatic ceiling.
+ * Resolve the project base branch fallback used when a caller omits
+ * `baseRef`.
+ */
+function resolveConfigBase(config) {
+  return (
+    config?.project?.baseBranch ?? config?.agentSettings?.baseBranch ?? 'main'
+  );
+}
+
+/** Positive-integer override, else the supplied default. */
+function resolveCommentTargetId(commentTargetId, fallback) {
+  return Number.isInteger(commentTargetId) && commentTargetId > 0
+    ? commentTargetId
+    : fallback;
+}
+
+/**
+ * Resolve the Story-scope envelope from the parameterized
+ * `{ scope: 'story', ticketId, baseRef, headRef, commentTargetId }` shape.
  *
- * @param {{
- *   epicId?: number,
- *   scope?: 'epic'|'story',
- *   ticketId?: number,
- *   baseBranch?: string|null,
- *   baseRef?: string|null,
- *   headRef?: string|null,
- *   commentTargetId?: number|null,
- * }} opts
- * @param {object} config
  * @returns {{
- *   scope: 'epic'|'story',
+ *   scope: 'story',
  *   ticketId: number,
  *   baseRef: string,
  *   headRef: string,
  *   commentTargetId: number,
- *   epicIdForLedger: number|null,
+ *   epicIdForLedger: null,
  * }}
  */
-function resolveScopeEnvelope(opts, config) {
-  const explicitScope = opts.scope;
-  const epicIdLegacy = opts.epicId;
-  const configBase =
-    config?.project?.baseBranch ?? config?.agentSettings?.baseBranch ?? 'main';
-
-  if (explicitScope === 'story') {
-    if (!Number.isInteger(opts.ticketId) || opts.ticketId <= 0) {
-      throw new TypeError(
-        'runCodeReview: ticketId is required (positive integer) when scope="story".',
-      );
-    }
-    if (typeof opts.headRef !== 'string' || opts.headRef.length === 0) {
-      throw new TypeError(
-        'runCodeReview: headRef is required (non-empty string) when scope="story".',
-      );
-    }
-    const baseRef = opts.baseRef ?? opts.baseBranch ?? configBase;
-    const commentTargetId =
-      Number.isInteger(opts.commentTargetId) && opts.commentTargetId > 0
-        ? opts.commentTargetId
-        : opts.ticketId;
-    return {
-      scope: 'story',
-      ticketId: opts.ticketId,
-      baseRef,
-      headRef: opts.headRef,
-      commentTargetId,
-      epicIdForLedger: null,
-    };
+function resolveStoryScope(opts, config) {
+  if (!Number.isInteger(opts.ticketId) || opts.ticketId <= 0) {
+    throw new TypeError(
+      'runCodeReview: ticketId is required (positive integer) when scope="story".',
+    );
+  }
+  if (typeof opts.headRef !== 'string' || opts.headRef.length === 0) {
+    throw new TypeError(
+      'runCodeReview: headRef is required (non-empty string) when scope="story".',
+    );
   }
+  return {
+    scope: 'story',
+    ticketId: opts.ticketId,
+    baseRef: opts.baseRef ?? resolveConfigBase(config),
+    headRef: opts.headRef,
+    commentTargetId: resolveCommentTargetId(
+      opts.commentTargetId,
+      opts.ticketId,
+    ),
+    epicIdForLedger: null,
+  };
+}
 
-  // Epic scope (default + legacy `epicId` callers).
-  const effectiveEpicId =
-    Number.isInteger(opts.ticketId) && opts.ticketId > 0
-      ? opts.ticketId
-      : epicIdLegacy;
-  if (!Number.isInteger(effectiveEpicId) || effectiveEpicId <= 0) {
+/**
+ * Resolve the Epic-scope envelope from the parameterized
+ * `{ scope: 'epic', ticketId, baseRef, headRef, commentTargetId }` shape.
+ * `headRef` defaults to `epic/<ticketId>` and `baseRef` to the project
+ * base branch.
+ *
+ * @returns {{
+ *   scope: 'epic',
+ *   ticketId: number,
+ *   baseRef: string,
+ *   headRef: string,
+ *   commentTargetId: number,
+ *   epicIdForLedger: number,
+ * }}
+ */
+function resolveEpicScope(opts, config) {
+  if (!Number.isInteger(opts.ticketId) || opts.ticketId <= 0) {
     throw new TypeError(
-      'runCodeReview: epicId is required (positive integer).',
+      'runCodeReview: ticketId is required (positive integer) when scope="epic".',
     );
   }
-  const baseRef = opts.baseRef ?? opts.baseBranch ?? configBase;
-  const headRef = opts.headRef ?? `epic/${effectiveEpicId}`;
-  const commentTargetId =
-    Number.isInteger(opts.commentTargetId) && opts.commentTargetId > 0
-      ? opts.commentTargetId
-      : effectiveEpicId;
   return {
     scope: 'epic',
-    ticketId: effectiveEpicId,
-    baseRef,
-    headRef,
-    commentTargetId,
-    epicIdForLedger: effectiveEpicId,
+    ticketId: opts.ticketId,
+    baseRef: opts.baseRef ?? resolveConfigBase(config),
+    headRef: opts.headRef ?? `epic/${opts.ticketId}`,
+    commentTargetId: resolveCommentTargetId(
+      opts.commentTargetId,
+      opts.ticketId,
+    ),
+    epicIdForLedger: opts.ticketId,
   };
 }
 
+/**
+ * Dispatch the parameterized scope envelope
+ * (`{ scope, ticketId, baseRef, headRef, commentTargetId }`) to the
+ * matching pure resolver. `scope` defaults to `'epic'`.
+ */
+function resolveScopeEnvelope(opts, config) {
+  return opts.scope === 'story'
+    ? resolveStoryScope(opts, config)
+    : resolveEpicScope(opts, config);
+}
+
 /**
  * In-process wrapper that the `/epic-deliver` runner and the
  * `/single-story-deliver` close path consume.
@@ -407,26 +423,23 @@ function resolveScopeEnvelope(opts, config) {
  * `scope: 'epic'` because the `code-review.end` schema requires
  * `epicId` and the ledger only spans Epic lifecycles.
  *
- * Argument shapes:
- *   - Legacy (Epic):
- *       `{ epicId, provider, bus, [baseBranch] }`
- *   - Parameterized (Epic or Story):
- *       `{ scope, ticketId, baseRef, headRef, [commentTargetId],
- *          provider, bus }`
- *     For `scope === 'story'`, `commentTargetId` overrides the post
- *     target (e.g. PR number) while `ticketId` continues to label the
- *     rendered header ("Story #N").
+ * Argument shape (parameterized, Epic or Story):
+ *   `{ scope, ticketId, baseRef, headRef, [commentTargetId],
+ *      provider, bus }`
+ *   `scope` defaults to `'epic'`; `baseRef` defaults to the project base
+ *   branch and (Epic scope only) `headRef` defaults to `epic/<ticketId>`.
+ *   For `scope === 'story'`, `commentTargetId` overrides the post
+ *   target (e.g. PR number) while `ticketId` continues to label the
+ *   rendered header ("Story #N").
  *
  * @param {{
- *   epicId?: number,
  *   scope?: 'epic'|'story',
- *   ticketId?: number,
+ *   ticketId: number,
  *   baseRef?: string|null,
  *   headRef?: string|null,
  *   commentTargetId?: number|null,
  *   provider: object,
  *   logger?: { info?: Function, warn?: Function, error?: Function, fatal?: Function, createProgress?: Function },
- *   baseBranch?: string|null,
  *   planningRisk?: { overallLevel?: ('low'|'medium'|'high'), axes?: Array<{ axis?: string, level?: string }> }|null,
  *   changedFileCount?: number|null,
  *   storyId?: number|null,

package/.agents/scripts/lib/orchestration/dispatch-pipeline.js

@@ -7,11 +7,11 @@
  */
 
 import { PROJECT_ROOT, resolveConfig } from '../config-resolver.js';
-import { parseBlockedBy } from '../dependency-parser.js';
 import { getEpicBranch } from '../git-utils.js';
 import { Logger } from '../Logger.js';
 import { TYPE_LABELS } from '../label-constants.js';
 import { createProvider } from '../provider-factory.js';
+import { buildStoryAdjacency } from '../story-adjacency.js';
 import { WorktreeManager } from '../worktree-manager.js';
 import { computeStoryWaves } from './dependency-analyzer.js';
 import { reconcileHierarchy } from './reconciler.js';
@@ -161,17 +161,10 @@ export function buildStoryDispatchGraph(allTickets) {
   );
   const storyMap = new Map(stories.map((s) => [s.id, s]));
 
-  const explicitDeps = new Map();
-  for (const story of stories) {
-    const fromBody = parseBlockedBy(story.body ?? '');
-    const fromField = Array.isArray(story.dependencies)
-      ? story.dependencies.map(Number)
-      : [];
-    const merged = [...new Set([...fromBody, ...fromField])].filter(
-      (id) => Number.isInteger(id) && id !== story.id && storyMap.has(id),
-    );
-    if (merged.length > 0) explicitDeps.set(story.id, merged);
-  }
+  // Shared story-level adjacency builder (lib/story-adjacency.js) owns the
+  // dependency-source ordering contract: body `blocked by` references via
+  // `parseBlockedBy`, then explicit `dependencies[]`, foreign edges dropped.
+  const explicitDeps = buildStoryAdjacency(stories);
 
   // computeStoryWaves expects a Map<storyId, { tasks: [] }>; with no Tasks
   // present, only explicitDeps + focus-area rollup (no-op for empty

package/.agents/scripts/lib/orchestration/epic-deliver-lease-guard.js

@@ -29,7 +29,10 @@
  * `process.exit(1)` by the `runAsCli` boundary), never `Logger.fatal`.
  */
 
-import { acquireLease, normalizeOperatorHandle } from './ticket-lease.js';
+import {
+  acquireLeaseFailClosed,
+  resolveOperatorFromCandidates,
+} from './lease-guard-shared.js';
 
 /**
  * Resolve the acquiring operator's identity. Precedence (Tech Spec #3476):
@@ -37,8 +40,11 @@ import { acquireLease, normalizeOperatorHandle } from './ticket-lease.js';
  *   2. `github.operatorHandle` in `.agentrc.json`.
  *   3. The local `git config user.email`.
  *
- * The `@`-prefix some operators carry on `operatorHandle` is stripped so the
- * value matches the bare login written to a ticket's `assignees`.
+ * The `@`-prefix some operators carry on `operatorHandle` is stripped (via
+ * the shared lease-guard kernel) so the value matches the bare login written
+ * to a ticket's `assignees`. This surface's missing-handle policy is `'null'`
+ * — `runPrepareGuards` fails closed on a null operator with deliver-specific
+ * wording after the (cheap, local) checkout-safety guard has run.
  *
  * @param {object} args
  * @param {string} [args.asFlag]        Explicit `--as` value.
@@ -48,12 +54,9 @@ import { acquireLease, normalizeOperatorHandle } from './ticket-lease.js';
  *   be determined.
  */
 export function resolveOperator({ asFlag, config, gitUserEmail } = {}) {
-  const candidates = [asFlag, config?.github?.operatorHandle, gitUserEmail];
-  for (const raw of candidates) {
-    const normalized = normalizeOperatorHandle(raw);
-    if (normalized !== null) return normalized;
-  }
-  return null;
+  return resolveOperatorFromCandidates({
+    candidates: [asFlag, config?.github?.operatorHandle, gitUserEmail],
+  });
 }
 
 /**
@@ -208,7 +211,7 @@ export async function acquireEpicLease({
   config,
   now,
 }) {
-  const result = await acquireLease({
+  return acquireLeaseFailClosed({
     provider,
     ticketId: epicId,
     operator,
@@ -216,11 +219,8 @@ export async function acquireEpicLease({
     steal,
     config,
     now,
+    renderRefusal: renderLeaseRefusal,
   });
-  if (!result.acquired) {
-    throw new Error(renderLeaseRefusal(result, epicId));
-  }
-  return result;
 }
 
 /**

package/.agents/scripts/lib/orchestration/epic-plan-decompose/phases/planning-artifacts.js

@@ -11,7 +11,7 @@
  */
 
 import { resolveListValue } from '../../../config/shared.js';
-import { _internal as conflictInternal } from '../../ticket-validator-conflicts.js';
+import { DEFAULT_REGISTRY_PATTERNS } from '../../ticket-validator-conflicts.js';
 
 /**
  * Ensure the supplied Epic body carries a `## Planning Artifacts` section.
@@ -67,7 +67,7 @@ export function resolveConflictPolicy(cfg) {
   }
   if (planning?.crossCuttingRegistries !== undefined) {
     policy.registries = resolveListValue(
-      conflictInternal.DEFAULT_REGISTRY_PATTERNS,
+      DEFAULT_REGISTRY_PATTERNS,
       planning.crossCuttingRegistries,
     );
   }

package/.agents/scripts/lib/orchestration/epic-plan-lease-guard.js

@@ -8,19 +8,18 @@
  * silently duplicate the Feature/Story tree:
  *
  *   - `acquireEpicPlanLease`   — claim the Epic before Phase 7 (spec). Refuses
- *                                (throws, exit non-zero) when a foreign claim
- *                                already holds the Epic, naming the current
- *                                owner. **Fail-closed (audit #3513):**
- *                                `/epic-plan` emits no `story.heartbeat` during
- *                                its run (heartbeats are a delivery-time
- *                                signal), so there is no live-heartbeat source
- *                                to judge a concurrent plan's liveness from.
- *                                Defaulting liveness to "stale" made every
- *                                foreign claim look reclaimable, leaving the
- *                                guard inert. We therefore treat ANY foreign
- *                                assignee as a live claim and refuse the take
- *                                unless `--steal` forcibly transfers it. An
- *                                unassigned or self-held Epic still proceeds.
+ *                                (throws, exit non-zero) when a live foreign
+ *                                claim already holds the Epic, naming the
+ *                                current owner. **Claim-time liveness
+ *                                (Story #4019):** `/epic-plan` emits no
+ *                                `story.heartbeat`, so the lease records its
+ *                                own claim-time in a `plan-lease` structured
+ *                                comment on the Epic at acquire time. A
+ *                                foreign claim fresher than the lease TTL
+ *                                refuses (unless `--steal`); a stale or
+ *                                record-less claim is reclaimed
+ *                                automatically. An unassigned or self-held
+ *                                Epic still proceeds.
  *   - `releaseEpicPlanLease`   — release the claim after Phase 8 (decompose).
  *                                Best-effort and self-scoped: a no-op once the
  *                                Epic was reassigned elsewhere.
@@ -35,13 +34,15 @@
  */
 
 import { getGitHub } from '../config/github.js';
+import { resolveLeaseTtlMs } from '../config/limits.js';
 import { Logger } from '../Logger.js';
 import { TYPE_LABELS } from '../label-constants.js';
 import {
-  acquireLease,
-  normalizeOperatorHandle,
-  releaseLease,
-} from './ticket-lease.js';
+  acquireLeaseFailClosed,
+  resolveOperatorFromCandidates,
+} from './lease-guard-shared.js';
+import { currentOwner, releaseLease } from './ticket-lease.js';
+import { findStructuredComment, upsertStructuredComment } from './ticketing.js';
 
 /**
  * Resolve the operator handle that owns this `/epic-plan` run from
@@ -52,32 +53,115 @@ import {
  * (`acquireEpicPlanLease`) then fails closed by throwing rather than running an
  * ownerless, unguarded plan.
  *
- * The `@`-prefix some operators carry on `operatorHandle` is stripped so the
- * value matches the bare login GitHub writes to (and returns from) a ticket's
- * `assignees` — otherwise the assignee PATCH is rejected (HTTP 422, invalid
- * assignee) and the self-held-claim comparison (`owner === operator`) never
- * matches. This mirrors the sibling lease guards
- * (`single-story-lease-guard.js`, `epic-deliver-lease-guard.js`).
+ * The `@`-prefix some operators carry on `operatorHandle` is stripped (via
+ * the shared lease-guard kernel) so the value matches the bare login GitHub
+ * writes to (and returns from) a ticket's `assignees` — otherwise the
+ * assignee PATCH is rejected (HTTP 422, invalid assignee) and the
+ * self-held-claim comparison (`owner === operator`) never matches.
+ *
+ * The plan surface's missing-handle policy is `'null'` (intentional
+ * divergence from the standalone path's `'throw'`): `releaseEpicPlanLease`
+ * is best-effort and must degrade to a `no-operator` no-op rather than
+ * throw, so the throw-on-missing decision lives in `acquireEpicPlanLease`.
  *
  * @param {object} config Resolved config bag.
  * @returns {string|null}
  */
 export function resolveOperator(config) {
-  return normalizeOperatorHandle(getGitHub(config).operatorHandle);
+  return resolveOperatorFromCandidates({
+    candidates: [getGitHub(config).operatorHandle],
+  });
+}
+
+/**
+ * Structured-comment type carrying the plan-lease claim-time record.
+ * Registered in `ticketing/reads.js` `STRUCTURED_COMMENT_TYPES`.
+ */
+export const PLAN_LEASE_COMMENT_TYPE = 'plan-lease';
+
+/**
+ * Render the `plan-lease` structured-comment body: a one-line human
+ * summary plus the canonical fenced-JSON record `parsePlanLeaseClaim`
+ * reads back.
+ *
+ * @param {{ epicId: number, owner: string, claimedAt: string }} input
+ *   `claimedAt` is an ISO-8601 timestamp.
+ * @returns {string}
+ */
+export function buildPlanLeaseCommentBody({ epicId, owner, claimedAt }) {
+  const record = {
+    kind: PLAN_LEASE_COMMENT_TYPE,
+    epicId,
+    owner,
+    claimedAt,
+  };
+  return [
+    `### 🔒 Plan Lease — claimed by \`${owner}\``,
+    '',
+    `This Epic is being planned by \`${owner}\` (claimed ${claimedAt}). A`,
+    'concurrent `/epic-plan` run refuses while this claim is fresher than the',
+    'lease TTL, and reclaims automatically once it goes stale.',
+    '',
+    '```json',
+    JSON.stringify(record, null, 2),
+    '```',
+  ].join('\n');
+}
+
+/**
+ * Parse the claim record out of a `plan-lease` comment body. Returns
+ * `{ owner, claimedAtMs }` or `null` when the body carries no readable
+ * record — which callers treat as "no claim-time recorded" (stale,
+ * reclaimable).
+ *
+ * @param {string|undefined|null} body
+ * @returns {{ owner: string, claimedAtMs: number } | null}
+ */
+export function parsePlanLeaseClaim(body) {
+  if (typeof body !== 'string') return null;
+  const match = body.match(/```json\s*\n([\s\S]*?)\n\s*```/);
+  if (!match) return null;
+  let record;
+  try {
+    record = JSON.parse(match[1]);
+  } catch (_err) {
+    return null;
+  }
+  if (!record || record.kind !== PLAN_LEASE_COMMENT_TYPE) return null;
+  const owner =
+    typeof record.owner === 'string' && record.owner.length > 0
+      ? record.owner
+      : null;
+  const claimedAtMs = Date.parse(record.claimedAt ?? '');
+  if (owner === null || !Number.isFinite(claimedAtMs)) return null;
+  return { owner, claimedAtMs };
 }
 
 /**
  * Acquire the Epic-lease before Phase 7.
  *
- * **Fail-closed (audit #3513).** `/epic-plan` emits no `story.heartbeat`
- * during its run, so there is no live-heartbeat source to judge a concurrent
- * plan's liveness from. Rather than default liveness to "stale" (which made
- * every foreign claim look reclaimable and left this guard inert), we anchor
- * `heartbeatAt` to the same `now` the lease primitive evaluates against. That
- * makes `isClaimLive` return true for ANY foreign owner, so `acquireLease`
- * refuses a foreign assignee unless `steal` is set — naming the current owner.
- * An unassigned Epic (`unclaimed`) or a self-held claim (`already-held`) still
- * proceeds without a write. This mirrors `single-story-lease-guard.js`.
+ * **Claim-time liveness (Story #4019, superseding the audit-#3513
+ * fail-closed anchor).** `/epic-plan` emits no `story.heartbeat`, so the
+ * old guard treated EVERY foreign assignee as live — which made the
+ * documented "`--steal` once you have confirmed the other run is dead"
+ * contract undecidable (there was no in-band liveness signal to confirm
+ * against). The lease now records its own claim-time: on every successful
+ * acquire the guard upserts a `plan-lease` structured comment on the Epic
+ * carrying `{ owner, claimedAt }`. A subsequent run judges a foreign
+ * claim's liveness from that claim-time against the lease TTL
+ * (`resolveLeaseTtlMs`):
+ *
+ *   - **Fresh foreign claim** (claim-time within TTL) → refuse, naming the
+ *     owner and the claim age; `--steal` force-transfers.
+ *   - **Stale foreign claim** (claim-time older than TTL) → reclaim
+ *     automatically.
+ *   - **No claim-time record** (foreign assignee but no readable
+ *     `plan-lease` comment, or the comment names a different owner) →
+ *     treated as stale and reclaimed — the assignee predates this
+ *     mechanism or was set out-of-band, so there is nothing to wait on.
+ *
+ * An unassigned Epic (`unclaimed`) or a self-held claim (`already-held`)
+ * proceeds; both refresh the claim-time record.
  *
  * A refused claim throws (caught at the CLI boundary → exit non-zero).
  *
@@ -85,7 +169,7 @@ export function resolveOperator(config) {
  * @param {import('../ITicketingProvider.js').ITicketingProvider} args.provider
  * @param {number} args.epicId
  * @param {object} [args.config]
- * @param {boolean} [args.steal=false]   Force-transfer a foreign claim.
+ * @param {boolean} [args.steal=false]   Force-transfer a live foreign claim.
  * @param {number} [args.now]            Injectable clock (epoch ms; tests).
  * @returns {Promise<{ acquired: boolean, owner: string|null, previousOwner: string|null, reason: string }>}
  */
@@ -108,31 +192,82 @@ export async function acquireEpicPlanLease({
     );
   }
 
-  // Fail closed: with no live-heartbeat source on the plan path, treat any
-  // foreign assignee as a live claim by anchoring `heartbeatAt` to the same
-  // `now` the primitive evaluates against (`isClaimLive` → true for any owner).
-  // `acquireLease` then refuses a foreign claim unless `steal` is set; an
-  // unassigned or self-held Epic proceeds without a write.
   const resolvedNow =
     typeof now === 'number' && Number.isFinite(now) ? now : Date.now();
-  const result = await acquireLease({
+  const ttlMs = resolveLeaseTtlMs(config);
+
+  // Resolve the current assignee and the recorded claim-time. The
+  // claim-time only counts when the `plan-lease` record names the same
+  // owner as the assignee — a mismatched or missing record means the claim
+  // has no liveness signal and is treated as stale (reclaimable).
+  const ticket = await provider.getTicket(epicId);
+  const owner = currentOwner(ticket?.assignees);
+  let heartbeatAt = null;
+  if (owner !== null && owner !== operator) {
+    let claim = null;
+    try {
+      const comment = await findStructuredComment(
+        provider,
+        epicId,
+        PLAN_LEASE_COMMENT_TYPE,
+      );
+      claim = comment ? parsePlanLeaseClaim(comment.body) : null;
+    } catch (err) {
+      Logger.warn(
+        `[epic-plan] Could not read plan-lease claim record on #${epicId} ` +
+          `(treating foreign claim as stale): ${err.message}`,
+      );
+    }
+    if (claim && claim.owner === owner) {
+      heartbeatAt = claim.claimedAtMs;
+    }
+  }
+
+  const result = await acquireLeaseFailClosed({
     provider,
     ticketId: epicId,
     operator,
-    heartbeatAt: resolvedNow,
+    heartbeatAt,
     steal,
     config,
     now: resolvedNow,
+    renderRefusal: (refused) => {
+      const ageMinutes =
+        heartbeatAt !== null
+          ? Math.round((resolvedNow - heartbeatAt) / 60000)
+          : null;
+      const ageNote =
+        ageMinutes !== null
+          ? `Its plan-lease claim is ~${ageMinutes} minute(s) old (TTL ${Math.round(ttlMs / 60000)} minute(s)), so the run is presumed live. `
+          : '';
+      return (
+        `[epic-plan] Epic #${epicId} is currently claimed by '${refused.owner}'. ` +
+        `Refusing to plan concurrently — another /epic-plan run owns this Epic. ` +
+        `${ageNote}Wait for that run to finish (the claim auto-expires at the ` +
+        `lease TTL), or re-run with --steal to forcibly transfer the claim.`
+      );
+    },
   });
 
-  if (!result.acquired) {
-    throw new Error(
-      `[epic-plan] Epic #${epicId} is currently claimed by '${result.owner}'. ` +
-        `Refusing to plan concurrently — another /epic-plan run owns this Epic ` +
-        `(the plan path has no heartbeat ledger, so a foreign assignee always ` +
-        `blocks unless stolen). Wait for that run to finish, or re-run with ` +
-        `--steal to forcibly transfer the claim once you have confirmed the ` +
-        `other run is dead.`,
+  // Record (or refresh) the claim-time so the next run can judge this
+  // claim's liveness. Best-effort: a comment failure degrades to a
+  // record-less claim (which a later run treats as stale) — it never
+  // fails the plan.
+  try {
+    await upsertStructuredComment(
+      provider,
+      epicId,
+      PLAN_LEASE_COMMENT_TYPE,
+      buildPlanLeaseCommentBody({
+        epicId,
+        owner: operator,
+        claimedAt: new Date(resolvedNow).toISOString(),
+      }),
+    );
+  } catch (err) {
+    Logger.warn(
+      `[epic-plan] Failed to record plan-lease claim-time on #${epicId} ` +
+        `(non-fatal; a later run will treat this claim as stale): ${err.message}`,
     );
   }
 

package/.agents/scripts/lib/orchestration/epic-plan-spec/phases/drain.js

@@ -8,8 +8,8 @@
  */
 
 import path from 'node:path';
-import { PROJECT_ROOT } from '../../../config-resolver.js';
 import * as gitUtils from '../../../git-utils.js';
+import { PROJECT_ROOT } from '../../../project-root.js';
 import { forceDrainPendingCleanup } from '../../../worktree/lifecycle/force-drain.js';
 import { readManifest } from '../../../worktree/lifecycle/pending-cleanup.js';
 import { sweepStaleStoryWorktrees } from '../../plan-runner/worktree-sweep.js';