mandrel 1.58.0 → 1.60.0

package/.agents/scripts/lib/orchestration/epic-runner/story-run-progress-writer.js

@@ -12,8 +12,8 @@
  * removed.
  *
  * The renderer survives because its `{ body, payload }` output still feeds
- * two non-comment contracts: the `renderedBody` markdown the `/story-deliver`
- * and `single-story-deliver` CLIs (`story-phase.js`, `story-deliver-prepare.js`)
+ * two non-comment contracts: the `renderedBody` markdown the `/deliver`
+ * and `single-story-deliver` CLIs (`story-phase.js`, the inline `story-init.js` prepare step)
  * relay to chat so the operator sees the phase table inline, and the snapshot
  * payload returned in those CLIs' JSON envelopes. `upsertStoryRunProgress`
  * therefore renders-only: it computes the body/payload and (optionally) mirrors
@@ -71,10 +71,10 @@ const PHASE_EMOJI = {
 };
 
 /**
- * Canonical 3-tier Story-phase order. The Story-phase snapshot replaces the
+ * Canonical 2-tier Story-phase order. The Story-phase snapshot replaces the
  * 4-tier per-Task list when the Story carries inline acceptance (no child
  * Tasks). Each entry tracks `status` + `startedAt` / `endedAt` so the parent
- * `/epic-deliver` aggregator can render a coarse progress bar without
+ * `/deliver` aggregator can render a coarse progress bar without
  * walking Task tickets.
  */
 export const STORY_PHASE_ORDER = ['init', 'implement', 'validate', 'close'];
@@ -89,8 +89,8 @@ const STORY_PHASE_STATUS_EMOJI = {
 
 /**
  * Build the canonical default `phases[]` array for a freshly-initialized
- * 3-tier Story snapshot. All entries are `pending`; timestamps are null.
- * Exported so call sites (story-deliver-prepare, story-phase) and
+ * 2-tier Story snapshot. All entries are `pending`; timestamps are null.
+ * Exported so call sites (the story-init prepare step, story-phase) and
  * tests can build the same shape without re-implementing it.
  *
  * @returns {Array<{ name: string, status: 'pending', startedAt: null, endedAt: null }>}
@@ -175,7 +175,7 @@ function normalizeTask(task) {
  * Exported so tests can pin the rendered shape without going through the
  * upsert path.
  *
- * Two shapes are supported, selected by whether `input.phases` (3-tier
+ * Two shapes are supported, selected by whether `input.phases` (2-tier
  * Story-phase snapshot) or `input.tasks` (legacy 4-tier per-Task list) is
  * provided. Callers MUST pass exactly one of the two — passing both is
  * rejected as a contract violation so a mistake at the call site fails
@@ -216,7 +216,7 @@ export function renderStoryRunProgressBody(input) {
   const hasTasks = Array.isArray(input.tasks);
   if (hasPhases && hasTasks) {
     throw new TypeError(
-      'renderStoryRunProgressBody: pass either `phases` (3-tier) or `tasks` ' +
+      'renderStoryRunProgressBody: pass either `phases` (2-tier) or `tasks` ' +
         '(4-tier), not both — the snapshot shape is mutually exclusive.',
     );
   }
@@ -296,7 +296,7 @@ function renderTasksBody({
 }
 
 /**
- * Render the 3-tier Story-phase body. Pure helper for
+ * Render the 2-tier Story-phase body. Pure helper for
  * `renderStoryRunProgressBody`. Emits a `phases[]` payload whose entries
  * carry `{ name, status, startedAt, endedAt }` for init/implement/validate/close.
  */
@@ -351,7 +351,7 @@ function renderPhasesBody({ storyId, branch, phase, phases: raw, updatedAt }) {
  * renders only and, when `notify` is supplied, mirrors a low-severity webhook
  * event for operators who wire one up.
  *
- * Two shapes are supported, selected by whether `args.phases` (3-tier
+ * Two shapes are supported, selected by whether `args.phases` (2-tier
  * Story-phase snapshot) or `args.tasks` (legacy 4-tier per-Task list) is
  * provided. The webhook mirror's `done/total` count is computed from whichever
  * shape is active.

package/.agents/scripts/lib/orchestration/epic-runner/sub-agent-return.js

@@ -1,16 +1,14 @@
 /**
  * sub-agent-return.js — parse and reconcile per-Story sub-agent return text.
  *
- * `/epic-deliver` Step 2 dispatches one `Agent` tool call per Story per
+ * `/deliver` Step 2 dispatches one `Agent` tool call per Story per
  * wave. Each sub-agent owes its parent the JSON return contract documented
- * in `.agents/workflows/epic-deliver.md`:
+ * in `.agents/workflows/helpers/deliver-epic.md`:
  *
  *   {
  *     "storyId": <number>,
  *     "status": "done" | "blocked" | "failed",
  *     "phase": "init|implementing|closing|blocked|done",
- *     "tasksDone": <number>,
- *     "tasksTotal": <number>,
  *     "branchDeleted": <boolean>,
  *     "blockerCommentId": <string|null>,
  *     "detail": <string|undefined>,
@@ -29,7 +27,7 @@
  * directly to GitHub-state reconciliation plus a friction record — the
  * stronger backstop that already caught everything the heuristics caught.
  *
- * This module provides the two helpers `/epic-deliver`'s wave dispatcher
+ * This module provides the two helpers `/deliver`'s wave dispatcher
  * now uses:
  *
  *   - `parseStoryAgentReturn(raw)` — accept an already-parsed object or a
@@ -119,8 +117,6 @@ function validateStoryReturnShape(obj) {
   }
   const value = { storyId, status };
   if (typeof obj.phase === 'string') value.phase = obj.phase;
-  if (Number.isInteger(obj.tasksDone)) value.tasksDone = obj.tasksDone;
-  if (Number.isInteger(obj.tasksTotal)) value.tasksTotal = obj.tasksTotal;
   if (typeof obj.branchDeleted === 'boolean') {
     value.branchDeleted = obj.branchDeleted;
   }
@@ -143,8 +139,8 @@ function quote(text) {
  * Story ticket's live state when the sub-agent return cannot be trusted.
  *
  * The result is always conservative — `status: 'failed'` unless the live
- * ticket carries `agent::done` (or `state: 'closed'`). The phase / counters
- * are best-effort, sourced from the Story's `story-run-progress` comment;
+ * ticket carries `agent::done` (or `state: 'closed'`). The phase is
+ * best-effort, sourced from the Story's `story-run-progress` comment;
  * absence of the comment is non-fatal.
  *
  * Story #3907 — a Story carrying `agent::blocked` reconciles to
@@ -163,8 +159,6 @@ function quote(text) {
  *   storyId: number,
  *   status: 'done' | 'blocked' | 'failed',
  *   phase?: string,
- *   tasksDone?: number,
- *   tasksTotal?: number,
  *   blockerCommentId?: string,
  *   reconciledFromGitHub: true,
  *   reconcileError?: string,
@@ -223,8 +217,8 @@ export async function reconcileStoryFromGitHub({ provider, storyId } = {}) {
     }
   }
 
-  // Cross-look the story-run-progress comment for phase / task counters when
-  // present. Story #3909 retired the per-Story story-run-progress *comment*
+  // Cross-look the story-run-progress comment for the phase when present.
+  // Story #3909 retired the per-Story story-run-progress *comment*
   // (the redundant mid-flight surface), so this read now usually finds nothing
   // and the reconciled row degrades to label-only — which is fine: the labels
   // are the authoritative state. Failure here is non-fatal.
@@ -237,12 +231,6 @@ export async function reconcileStoryFromGitHub({ provider, storyId } = {}) {
     const payload = comment ? parseFencedJsonComment(comment) : null;
     if (payload && typeof payload === 'object') {
       if (typeof payload.phase === 'string') out.phase = payload.phase;
-      if (Array.isArray(payload.tasks)) {
-        out.tasksTotal = payload.tasks.length;
-        out.tasksDone = payload.tasks.filter(
-          (t) => t && t.state === 'done',
-        ).length;
-      }
     }
   } catch (err) {
     out.reconcileError = err?.message ?? String(err);
@@ -269,7 +257,7 @@ export function renderMalformedReturnsFriction({ epicId, wave, failures }) {
     '',
     `**Reason:** \`malformed-subagent-return\``,
     '',
-    `${failures.length} sub-agent return(s) did not match the /story-deliver return contract.`,
+    `${failures.length} sub-agent return(s) did not match the /deliver return contract.`,
     'Each Story below was reconciled from GitHub (labels + `story-run-progress`)',
     'and its wave-row downgraded to `failed` unless the live ticket already carried',
     '`agent::done`.',

package/.agents/scripts/lib/orchestration/epic-spec-reconciler-apply.js

@@ -730,21 +730,13 @@ function collectStructuralEdges(spec) {
   const out = {};
   if (!spec || typeof spec !== 'object') return out;
   const epicSlug = 'epic';
-  for (const feature of spec.features ?? []) {
-    if (!feature?.slug) continue;
-    out[feature.slug] = { entity: 'feature', parentSlug: epicSlug };
-    for (const story of feature.stories ?? []) {
-      if (!story?.slug) continue;
-      out[story.slug] = {
-        entity: 'story',
-        parentSlug: feature.slug,
-        dependsOn: [...(story.dependsOn ?? [])].sort(),
-      };
-      for (const task of story.tasks ?? []) {
-        if (!task?.slug) continue;
-        out[task.slug] = { entity: 'task', parentSlug: story.slug };
-      }
-    }
+  for (const story of spec.stories ?? []) {
+    if (!story?.slug) continue;
+    out[story.slug] = {
+      entity: 'story',
+      parentSlug: epicSlug,
+      dependsOn: [...(story.dependsOn ?? [])].sort(),
+    };
   }
   return out;
 }

package/.agents/scripts/lib/orchestration/epic-spec-reconciler-diff.js

@@ -18,12 +18,12 @@
  *
  * @typedef {object} SpecInput
  *   The parsed YAML returned by `lib/spec/loader.js#loadSpec`. Shape is
- *   `{ epic: {...}, features: [{slug, stories: [...]}], gates?: {...} }`
+ *   `{ epic: {...}, stories: [...], gates?: {...} }`
  *   per `.agents/schemas/epic-spec.schema.json`.
  *
  * @typedef {object} StateMappingEntry
  * @property {number} issueNumber          GH issue number this slug maps to.
- * @property {string} entity               'epic'|'feature'|'story'|'task'.
+ * @property {string} entity               'epic'|'story'.
  * @property {string} [contentHash]        Content hash captured at last
  *                                         reconcile; absence forces an
  *                                         update when ghState carries
@@ -115,7 +115,7 @@ function labelsEqual(a, b) {
  * a naive replace-style label diff would propose removing operator-
  * managed metadata that lives in these namespaces.
  *
- * Why: Story #2056 / Epic #1994 — `/epic-plan` was silently stripping
+ * Why: Story #2056 / Epic #1994 — `/plan` was silently stripping
  * `type::epic` and `risk::*` from the parent Epic on every decompose,
  * which then broke `dispatcher.js` (`type "unknown"`). Defence-in-depth
  * lives here in the diff engine: even if a future spec author drops
@@ -133,7 +133,7 @@ const PROTECTED_EPIC_LABEL_NAMESPACES = Object.freeze([
   'risk::',
   // Story #3050 — `acceptance::*` is set by Phase 7 spec-persist when
   // `planningRisk.acceptanceDisposition='not-applicable'` (or another
-  // disposition) and gates downstream `/epic-deliver` start/finalize
+  // disposition) and gates downstream `/deliver` start/finalize
   // behavior. Before this namespace was protected, Phase 8 decompose
   // diffed the Epic's labels against a spec entry that doesn't carry
   // `acceptance::*`, silently emitting an Update that stripped the
@@ -190,7 +190,7 @@ function normaliseBody(value) {
  * duplicate footer blocks and trailing `blocked by` lines are removed in
  * a single pass. Kept local to this module so the diff engine does not
  * depend on the Task-body renderer (Story #3185 / Epic #3163: the renderer
- * is going away with the 3-tier producer cutover).
+ * is going away with the 2-tier producer cutover).
  */
 const ORCHESTRATOR_FOOTER_RE = /\n?---[ \t]*\r?\n+parent:\s*#\d+[\s\S]*$/;
 
@@ -247,9 +247,8 @@ function renderFooter({ parentId, epicId, dependencies = [] }) {
  * `parent: #N` / `Epic: #M` / `blocked by #X` and breaking the cascade.
  *
  * Story #3185 — the footer compose/strip logic is inlined here rather
- * than reused from the legacy Task-body renderer module. Under the
- * 3-tier hierarchy (Epic → Feature → Story) that renderer is being
- * removed, so the diff engine carries its own footer shape. The shape
+ * than reused from the legacy Task-body renderer module. That renderer
+ * was removed, so the diff engine carries its own footer shape. The shape
  * is byte-identical to the legacy renderer's `parent: #<n>` /
  * `Epic: #<m>` / `blocked by #<x>` output so cascade-readers continue
  * to parse it unchanged.
@@ -326,7 +325,7 @@ function fieldChanges(specEntity, obs, mapping, ctx = {}) {
   // feature/story/task body fields): "When omitted, the GH issue body
   // is left untouched". Pre-Story-#2283 the engine treated `undefined`
   // as `""`, which emitted a destructive `body: <existing> → ""` Update
-  // on every `/epic-plan` Phase 8 because the decomposer's renderer
+  // on every `/plan` Phase 8 because the decomposer's renderer
   // projects the Epic spec entry from `{ id, title }` only. Skip the
   // body diff entirely when the spec did not carry a body string. An
   // explicit `body: ""` in the spec still produces a clear-op when the
@@ -413,9 +412,8 @@ function sortBySlug(ops) {
 
 /**
  * Walk the spec and yield one structural-entity record per visited
- * node. The walker is iterative-via-recursion but bounded by the spec's
- * nesting (epic → features → stories → tasks); the depth never exceeds
- * 4 so an explicit work-queue would just obscure the shape.
+ * node. The spec is 2-tier (epic → stories), so the walk is a single
+ * flat pass over `spec.stories` after the Epic record.
  *
  * @param {SpecInput} spec
  * @returns {Array<{
@@ -446,37 +444,35 @@ function flattenSpec(spec) {
   }
 
   const epicAnchor = spec.epic ? epicSlug(spec.epic) : null;
-  for (const feature of spec.features ?? []) {
+  // Duplicate-slug guard. The schema cannot express slug uniqueness across
+  // a hand-edited spec, and two same-slug Creates would orphan one GH
+  // issue (the second create overwrites the first's mapping entry).
+  // flattenSpec is the chokepoint both the loader path and the diff path
+  // flow through, so the check lives here.
+  const seenSlugs = new Set();
+  const duplicateSlugs = new Set();
+  for (const story of spec.stories ?? []) {
+    if (seenSlugs.has(story.slug)) duplicateSlugs.add(story.slug);
+    seenSlugs.add(story.slug);
+  }
+  if (duplicateSlugs.size > 0) {
+    throw new Error(
+      `spec contains duplicate story slug(s): ${[...duplicateSlugs].join(', ')}. ` +
+        `Each story slug must be unique — rename the duplicated entries in ` +
+        `the spec and re-run.`,
+    );
+  }
+  for (const story of spec.stories ?? []) {
     out.push({
-      slug: feature.slug,
-      entity: ENTITY_KINDS.FEATURE,
-      title: String(feature.title ?? ''),
-      body: feature.body,
-      labels: feature.labels,
+      slug: story.slug,
+      entity: ENTITY_KINDS.STORY,
+      title: String(story.title ?? ''),
+      body: story.body,
+      labels: story.labels,
+      wave: story.wave,
       parentSlug: epicAnchor,
+      dependsOn: story.dependsOn ?? [],
     });
-    for (const story of feature.stories ?? []) {
-      out.push({
-        slug: story.slug,
-        entity: ENTITY_KINDS.STORY,
-        title: String(story.title ?? ''),
-        body: story.body,
-        labels: story.labels,
-        wave: story.wave,
-        parentSlug: feature.slug,
-        dependsOn: story.dependsOn ?? [],
-      });
-      for (const task of story.tasks ?? []) {
-        out.push({
-          slug: task.slug,
-          entity: ENTITY_KINDS.TASK,
-          title: String(task.title ?? ''),
-          body: task.body,
-          labels: task.labels,
-          parentSlug: story.slug,
-        });
-      }
-    }
   }
   return out;
 }
@@ -509,6 +505,40 @@ function dependsOnEqual(a, b) {
   return labelsEqual(a, b);
 }
 
+/**
+ * Entity kinds that only exist in pre-v4 (3-tier) state files. The v4
+ * hard cutover (v1.60.0) removed the Feature/Task tiers; encountering one
+ * of these in `state.mapping` means the state file predates the cutover
+ * and must be migrated by the operator — there is deliberately no legacy
+ * close-op support (hard-cutover policy, git-conventions.md).
+ */
+const LEGACY_ENTITY_KINDS = Object.freeze(new Set(['feature', 'task']));
+
+/**
+ * Throw a loud, actionable error when the state mapping carries legacy
+ * Feature/Task entries. Raised early in `diff()` so the operator sees a
+ * migration instruction instead of `unknown entity kind: feature` from
+ * deep inside `closeOp`.
+ *
+ * @param {Record<string, StateMappingEntry>} mapping
+ */
+function assertNoLegacyEntities(mapping) {
+  const legacy = Object.entries(mapping).filter(([, entry]) =>
+    LEGACY_ENTITY_KINDS.has(entry?.entity),
+  );
+  if (legacy.length === 0) return;
+  const summary = legacy
+    .map(([slug, entry]) => `${slug} (#${entry.issueNumber}, ${entry.entity})`)
+    .join(', ');
+  throw new Error(
+    `diff: the epic state file is pre-v4 — it carries legacy Feature/Task ` +
+      `mapping entries: ${summary}. The 2-tier reconciler cannot process ` +
+      `these. Close the legacy Feature issues manually, then delete (or ` +
+      `reseed) the .agents/epics/<epicId>.state.json file per the v1.60.0 ` +
+      `migration notes, and re-run.`,
+  );
+}
+
 /**
  * Diff `(spec, state, ghState)` into a `Plan`. See the module header for
  * the full contract.
@@ -523,6 +553,7 @@ export function diff({ spec, state, ghState } = {}) {
     throw new TypeError('diff: state argument is required');
   }
   const mapping = state.mapping ?? {};
+  assertNoLegacyEntities(mapping);
   const seenSpecSlugs = new Set();
 
   for (const entity of flattenSpec(spec)) {
@@ -595,7 +626,7 @@ export function diff({ spec, state, ghState } = {}) {
     plan.closes.push(
       closeOp({
         slug,
-        entity: mapped.entity ?? ENTITY_KINDS.TASK,
+        entity: mapped.entity ?? ENTITY_KINDS.STORY,
         issueNumber: mapped.issueNumber,
         title: mapped.title,
       }),

package/.agents/scripts/lib/orchestration/epic-spec-reconciler-ops.js

@@ -44,7 +44,7 @@
  * apply pipeline. Arrays are always present (never undefined); an empty
  * plan has all four arrays at length 0.
  *
- * @typedef {'epic'|'feature'|'story'|'task'} EntityKind
+ * @typedef {'epic'|'story'} EntityKind
  *   The structural entity kind. Matches schema $defs — agent-execution
  *   labels (agent::*) are owned by the wave-runner and never appear in
  *   the structural surface.
@@ -87,7 +87,7 @@
  * @typedef {object} RelinkOp
  * @property {'relink'} kind
  * @property {string}   slug
- * @property {EntityKind} entity     'story' (dependsOn) or 'feature'|'story'|'task' (parent).
+ * @property {EntityKind} entity     'story' (dependsOn / parent).
  * @property {number}   issueNumber
  * @property {{ before: string|null, after: string|null }} [parent]
  *   Parent slug change. `null` on either side means "no parent" (epic
@@ -117,9 +117,7 @@ export const OP_KINDS = Object.freeze({
 /** Entity-kind discriminator values, matching the schema $defs. */
 export const ENTITY_KINDS = Object.freeze({
   EPIC: 'epic',
-  FEATURE: 'feature',
   STORY: 'story',
-  TASK: 'task',
 });
 
 const VALID_OP_KINDS = new Set(Object.values(OP_KINDS));

package/.agents/scripts/lib/orchestration/file-assumptions.js

@@ -8,7 +8,7 @@
  * are batched per-Story and surfaced through the same error envelope the
  * decompose loop already uses.
  *
- * Under the 3-tier hierarchy (Epic → Feature → Story; Epic #3078 / #3238)
+ * Under the 2-tier hierarchy (Epic → Story; Epic #3078 / #3238)
  * the Story is the implementation unit — there is no `type::task` ticket
  * layer — so the gate scans `type === 'story'` tickets and reads the
  * `{ path, assumption }` entries inlined on each Story body.
@@ -25,8 +25,9 @@
  * therefore validates each Story against the **simulated post-predecessor
  * tree** — base-branch existence overlaid with the create/delete delta of
  * the Story's transitive `depends_on` predecessors (the same reachability
- * walk the conflict gate uses, imported from `ticket-validator-conflicts.js`
- * rather than re-derived). Two extra wave-aware rules layer on top of the
+ * walk the conflict gate uses, imported from the shared
+ * `story-reachability.js` leaf rather than re-derived). Two extra
+ * wave-aware rules layer on top of the
  * base-branch rules:
  *   - `creates`            + path created by a **predecessor** → mismatch
  *     (`expected: 'refactors-existing'`) telling the planner to declare
@@ -48,8 +49,8 @@
 import { gitSpawn } from '../git-utils.js';
 import { parse as parseStoryBody } from '../story-body/story-body.js';
 import { FILE_ASSUMPTION_VALUES } from './file-assumption-enum.js';
+import { computeStoryReachability } from './story-reachability.js';
 import { isObjectPathEntry } from './task-body-validator.js';
-import { computeStoryReachability } from './ticket-validator-conflicts.js';
 
 /**
  * Default git probe — returns `true` when `path` exists at
@@ -254,7 +255,7 @@ function predecessorMutator(index, path, predecessors) {
  *     mismatches: object[]  // structured payload for downstream tooling
  *   }
  *
- * Under the 3-tier hierarchy the Story is the implementation unit, so the
+ * Under the 2-tier hierarchy the Story is the implementation unit, so the
  * gate scans `type === 'story'` tickets and reads the inline
  * `{ path, assumption }` entries on each Story body.
  *

package/.agents/scripts/lib/orchestration/finalize/close-planning-tickets.js

@@ -4,7 +4,7 @@
  * planning context tickets (PRD / Tech Spec / Acceptance Spec) linked
  * from the Epic body's `## Planning Artifacts` section.
  *
- * Extracted from `/epic-deliver` Phase 7.1 prose (the `gh issue close`
+ * Extracted from `/deliver` Phase 7.1 prose (the `gh issue close`
  * sequence) so the lifecycle Finalizer listener has a single async
  * helper to call. Reuses `parseLinkedIssues` so the three planning ids
  * are read from the same canonical body shape that `epic-plan` writes

package/.agents/scripts/lib/orchestration/finalize/open-or-locate-pr.js

@@ -4,7 +4,7 @@
  * request, or locates the existing one when finalize is replaying after
  * a crash between `gh pr create` and the `pr.created` emit.
  *
- * Extracted from `/epic-deliver` Phase 7.1 prose so the lifecycle
+ * Extracted from `/deliver` Phase 7.1 prose so the lifecycle
  * Finalizer listener has a single async helper that returns the
  * `{ prNumber, url, created }` envelope it needs to compose
  * downstream emits.
@@ -26,7 +26,7 @@
  * the same head branch: the second call short-circuits at the probe and
  * does not attempt to create a duplicate PR. This is the AC-10
  * idempotency contract the Finalizer relies on for cross-process
- * re-runs of `/epic-deliver`.
+ * re-runs of `/deliver`.
  */
 
 import { spawnSync } from 'node:child_process';

package/.agents/scripts/lib/orchestration/finalize/sanitize-skip-ci.js

@@ -4,7 +4,7 @@
  * `[skip ci]` markers (and the four variant spellings GitHub honours)
  * from a text payload.
  *
- * Story #3165: `/epic-deliver` Phase 7 opens a PR squashed into `main`
+ * Story #3165: `/deliver` Phase 7 opens a PR squashed into `main`
  * via `gh pr merge --squash`. Story commits legitimately carry
  * `[skip ci]` markers under `delivery.ci.skipForStoryPushes: true` to
  * keep CI from firing on the wave's intermediate pushes. When GitHub

package/.agents/scripts/lib/orchestration/lease-guard-shared.js

@@ -0,0 +1,144 @@
+/**
+ * lease-guard-shared.js — Story #3992: single-source the lease-acquisition
+ * kernel shared by the three per-surface lease guards.
+ *
+ * `epic-deliver-lease-guard.js`, `epic-plan-lease-guard.js`, and
+ * `single-story-lease-guard.js` historically each carried their own copy of
+ * the operator-handle resolution and the fail-closed acquire wrapper around
+ * `ticket-lease.acquireLease` (anchor `heartbeatAt` to `now` so a foreign
+ * assignee always reads as a live claim, then throw an operator-facing
+ * refusal naming the current owner unless `--steal`). The three copies had
+ * already diverged — different `resolveOperator` signatures and different
+ * missing-handle behaviour (`null` vs `throw`) — and were synchronised only
+ * by docstring promise ("This mirrors the sibling lease guards…").
+ *
+ * This module is the single home for the kernel, modelled on the
+ * shared plumbing inside `story-close/format-autofix.js` (Story #3332,
+ * consolidated by Story #4017). The
+ * per-surface guards now differ only in injected **policy**:
+ *
+ *   - **Operator candidates** — each surface supplies its own ordered
+ *     candidate list (e.g. `--as` flag → `github.operatorHandle` →
+ *     `git user.email` for `/deliver`; bare `operatorHandle` for the
+ *     plan/standalone paths).
+ *   - **Missing-handle behaviour** — `'null'` (return null; the caller fails
+ *     closed at acquire time) vs `'throw'` (refuse immediately with surface
+ *     wording). The divergence between the plan path (`null`) and the
+ *     standalone path (`throw`) is intentional: the plan path also calls
+ *     `resolveOperator` on its best-effort release leg, where a missing
+ *     handle must degrade to a `no-operator` no-op rather than throw.
+ *   - **Refusal wording** — each surface renders its own operator-facing
+ *     message via `renderRefusal(result, ticketId)`.
+ *   - **Liveness anchoring** — the plan/standalone paths have no heartbeat
+ *     ledger, so they anchor `heartbeatAt` to `now` (fail-closed: every
+ *     foreign claim reads live). `/deliver` threads a real
+ *     `heartbeatAt` through from the lifecycle ledger, so it opts out of
+ *     anchoring.
+ *
+ * The unclaimed / already-held / foreign-claim decision table itself (and
+ * the steal transfer) lives in `ticket-lease.acquireLease`; this kernel owns
+ * the fail-closed parameterisation and the refuse-by-throw boundary that the
+ * three guards previously each re-implemented.
+ *
+ * Per `.agents/rules/orchestration-error-handling.md`, failures surface via
+ * `throw new Error(...)`, never `Logger.fatal`.
+ */
+
+import { acquireLease, normalizeOperatorHandle } from './ticket-lease.js';
+
+/**
+ * Resolve the operator handle from an ordered candidate list, applying the
+ * surface's missing-handle policy.
+ *
+ * Each candidate is passed through the shared `normalizeOperatorHandle` so a
+ * leading `@` is stripped (the assignees API expects bare logins, not
+ * `@`-prefixed mentions) and the shipped `@[USERNAME]` placeholder maps to
+ * `null` — otherwise the assignee PATCH is rejected (HTTP 422) and the
+ * self-held-claim comparison (`owner === operator`) never matches. The first
+ * candidate that normalises to a non-null handle wins.
+ *
+ * @param {object} opts
+ * @param {Array<string|null|undefined>} opts.candidates  Ordered raw handles.
+ * @param {'null'|'throw'} [opts.missingHandleBehavior='null']  What to do
+ *   when no candidate resolves: return `null`, or throw with the surface's
+ *   configured wording.
+ * @param {string} [opts.missingHandleMessage]  Error message used when
+ *   `missingHandleBehavior` is `'throw'`.
+ * @returns {string|null} Bare operator handle, or `null` (policy `'null'`).
+ * @throws {Error} When no candidate resolves and the policy is `'throw'`.
+ */
+export function resolveOperatorFromCandidates({
+  candidates,
+  missingHandleBehavior = 'null',
+  missingHandleMessage,
+} = {}) {
+  for (const raw of candidates ?? []) {
+    const normalized = normalizeOperatorHandle(raw);
+    if (normalized !== null) return normalized;
+  }
+  if (missingHandleBehavior === 'throw') {
+    throw new Error(missingHandleMessage);
+  }
+  return null;
+}
+
+/**
+ * Acquire a ticket lease, failing closed by throwing the surface's refusal
+ * message when the claim is refused (live foreign owner, no `steal`).
+ *
+ * When `anchorHeartbeatToNow` is set (the plan/standalone paths, which have
+ * no heartbeat ledger), `heartbeatAt` and `now` are both anchored to the
+ * same resolved clock value so `isClaimLive` returns true for ANY foreign
+ * owner — `acquireLease` then refuses a foreign assignee unless `steal` is
+ * set, while unclaimed and self-held tickets still proceed without a write.
+ * When unset (`/deliver`), the caller-supplied `heartbeatAt` / `now`
+ * pass through untouched.
+ *
+ * @param {object} opts
+ * @param {object} opts.provider          Ticketing provider.
+ * @param {number} opts.ticketId          Ticket to claim.
+ * @param {string} opts.operator          Resolved operator handle.
+ * @param {number|null} [opts.heartbeatAt=null]  Current owner's last
+ *   heartbeat (epoch ms). Ignored when `anchorHeartbeatToNow` is set.
+ * @param {boolean} [opts.steal=false]    Forcibly transfer a foreign claim.
+ * @param {object} [opts.config]          Resolved config (TTL default).
+ * @param {number} [opts.now]             Injectable clock (epoch ms; tests).
+ * @param {boolean} [opts.anchorHeartbeatToNow=false]  Fail-closed liveness
+ *   anchoring for surfaces with no heartbeat source.
+ * @param {(result: object, ticketId: number) => string} opts.renderRefusal
+ *   Renders the operator-facing refusal message for a refused claim.
+ * @returns {Promise<{ acquired: boolean, owner: string, previousOwner: string|null, reason: string }>}
+ * @throws {Error} When the claim is refused (`result.acquired === false`).
+ */
+export async function acquireLeaseFailClosed({
+  provider,
+  ticketId,
+  operator,
+  heartbeatAt = null,
+  steal = false,
+  config,
+  now,
+  anchorHeartbeatToNow = false,
+  renderRefusal,
+}) {
+  let resolvedHeartbeatAt = heartbeatAt;
+  let resolvedNow = now;
+  if (anchorHeartbeatToNow) {
+    resolvedNow =
+      typeof now === 'number' && Number.isFinite(now) ? now : Date.now();
+    resolvedHeartbeatAt = resolvedNow;
+  }
+  const result = await acquireLease({
+    provider,
+    ticketId,
+    operator,
+    heartbeatAt: resolvedHeartbeatAt,
+    steal,
+    config,
+    now: resolvedNow,
+  });
+  if (!result.acquired) {
+    throw new Error(renderRefusal(result, ticketId));
+  }
+  return result;
+}

package/.agents/scripts/lib/orchestration/lifecycle/emit-story-dispatch-end.js

@@ -12,7 +12,7 @@
  *   `lib/orchestration/wave-session.js`, which nothing imports outside
  *   tests — so every dispatched Story stayed "in-flight" forever and the
  *   idle watchdog flagged completed Stories as stalled. The host-LLM driven
- *   `/epic-deliver` path closes a wave through `epic-execute-record-wave.js`,
+ *   `/deliver` path closes a wave through `epic-execute-record-wave.js`,
  *   so that CLI is the correct place to emit the matching dispatch-end per
  *   recorded Story.
  *

package/.agents/scripts/lib/orchestration/lifecycle/emit-story-heartbeat.js

@@ -23,9 +23,9 @@
  *
  * The schema declares `additionalProperties: false`, so this emitter's
  * signature is deliberately narrow: only the schema-allowed fields are
- * accepted. Earlier per-child counters (`taskId`, `tasksDone`,
- * `tasksTotal`, `currentTaskId`) were dropped under Epic #3078's
- * 3-tier hard cutover — they would fail strict validation and have no
+ * accepted. The earlier per-child Task id and progress counters
+ * were dropped under Epic #3078's
+ * 2-tier hard cutover — they would fail strict validation and have no
  * meaning now that the Story is the leaf execution unit with no child
  * tickets. The optional `operator` field (Story #3480) records the handle
  * holding the assignee-as-lease claim; it is included only when supplied so