mandrel 2.31.0 → 2.32.0

package/.agents/scripts/lib/orchestration/single-story-close/phases/worktree-reap.js

@@ -16,13 +16,9 @@
  * actually reaped and every close said it did. Best-effort means the close
  * still succeeds on refusal; it does not mean the close may claim an
  * outcome it never checked.
- *
- * Also clears the trace-hook env vars so subsequent tooling falls back to
- * the no-op branch instead of pointing at a (now-reaped) worktree.
  */
 
 import { Logger } from '../../../Logger.js';
-import { clearActiveStoryEnv } from '../../../observability/active-story-env.js';
 import { WorktreeManager as DefaultWorktreeManager } from '../../../worktree-manager.js';
 
 /**
@@ -92,15 +88,5 @@ export async function reapWorktreePhase({
     }
   }
 
-  // Clear the trace-hook env vars so subsequent tooling falls back to the
-  // no-op branch instead of pointing at a (now-reaped) worktree.
-  try {
-    clearActiveStoryEnv({
-      logger: { warn: (m) => progress('ENV', `⚠️ ${m}`) },
-    });
-  } catch {
-    // Non-fatal.
-  }
-
   return worktreeReaped;
 }

package/.agents/scripts/lib/orchestration/single-story-close/runner.js

@@ -29,6 +29,7 @@ import { parseCloseOptions, resolveWaitForMerge } from './phases/options.js';
 import { ensurePullRequestWith } from './phases/pull-request.js';
 import { pushStoryBranch } from './phases/push.js';
 import { handleCriticalReviewBlock } from './phases/review-block.js';
+import { handleOverriddenReviewBlock } from './phases/review-override.js';
 import { reapWorktreePhase } from './phases/worktree-reap.js';
 import { runWrongTreeGuardPhase } from './phases/wrong-tree-guard.js';
 
@@ -207,6 +208,8 @@ async function openAndReviewPr({
   storyBranch,
   baseBranch,
   provider,
+  config,
+  overrideReviewBlock,
   injectedGh,
   injectedRunCodeReview,
   setPhase = () => {},
@@ -222,6 +225,8 @@ async function openAndReviewPr({
     cwd,
     storyId,
     storyTitle: story.title,
+    // Scanned for a declared `BREAKING CHANGE:` footer — see pull-request.js.
+    storyBody: story.body,
     storyBranch,
     baseBranch,
     gh: injectedGh,
@@ -249,6 +254,27 @@ async function openAndReviewPr({
   });
   if (reviewOutcome.halted) {
     const criticalCount = reviewOutcome.severity?.critical ?? 0;
+    // The sanctioned override. Checked BEFORE the blocked
+    // transition so an overridden run never touches `agent::blocked`: the
+    // Story is proceeding, and parking it would make the label lie for the
+    // rest of the close.
+    if (overrideReviewBlock) {
+      const override = await handleOverriddenReviewBlock({
+        provider,
+        storyId,
+        prUrl,
+        prNumber,
+        criticalCount,
+        reason: overrideReviewBlock,
+        config,
+      });
+      return {
+        prUrl,
+        prNumber,
+        alreadyMerged: false,
+        reviewOverride: override,
+      };
+    }
     await handleCriticalReviewBlock({
       provider,
       storyId,
@@ -257,10 +283,12 @@ async function openAndReviewPr({
     });
     throw new Error(
       `[single-story-close] Story-scope review reported ${criticalCount} critical blocker(s) on PR ${prUrl}. ` +
-        'Auto-merge was not enabled. Remediate the findings posted to the PR and re-run `/deliver`.',
+        'Auto-merge was not enabled. Remediate the findings posted to the PR and re-run `/deliver`. ' +
+        'If you have reviewed a finding and judged it wrong, re-run with ' +
+        '`--override-review-block "<reason>"` rather than merging by hand.',
     );
   }
-  return { prUrl, prNumber, alreadyMerged: false };
+  return { prUrl, prNumber, alreadyMerged: false, reviewOverride: null };
 }
 
 async function releaseLease({
@@ -296,11 +324,9 @@ async function releaseLease({
  * `runBaseSyncPhase`, and a critical-blocker review halt in
  * `openAndReviewPr`) throw before the clean-close lease release at the
  * tail of `runSingleStoryClose`, stranding the operator's lease
- * indefinitely. The standalone lease does **not** expire by TTL: it is
- * fail-closed by design (`lease-guard-shared.js` anchors `heartbeatAt` to
- * now, so `isClaimLive` is true for any foreign assignee regardless of the
- * configured TTL), so a stranded claim is cleared only by `--steal` or
- * de-assignment. That fail-closed-refuses a different operator who picks up
+ * indefinitely. The standalone lease has **no** TTL to expire by (Story
+ * #5006 deleted it): `acquireLease` refuses any foreign assignee outright,
+ * so a stranded claim is cleared only by `--steal` or de-assignment. That fail-closed-refuses a different operator who picks up
  * the blocked Story — exactly the hand-off case. Releasing here closes
  * that gap.
  *
@@ -383,6 +409,7 @@ export async function runSingleStoryClose({
   noWaitForMerge: noWaitForMergeParam,
   maxWaitSeconds: maxWaitSecondsParam,
   mergeWatchMode: mergeWatchModeParam,
+  overrideReviewBlock: overrideReviewBlockParam,
   injectedProvider,
   injectedConfig,
   injectedNotify,
@@ -402,10 +429,11 @@ export async function runSingleStoryClose({
     noWaitForMergeParam,
     maxWaitSecondsParam,
     mergeWatchModeParam,
+    overrideReviewBlockParam,
   });
   if (!options.storyId) {
     throw new Error(
-      'Usage: node single-story-close.js --story <STORY_ID> [--cwd <main-repo>] [--skip-validation] [--skip-sync] [--no-auto-merge] [--wait-merge|--no-wait-merge] [--max-wait-seconds <n>] [--merge-watch-mode <sync|async>]',
+      'Usage: node single-story-close.js --story <STORY_ID> [--cwd <main-repo>] [--skip-validation] [--skip-sync] [--no-auto-merge] [--wait-merge|--no-wait-merge] [--max-wait-seconds <n>] [--merge-watch-mode <sync|async>] [--override-review-block <reason>]',
     );
   }
 
@@ -730,22 +758,25 @@ async function runClosePipeline({
     leaseArgs,
   );
 
-  const { prUrl, prNumber, alreadyMerged } = await releaseLeaseOnBlock(
-    () =>
-      openAndReviewPr({
-        cwd: options.cwd,
-        worktreePath,
-        story,
-        storyId: options.storyId,
-        storyBranch,
-        baseBranch,
-        provider,
-        injectedGh,
-        injectedRunCodeReview,
-        setPhase,
-      }),
-    leaseArgs,
-  );
+  const { prUrl, prNumber, alreadyMerged, reviewOverride } =
+    await releaseLeaseOnBlock(
+      () =>
+        openAndReviewPr({
+          cwd: options.cwd,
+          worktreePath,
+          story,
+          storyId: options.storyId,
+          storyBranch,
+          baseBranch,
+          provider,
+          config,
+          overrideReviewBlock: options.overrideReviewBlock,
+          injectedGh,
+          injectedRunCodeReview,
+          setPhase,
+        }),
+      leaseArgs,
+    );
   // Reap the per-Story worktree BEFORE the arm (Story #4681). Arming runs
   // `gh pr merge --auto --squash --delete-branch`, which — against an
   // already-mergeable PR — merges immediately and then shells out to local
@@ -843,7 +874,10 @@ async function runClosePipeline({
     gates: {
       validation: options.skipValidation ? 'skipped' : 'passed',
       baseSync: options.skipSync ? 'skipped' : 'passed',
-      codeReview: 'passed',
+      // An overridden blocker reports `overridden`, never
+      // `passed`. The review DID fail; a human authorized shipping anyway, and
+      // the envelope is the machine-readable trail that says so.
+      codeReview: reviewOverride ? 'overridden' : 'passed',
     },
   };
 

package/.agents/scripts/lib/orchestration/single-story-lease-guard.js

@@ -24,18 +24,17 @@
  * operator handle from config and delegates assignee mutation to the pure
  * `ticket-lease.js` primitive.
  *
- * **Fail-closed liveness (audit #3513).** The standalone path has no
- * Epic-scoped lifecycle ledger to read a per-owner `story.heartbeat` from, so
- * there is no live-heartbeat source to feed the lease primitive's liveness
- * check. Defaulting `heartbeatAt` to `null` made *every* foreign claim look
- * stale (`isClaimLive(null) === false`), so the guard silently reclaimed any
- * foreign assignee — leaving it inert as a concurrency guard. We therefore
- * **fail closed**: a foreign assignee is treated as a *live* claim by default
- * and refuses the take (naming the current owner), unless the operator passes
- * `--steal` to forcibly transfer it. This is the safer choice for a guard
- * whose whole job is to stop two operators clobbering the same Story; a
- * genuinely abandoned claim is cleared by hand (or `--steal`) rather than
- * raced into automatically. Unclaimed and self-held tickets still proceed.
+ * **Fail-closed (audit #3513, hard-wired by Story #5006).** The lease
+ * primitive used to reclaim a foreign claim whose heartbeat was older than a
+ * TTL — and with no heartbeat source, *every* foreign claim looked stale, so
+ * the guard silently reclaimed any foreign assignee and was inert as a
+ * concurrency guard. The guard worked around that by anchoring the heartbeat
+ * to `now`; Story #5006 deleted the TTL outright, so the fail-closed
+ * behaviour is now the primitive's own: a foreign assignee refuses the take
+ * (naming the current owner) unless the operator passes `--steal` to forcibly
+ * transfer it. A genuinely abandoned claim is cleared by hand (or `--steal`)
+ * rather than raced into automatically. Unclaimed and self-held tickets still
+ * proceed.
  */
 
 import {
@@ -75,21 +74,19 @@ export function resolveOperator(config) {
 }
 
 /**
- * Acquire (or re-affirm / reclaim) the Story lease for the standalone path.
+ * Acquire (or re-affirm) the Story lease for the standalone path.
  *
- * **Fail-closed:** because the standalone path has no Epic ledger to source a
- * live heartbeat from, a foreign assignee is treated as a live claim and
- * refuses the take by default — the guard throws naming the current owner so
- * the operator can coordinate. Pass `steal: true` (`--steal`) to forcibly
- * transfer it. Unclaimed and self-held tickets proceed without a write.
+ * **Fail-closed:** a foreign assignee refuses the take — the guard throws
+ * naming the current owner so the operator can coordinate. Pass
+ * `steal: true` (`--steal`) to forcibly transfer it. Unclaimed and self-held
+ * tickets proceed without a write.
  *
  * @param {object} opts
  * @param {object} opts.provider           Ticketing provider (getTicket/updateTicket).
  * @param {number} opts.storyId            Story ticket to claim.
- * @param {object} opts.config             Resolved config (operator handle + TTL default).
+ * @param {object} opts.config             Resolved config (operator handle).
  * @param {string} [opts.operator]         Override the resolved operator (tests).
  * @param {boolean} [opts.steal=false]     Forcibly transfer a foreign claim.
- * @param {number} [opts.now]              Injectable clock (epoch ms) for tests.
  * @returns {Promise<{ acquired: boolean, owner: string, previousOwner: string|null, reason: string }>}
  * @throws {Error} When a foreign claim refuses the acquire (no `steal`).
  */
@@ -99,27 +96,19 @@ export async function acquireStoryLease({
   config,
   operator,
   steal = false,
-  now,
 }) {
   const owner = operator ?? resolveOperator(config);
-  // Fail closed: with no live-heartbeat source on the standalone path, the
-  // shared kernel anchors `heartbeatAt` to the same `now` the primitive
-  // evaluates against, so `isClaimLive` returns true for any foreign owner
-  // and `acquireLease` refuses unless `steal` is set.
   return acquireLeaseFailClosed({
     provider,
     ticketId: storyId,
     operator: owner,
     steal,
-    config,
-    now,
-    anchorHeartbeatToNow: true,
     renderRefusal: (result) =>
       `single-story lease: Story #${storyId} is currently held by @${result.owner}. ` +
       'Another /deliver run owns this Story. Coordinate with that ' +
       'operator, or re-run with --steal to forcibly transfer the claim once you ' +
-      'have confirmed the other run is dead. (The standalone path has no Epic ' +
-      'heartbeat ledger, so a foreign assignee always blocks unless stolen.)',
+      'have confirmed the other run is dead. (A foreign assignee always ' +
+      'blocks unless stolen.)',
   });
 }
 
@@ -142,5 +131,5 @@ export async function releaseStoryLease({
   operator,
 }) {
   const owner = operator ?? resolveOperator(config);
-  return releaseLease({ provider, ticketId: storyId, operator: owner, config });
+  return releaseLease({ provider, ticketId: storyId, operator: owner });
 }

package/.agents/scripts/lib/orchestration/spec-spill.js

@@ -6,13 +6,27 @@
  * Spec is treated as a sizing smell (the Story should be split or the Spec
  * tightened), not as a reason to write temporary product docs.
  *
- * The budget reuses the §2 FinOps estimator ({@link estimateTokens}, ~4
- * chars/token) so the threshold speaks the same units as hydration budgets.
+ * This module also **owns** the §2 FinOps token estimator
+ * ({@link estimateTokens}, ~4 chars/token) — the one shared approximation every
+ * fixed framework ceiling speaks in (the Spec budget below, the plan-time
+ * sizing ceilings in `ticket-validator-sizing.js`, and the audit checklist
+ * threading budget). It used to live in a `context-envelope.js` SDK whose
+ * remaining surface had no live caller; the estimator is all that survived.
  *
  * @module lib/orchestration/spec-spill
  */
 
-import { estimateTokens } from './context-envelope.js';
+/**
+ * Rough token estimate: ~4 characters per token. Deliberately cheap and
+ * deterministic — every ceiling that quotes "tokens" is quoting this number,
+ * so the approximation matters far less than every caller sharing one.
+ *
+ * @param {string} text
+ * @returns {number}
+ */
+export function estimateTokens(text) {
+  return Math.ceil(String(text ?? '').length / 4);
+}
 
 /**
  * Soft budget (estimated tokens) for an inline `## Spec`. ~1500 tokens ≈ 6KB —

package/.agents/scripts/lib/orchestration/story-close/phases/review-core.js

@@ -1,12 +1,13 @@
 /**
  * phases/review-core.js — the shared Story-scope review spine.
  *
- * Extracted from `phases/code-review.js` (Story #4603). `runStoryReviewCore` is
- * the one implementation both close paths call `runCodeReview` through — the
- * epic-attached phase (`code-review.js#runStoryCodeReview`) and the standalone
- * v2 path (`single-story-close/phases/code-review.js#runStoryScopeReview`) —
- * so it belongs to neither and lives here rather than inside one path's phase
- * file (Story #3653 established the shared-spine contract).
+ * Extracted from the Epic-era `phases/code-review.js` (Story #4603) so the
+ * spine belonged to neither close path. `runStoryReviewCore` is the one
+ * implementation `runCodeReview` is called through; since Story #5006 retired
+ * the Epic-attached phase, its sole caller is the v2 standalone path
+ * (`single-story-close/phases/code-review.js#runStoryScopeReview`). It stays
+ * here — the shared-spine contract (Story #3653) is what keeps the maker-blind
+ * review invocation out of a phase file.
  */
 
 import { countChangedLines } from '../../../audit-suite/index.js';

package/.agents/scripts/lib/orchestration/story-deliver-terminal.js

@@ -425,7 +425,8 @@ export function persistTerminalEnvelope(
  * machine-readable contract — every invocation emits exactly ONE, and a
  * headless caller parses it out of stdout to decide what happened.
  * `Logger.info` is level-gated, so under the documented
- * `AGENT_LOG_LEVEL=silent` (§ 1.H) the envelope silently vanished and the
+ * `AGENT_LOG_LEVEL=silent` (execution-reference § Log-level control) the
+ * envelope silently vanished and the
  * caller got a bare exit code: precisely the "no envelope at all" outcome
  * Story #4543 exists to remove. A contract payload must not be suppressible
  * by a verbosity knob.

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

@@ -45,7 +45,10 @@
  * `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
  * literal `manual:<reason>` escape hatch when the Story is genuinely
- * unverifiable in isolation.
+ * unverifiable in isolation. `verify-tier-repair.js#normalizeVerifyTiers` runs
+ * first on the persist path (Story #5005) and **repairs** the entries whose
+ * tier `suggestVerifyFix` can infer, so the hard error below is reserved for
+ * the entries only the author can resolve.
  *
  * The errors are batched and surfaced as a single thrown Error so the
  * planner can see every offending slug in one pass instead of fixing one

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

@@ -1,57 +1,38 @@
 /**
  * ticket-lease.js — assignee-as-lease primitive (Story #3480, Epic #3457).
  *
- * The workflow-guards Feature (#3478) needs a way for one operator to take
- * 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 last-heartbeat epoch-ms
- * compared against a configured TTL.
+ * The workflow-guards Feature (#3478) needs a way for one operator to take an
+ * exclusive 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.
  *
- * **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.
+ * **A foreign claim is a refusal, full stop (Story #5006).** The lease shipped
+ * with a TTL: a claim whose owner's last heartbeat was older than
+ * `delivery.lease.ttlMs` counted as stale and was silently reclaimed. The
+ * `story.heartbeat` emitter that would have fed it was structurally inert (it
+ * demanded an `epicId >= 1` that v2, which has no Epics, never supplies) and
+ * was deleted, after which every guard pinned `heartbeatAt` to `now` so the
+ * liveness test always answered "live" — the TTL, the heartbeat parameter and
+ * the reclaim branch were an elaborate way of writing `true`. They are gone.
+ * A stranded claim is cleared with `--steal`, which is now the only way past
+ * a foreign owner.
  *
- * The three exported operations are deliberately thin and provider-agnostic:
+ * The two exported operations are deliberately thin and provider-agnostic:
  *
  *   - `acquireLease`  — claim an unassigned ticket, re-affirm a self-held
- *                       claim, reclaim a ticket whose foreign claim has gone
- *                       stale (heartbeat older than TTL), or — with
- *                       `steal: true` — forcibly transfer a *live* foreign
- *                       claim.
+ *                       claim, or — with `steal: true` — forcibly transfer a
+ *                       foreign claim.
  *   - `releaseLease`  — clear the assignment, but only when the operator
  *                       still holds it (a no-op once the ticket was
  *                       reassigned elsewhere, so a late release never steals
  *                       a claim back from whoever took over).
- *   - `describeLease` — a read-only snapshot of the current claim and its
- *                       liveness, used by callers (and tests) to reason about
- *                       a ticket without mutating it.
  *
  * Provider contract (a subset of `ITicketingProvider`):
  *   - `getTicket(id)`            → `{ assignees: string[], ... }`
  *   - `updateTicket(id, { assignees })` writes the assignee list.
- *
- * 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 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 { resolveLeaseTtlMs } from '../config/limits.js';
-
 /**
  * The shipped, non-personal operator-identity placeholder (and its bare,
  * post-normalise form). The committed `.agentrc.json` and the distributed
@@ -94,35 +75,6 @@ export function normalizeOperatorHandle(raw) {
   return trimmed;
 }
 
-/**
- * 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.
- * @param {number} args.now                          Current time (epoch ms).
- * @returns {boolean}
- */
-export function isClaimLive({ heartbeatAt, ttlMs, now }) {
-  if (typeof heartbeatAt !== 'number' || !Number.isFinite(heartbeatAt)) {
-    return false;
-  }
-  return now - heartbeatAt <= ttlMs;
-}
-
 /**
  * Normalise the assignee list into a single current owner. The lease model is
  * single-holder: the first assignee is authoritative. Returns `null` for an
@@ -141,10 +93,10 @@ export function currentOwner(assignees) {
  *
  * @param {string} op
  * @param {object} opts
- * @returns {{ provider: object, ticketId: number, operator: string, ttlMs: number, now: number }}
+ * @returns {{ provider: object, ticketId: number, operator: string }}
  */
 function normaliseOpts(op, opts) {
-  const { provider, ticketId, operator, config, now } = opts ?? {};
+  const { provider, ticketId, operator } = opts ?? {};
 
   if (!provider || typeof provider.getTicket !== 'function') {
     throw new Error(`${op}: provider with getTicket/updateTicket is required`);
@@ -156,45 +108,7 @@ function normaliseOpts(op, opts) {
     throw new Error(`${op}: operator must be a non-empty string`);
   }
 
-  const ttlMs = resolveLeaseTtlMs(config, opts.ttlMs);
-  const resolvedNow =
-    typeof now === 'number' && Number.isFinite(now) ? now : Date.now();
-
-  return { provider, ticketId, operator, ttlMs, now: resolvedNow };
-}
-
-/**
- * Read-only snapshot of the current lease on a ticket. Never mutates.
- *
- * @param {object} opts
- * @param {object} opts.provider              Ticketing provider (getTicket).
- * @param {number} opts.ticketId              Ticket to inspect.
- * @param {string} opts.operator              The operator asking.
- * @param {number|null} [opts.heartbeatAt]    Owner's last heartbeat (epoch ms).
- * @param {object} [opts.config]              Resolved config (for TTL default).
- * @param {number} [opts.ttlMs]               Explicit TTL override (epoch ms).
- * @param {number} [opts.now]                 Injectable clock (epoch ms).
- * @returns {Promise<{
- *   ticketId: number,
- *   owner: string|null,
- *   heldByOperator: boolean,
- *   live: boolean,
- *   ttlMs: number,
- * }>}
- */
-export async function describeLease(opts) {
-  const { provider, ticketId, operator, ttlMs, now } = normaliseOpts(
-    'describeLease',
-    opts,
-  );
-  const ticket = await provider.getTicket(ticketId);
-  const owner = currentOwner(ticket?.assignees);
-  const heldByOperator = owner === operator;
-  const live =
-    owner === null
-      ? false
-      : isClaimLive({ heartbeatAt: opts.heartbeatAt, ttlMs, now });
-  return { ticketId, owner, heldByOperator, live, ttlMs };
+  return { provider, ticketId, operator };
 }
 
 /**
@@ -205,10 +119,8 @@ export async function describeLease(opts) {
  *                                     `reason: 'unclaimed'`.
  *   - Operator already holds it    → no write, `acquired: true`,
  *                                     `reason: 'already-held'`.
- *   - Live foreign claim, no steal → no write, `acquired: false`,
+ *   - Foreign claim, no steal      → no write, `acquired: false`,
  *                                     `owner: <foreign>`, `reason: 'held'`.
- *   - Stale foreign claim          → reassign operator, `acquired: true`,
- *                                     `reason: 'reclaimed'`.
  *   - Foreign claim + `steal:true` → reassign operator, `acquired: true`,
  *                                     `reason: 'stolen'`.
  *   - Lost a write race            → a foreign login co-assigned between our
@@ -226,23 +138,16 @@ export async function describeLease(opts) {
  * @param {object} opts.provider              Ticketing provider.
  * @param {number} opts.ticketId              Ticket to claim.
  * @param {string} opts.operator              Operator acquiring the lease.
- * @param {number|null} [opts.heartbeatAt]    Current owner's last heartbeat (epoch ms).
- * @param {boolean} [opts.steal=false]        Transfer a live foreign claim.
- * @param {object} [opts.config]              Resolved config (TTL default).
- * @param {number} [opts.ttlMs]               Explicit TTL override.
- * @param {number} [opts.now]                 Injectable clock.
+ * @param {boolean} [opts.steal=false]        Transfer a foreign claim.
  * @returns {Promise<{
  *   acquired: boolean,
  *   owner: string,
  *   previousOwner: string|null,
- *   reason: 'unclaimed'|'already-held'|'reclaimed'|'stolen'|'held'|'lost-race',
+ *   reason: 'unclaimed'|'already-held'|'stolen'|'held'|'lost-race',
  * }>}
  */
 export async function acquireLease(opts) {
-  const { provider, ticketId, operator, ttlMs, now } = normaliseOpts(
-    'acquireLease',
-    opts,
-  );
+  const { provider, ticketId, operator } = normaliseOpts('acquireLease', opts);
   const steal = opts.steal === true;
 
   const ticket = await provider.getTicket(ticketId);
@@ -269,9 +174,8 @@ export async function acquireLease(opts) {
     };
   }
 
-  // Foreign claim — decide on liveness / steal.
-  const live = isClaimLive({ heartbeatAt: opts.heartbeatAt, ttlMs, now });
-  if (live && !steal) {
+  // Foreign claim — refuse unless the operator explicitly steals it.
+  if (!steal) {
     return {
       acquired: false,
       owner,
@@ -285,7 +189,7 @@ export async function acquireLease(opts) {
     ticketId,
     operator,
     previousOwner: owner,
-    reason: steal && live ? 'stolen' : 'reclaimed',
+    reason: 'stolen',
   });
 }
 
@@ -359,9 +263,6 @@ async function claimAndVerify({
  * @param {object} opts.provider   Ticketing provider.
  * @param {number} opts.ticketId   Ticket to release.
  * @param {string} opts.operator   Operator releasing the lease.
- * @param {object} [opts.config]   Resolved config (TTL default).
- * @param {number} [opts.ttlMs]    Explicit TTL override.
- * @param {number} [opts.now]      Injectable clock.
  * @returns {Promise<{
  *   released: boolean,
  *   owner: string|null,

package/.agents/scripts/lib/orchestration/ticket-validator-sizing.js

@@ -29,7 +29,7 @@
  */
 
 import { parse as parseStoryBody } from '../story-body/story-body.js';
-import { estimateTokens } from './context-envelope.js';
+import { estimateTokens } from './spec-spill.js';
 
 /**
  * Normalize a Story's `body` to the structured object the sizing layers

package/.agents/scripts/lib/orchestration/ticketing/reads.js

@@ -146,14 +146,14 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // `--steal`, not by TTL expiry. One entry per ticket; re-acquires upsert
   // in place.
   'plan-lease',
-  // Story #4415 (Epic #4406) — the feedback-loop graduators
-  // (`audit-results-graduator.js` / `retro-proposals-graduator.js`) upsert a
-  // `cross-repo-deferred` comment on the Epic listing findings that route
+  // Story #4415 (Epic #4406) — the feedback-loop graduator
+  // (`retro-proposals-graduator.js`) upserts a
+  // `cross-repo-deferred` comment listing findings that route
   // to a different repository and were therefore not filed here. Replaces
   // the prior log-line-only trace so the deferral survives the finalize
   // run as a durable, operator-visible record. Discriminated by a
-  // `graduator="audit-results|code-review"` attr so the two graduators
-  // upsert independent comments; re-runs upsert in place.
+  // `graduator="<name>"` attr so independent graduators do not clobber each
+  // other's comment; re-runs upsert in place.
   'cross-repo-deferred',
   // Epic #4474 (PR3) / v2 Stage 3 — `plan-persist.js` upserts a single
   // `plan-summary` comment on the primary Story at terminal persist