mandrel 1.93.0 → 1.94.0

package/.agents/scripts/lib/orchestration/deliver-route.js

@@ -0,0 +1,173 @@
+/**
+ * lib/orchestration/deliver-route.js — the deliver-side reader for the
+ * plan-time single-delivery seam (Epic #4475, M4-A).
+ *
+ * The plan path already ships the seam inert (Epic #4474): the risk verdict's
+ * `deliveryShape`, the `delivery::single` label, and the
+ * `epic-plan-state.decompose = { ticketCount: 0, shape: "single" }`
+ * checkpoint. Nothing on the deliver side read them — until this module. It
+ * folds those two markers (plus the global kill-switch) into a single
+ * delivery-route verdict for `/deliver`.
+ *
+ * Pure and total — inputs in, verdict out. No GitHub calls, no I/O, no
+ * throws. It mirrors how `review-depth.js#resolveDepth` and
+ * `epic-audit-prepare.js` read `planningRisk` / `decompose` off the
+ * `epic-plan-state` checkpoint: the caller fetches the Epic labels + the
+ * checkpoint, then hands both here.
+ *
+ * ── Routing precedence (highest wins) ──────────────────────────────────
+ *   1. Kill-switch. `delivery.routing.singleDelivery === false` forces
+ *      `fan-out` for EVERY Epic, even a single-labelled one — the instant
+ *      global revert (`lib/config/delivery-routing.js`). Overrides all.
+ *   2. Single marker. The `delivery::single` label (primary) OR
+ *      `checkpoint.decompose.shape === "single"` (secondary) → `single`.
+ *   3. Wide-DAG advisory. A fan-out-shaped Epic whose ready-width > 1 is
+ *      genuine parallelism → `fan-out`. Deliver-time width only ADVISES —
+ *      it never reroutes a single-marked Epic (that would orphan a Story
+ *      tree that does not exist; re-route = re-plan).
+ *   4. Legacy / no marker → `fan-out` (safe backward-compat: a legacy Epic
+ *      has an authored Story tree the fan-out engine consumes).
+ *
+ * BEHAVIOR-PRESERVING in M4-A: the router consumes a `single` verdict via a
+ * stub that continues at `deliver-epic.md` (fan-out), so no `/deliver`
+ * observably changes until M4-B lands `deliver-epic-single.md`.
+ *
+ * @typedef {'single'|'fan-out'} DeliveryRoute
+ */
+
+import { getDeliveryRouting } from '../config/delivery-routing.js';
+
+/** The canonical single-delivery routing marker label. */
+export const DELIVERY_SINGLE_LABEL = 'delivery::single';
+
+/**
+ * True when the Epic carries the `delivery::single` routing label. Tolerant
+ * of the two label shapes callers hold: an array of label-name strings, or an
+ * array of `{ name }` objects (the GitHub REST label shape).
+ *
+ * @param {{ labels?: Array<string | { name?: string }> } | null | undefined} epic
+ * @returns {boolean}
+ */
+function hasSingleLabel(epic) {
+  const labels = Array.isArray(epic?.labels) ? epic.labels : [];
+  return labels.some((l) => {
+    const name = typeof l === 'string' ? l : l?.name;
+    return name === DELIVERY_SINGLE_LABEL;
+  });
+}
+
+/**
+ * True when the plan-state checkpoint's `decompose.shape` is the deliberate
+ * single shape. `plan-persist.js` writes `decompose = { ticketCount: 0,
+ * shape: "single" }` for a spec-only plan; every other value (including a
+ * legacy checkpoint with no `shape` field) is not-single.
+ *
+ * @param {{ decompose?: { shape?: string } } | null | undefined} checkpoint
+ * @returns {boolean}
+ */
+function hasSingleDecomposeShape(checkpoint) {
+  return checkpoint?.decompose?.shape === 'single';
+}
+
+/**
+ * Resolve the delivery route for one Epic from its labels, its plan-state
+ * checkpoint, and the resolved config. See the module header for the full
+ * precedence. Pure — never throws; malformed / absent inputs degrade to the
+ * safe `fan-out` default.
+ *
+ * @param {{ labels?: Array<string | { name?: string }> } | null | undefined} epic
+ *   The Epic ticket snapshot (only `labels` is read here).
+ * @param {{ decompose?: { shape?: string } } | null | undefined} checkpoint
+ *   The `epic-plan-state` structured comment, parsed (or `null` on a legacy
+ *   Epic that predates the checkpoint — treated as no marker).
+ * @param {object | null | undefined} config
+ *   The resolved config; `delivery.routing.singleDelivery` is the kill-switch.
+ * @returns {{ route: DeliveryRoute, reason: string, singleDeliveryEnabled: boolean }}
+ */
+export function resolveEpicDeliveryRoute(epic, checkpoint, config) {
+  const { singleDelivery } = getDeliveryRouting(config);
+
+  // 1. Kill-switch — overrides all. A `false` value forces fan-out even for
+  //    an Epic the planner marked single (the instant global revert).
+  if (singleDelivery === false) {
+    return {
+      route: 'fan-out',
+      reason:
+        'kill-switch: delivery.routing.singleDelivery=false forces fan-out for every Epic',
+      singleDeliveryEnabled: false,
+    };
+  }
+
+  // 2. Single marker — label (primary) OR checkpoint decompose shape
+  //    (secondary). Either alone routes single.
+  const labelled = hasSingleLabel(epic);
+  const shaped = hasSingleDecomposeShape(checkpoint);
+  if (labelled || shaped) {
+    const via =
+      labelled && shaped
+        ? `${DELIVERY_SINGLE_LABEL} label + decompose.shape="single"`
+        : labelled
+          ? `${DELIVERY_SINGLE_LABEL} label`
+          : 'decompose.shape="single"';
+    return {
+      route: 'single',
+      reason: `single marker present (${via})`,
+      singleDeliveryEnabled: true,
+    };
+  }
+
+  // 3/4. No single marker → fan-out (a wide DAG or a legacy Story tree; the
+  //      deliver-time width only advises and never reroutes here).
+  return {
+    route: 'fan-out',
+    reason: 'no single marker — fan-out (legacy Story tree or wide DAG)',
+    singleDeliveryEnabled: true,
+  };
+}
+
+/**
+ * Compute the ready-width of a delivery plan — the count of work units that
+ * could dispatch on the first beat. It is the mechanical parallelism signal
+ * the planner uses at plan time to mark a genuinely-wide Epic `fan-out`, and
+ * that `/deliver` may surface as an advisory at deliver time (it never
+ * reroutes — see the module header).
+ *
+ * Accepts either input shape the framework already produces:
+ *   - Delivery-Slicing rows — `[{ independent: boolean }, …]` from
+ *     `parseDeliverySlicingTable`. A serial chain (every row
+ *     `Independent: No`, or a lone independent slice) has width 1; two or
+ *     more independent slices yield a width equal to that independent count
+ *     (> 1) — genuine parallelism.
+ *   - A wave DAG — `[[…], […], …]` (the array-of-waves `state.waves` shape
+ *     `runBuildWaveDagPhase` produces). The width is the largest wave — the
+ *     most Stories ready to dispatch on a single beat.
+ *
+ * Pure and total: an empty / malformed / unrecognized input degrades to
+ * width 1 (the safe "not wide" signal). Never throws.
+ *
+ * @param {Array<{ independent?: boolean }> | Array<Array<unknown>> | null | undefined} deliverySlicingRowsOrDag
+ * @returns {number} an integer ≥ 1.
+ */
+export function computeReadyWidth(deliverySlicingRowsOrDag) {
+  const input = deliverySlicingRowsOrDag;
+  if (!Array.isArray(input) || input.length === 0) return 1;
+
+  // Wave-DAG shape: an array whose entries are themselves arrays.
+  if (input.every((entry) => Array.isArray(entry))) {
+    let widest = 1;
+    for (const wave of input) {
+      if (wave.length > widest) widest = wave.length;
+    }
+    return widest;
+  }
+
+  // Delivery-Slicing rows: entries are `{ independent }` records.
+  const independentCount = input.reduce(
+    (acc, row) =>
+      row && typeof row === 'object' && row.independent === true
+        ? acc + 1
+        : acc,
+    0,
+  );
+  return independentCount >= 2 ? independentCount : 1;
+}

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

@@ -41,7 +41,7 @@ import { buildAuthoringGrounding } from './spec-authoring-grounding.js';
  * @param {{ github?: { owner?: string, repo?: string }|null }} opts
  * @returns {string|null}
  */
-export function resolveMemoryDir({ github } = {}) {
+function resolveMemoryDir({ github } = {}) {
   if (
     typeof process.env.MANDREL_MEMORY_DIR === 'string' &&
     process.env.MANDREL_MEMORY_DIR.length > 0

package/.agents/scripts/lib/orchestration/epic-run-state-store.js

@@ -326,6 +326,239 @@ export async function recordStoryStatus({
   });
 }
 
+/**
+ * Terminal / in-progress per-slice statuses persisted on a single-delivery
+ * checkpoint. The single-delivery analogue of `STORY_STATUSES` — a spec-only
+ * plan authors no Story tickets, so the leaf work unit is a `## Delivery
+ * Slicing` slice walked in-session on `epic/<id>` (Epic #4475). The design's
+ * durable contract is `{pending, done}`; `blocked`/`failed` mirror the story
+ * map so the M4-B executor can record a stalled slice without a schema bump.
+ */
+export const SLICE_STATUSES = Object.freeze([
+  'pending',
+  'done',
+  'blocked',
+  'failed',
+]);
+
+/**
+ * Build the initial per-slice status map from parsed `## Delivery Slicing`
+ * rows (`parseDeliverySlicingTable` output — `[{ slice, independent }]`).
+ * Every slice seeds at `status: 'pending'`, keyed by a **stable, position-
+ * derived** id `slice-<n>` (1-based) so a re-run over the same table
+ * round-trips its keys. The slice's human label is carried through as `title`
+ * for the operator rollup. Pure — exported for unit tests.
+ *
+ * @param {Array<{ slice?: string, independent?: boolean } | string>} slices
+ * @returns {Record<string, { status: string, title?: string }>}
+ */
+export function buildSliceStatusMap(slices) {
+  const out = {};
+  const rows = Array.isArray(slices) ? slices : [];
+  rows.forEach((entry, i) => {
+    const sliceId = `slice-${i + 1}`;
+    const record = { status: 'pending' };
+    const title =
+      typeof entry === 'string'
+        ? entry
+        : entry && typeof entry === 'object' && typeof entry.slice === 'string'
+          ? entry.slice
+          : undefined;
+    if (title) record.title = title;
+    out[sliceId] = record;
+  });
+  return out;
+}
+
+/**
+ * Merge a freshly-seeded slice status map onto a persisted one. Every slice
+ * present in either map appears in the result; when a slice exists in the
+ * prior map its recorded `status` wins (recorded progress — a `done` slice
+ * whose work already sits on `epic/<id>` — is never lost), while its `title`
+ * is refreshed from the incoming seed. Slices present only in the incoming
+ * seed are added at `pending`. Pure — exported for unit tests.
+ *
+ * @param {Record<string, object>|undefined} prior
+ * @param {Record<string, object>} incoming
+ * @returns {Record<string, object>}
+ */
+export function mergeSliceStatuses(prior, incoming) {
+  const priorMap = prior && typeof prior === 'object' ? prior : {};
+  const seedMap = incoming && typeof incoming === 'object' ? incoming : {};
+  const out = {};
+  for (const key of new Set([
+    ...Object.keys(priorMap),
+    ...Object.keys(seedMap),
+  ])) {
+    const priorEntry = priorMap[key];
+    const seedEntry = seedMap[key];
+    if (priorEntry && typeof priorEntry === 'object') {
+      const merged = { ...priorEntry };
+      if (seedEntry && typeof seedEntry.title === 'string') {
+        merged.title = seedEntry.title;
+      }
+      out[key] = merged;
+    } else {
+      out[key] = seedEntry;
+    }
+  }
+  return out;
+}
+
+/**
+ * Initialize (or resume) the single-delivery checkpoint for an Epic. The
+ * single-delivery analogue of `initialize` (Story #4155's per-Story map),
+ * writing the slice-map shape the M4-B executor walks:
+ *
+ * ```json
+ * {
+ *   "epicId": 4475,
+ *   "deliveryShape": "single",
+ *   "slices": { "slice-1": { "status": "pending", "title": "…" } },
+ *   "concurrencyCap": 1,
+ *   "storyCount": 0
+ * }
+ * ```
+ *
+ * Idempotent + resume-preserving: on a re-run an existing single checkpoint
+ * has its slice map **merged** (every already-`done` slice keeps its status
+ * so the executor skips it — the work already sits on `epic/<id>`), while
+ * newly-authored slices seed at `pending`. `startedAt` is preserved. A
+ * checkpoint written for the fan-out shape is NOT reinterpreted here — the
+ * caller (`epic-deliver-prepare.js --single`) owns route selection.
+ *
+ * @param {{
+ *   provider: import('../ITicketingProvider.js').ITicketingProvider,
+ *   epicId: number,
+ *   slices: Array<{ slice?: string, independent?: boolean } | string>,
+ *   concurrencyCap?: number,
+ * }} opts
+ * @returns {Promise<object>} the persisted (or preserved) state
+ */
+export async function initializeSingle({
+  provider,
+  epicId,
+  slices,
+  concurrencyCap = 1,
+} = {}) {
+  assertProvider(provider);
+  assertEpicId(epicId);
+  const seededSlices = buildSliceStatusMap(slices);
+  const storyCount = 0;
+  const existing = await read({ provider, epicId });
+  if (existing && existing.deliveryShape === 'single') {
+    const mergedSlices = mergeSliceStatuses(existing.slices, seededSlices);
+    if (
+      existing.concurrencyCap === concurrencyCap &&
+      sliceMapsEqual(existing.slices, mergedSlices)
+    ) {
+      return existing;
+    }
+    return write({
+      provider,
+      epicId,
+      state: {
+        ...existing,
+        deliveryShape: 'single',
+        concurrencyCap,
+        storyCount,
+        slices: mergedSlices,
+      },
+    });
+  }
+  return write({
+    provider,
+    epicId,
+    state: {
+      epicId,
+      startedAt: new Date().toISOString(),
+      deliveryShape: 'single',
+      concurrencyCap,
+      storyCount,
+      phase: 'prepare',
+      slices: seededSlices,
+      manualInterventions: [],
+    },
+  });
+}
+
+/**
+ * Record a per-slice terminal (or in-progress) status on a single-delivery
+ * checkpoint. The single-delivery analogue of `recordStoryStatus`: the M4-B
+ * executor calls this after each Delivery-Slicing slice commits to
+ * `epic/<id>`, flipping `slices[sliceId].status` `pending → done` so a resumed
+ * run skips the already-landed slice. Reads the current state first, splices
+ * the single slice's record into the `slices` map, and re-writes; other slices
+ * and all run-level fields are preserved verbatim. Tolerant of a
+ * legacy/absent `slices` map (treated as empty).
+ *
+ * @param {{
+ *   provider: import('../ITicketingProvider.js').ITicketingProvider,
+ *   epicId: number,
+ *   sliceId: string,
+ *   status: string,
+ *   title?: string,
+ * }} opts
+ * @returns {Promise<object>} the persisted state
+ */
+export async function recordSliceStatus({
+  provider,
+  epicId,
+  sliceId,
+  status,
+  title,
+} = {}) {
+  assertProvider(provider);
+  assertEpicId(epicId);
+  if (typeof sliceId !== 'string' || sliceId.length === 0) {
+    throw new TypeError(
+      'recordSliceStatus: sliceId must be a non-empty string',
+    );
+  }
+  if (!SLICE_STATUSES.includes(status)) {
+    throw new RangeError(
+      `recordSliceStatus: status "${status}" must be one of: ${SLICE_STATUSES.join(', ')}`,
+    );
+  }
+  const existing = (await read({ provider, epicId })) ?? {};
+  const slices =
+    existing.slices && typeof existing.slices === 'object'
+      ? { ...existing.slices }
+      : {};
+  const prior = slices[sliceId] ?? {};
+  const record = { ...prior, status };
+  if (typeof title === 'string' && title) record.title = title;
+  slices[sliceId] = record;
+  return write({
+    provider,
+    epicId,
+    state: { ...existing, slices },
+  });
+}
+
+/**
+ * Structural equality on two slice status maps — same key set and, per key,
+ * the same `status` and `title`. Used by `initializeSingle` to decide whether
+ * an idempotent re-prepare needs a rewrite. Pure.
+ *
+ * @param {Record<string, object>|undefined} a
+ * @param {Record<string, object>|undefined} b
+ * @returns {boolean}
+ */
+function sliceMapsEqual(a, b) {
+  const left = a && typeof a === 'object' ? a : {};
+  const right = b && typeof b === 'object' ? b : {};
+  const keys = Object.keys(left);
+  if (keys.length !== Object.keys(right).length) return false;
+  for (const key of keys) {
+    const l = left[key] ?? {};
+    const r = right[key];
+    if (!r) return false;
+    if (l.status !== r.status || l.title !== r.title) return false;
+  }
+  return true;
+}
+
 /**
  * Append a manual-intervention record to the checkpoint. Out-of-band
  * recovery steps the host LLM performs during a delivery — `AskUserQuestion`

package/.agents/scripts/lib/orchestration/lifecycle/emit-slice-lifecycle.js

@@ -0,0 +1,270 @@
+/**
+ * emit-slice-lifecycle.js — Epic #4475 (M4-A).
+ *
+ * Programmatic emitters for the three single-delivery slice lifecycle events
+ * (`slice.start`, `slice.end`, `slice.heartbeat`) — the single-delivery
+ * analogues of the per-Story `story.dispatch.start` / `story.dispatch.end` /
+ * `story.heartbeat` events. They append one schema-validated NDJSON record to
+ * `temp/epic-<id>/lifecycle.ndjson`, mirroring `emit-story-heartbeat.js`.
+ *
+ * A single-delivery run collapses the whole Epic into one long guarded
+ * session walking the `## Delivery Slicing` table on `epic/<id>`. Without a
+ * per-Story heartbeat the `/deliver` idle watchdog cannot tell a live session
+ * from a dead one, so these events give the long session an inspectable
+ * forward-progress signal (`slice.heartbeat`) plus per-slice boundaries
+ * (`slice.start` / `slice.end`) the resume path reads back.
+ *
+ * Introduced INERT in M4-A: the executor that emits these lands in M4-B
+ * (`deliver-epic-single.md`). Shipping the emitters + schemas now keeps that
+ * PR the flip-only change.
+ *
+ * The emit is best-effort at the call site (a failure to append MUST NOT
+ * block the slice transition itself); callers catch and log via the script's
+ * Logger, exactly as the story-heartbeat callers do. These functions still
+ * throw on a programming error (bad argument / schema mismatch) so the bug
+ * surfaces in tests.
+ */
+
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+import { epicLedgerPath } from '../../config/temp-paths.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_DIR = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  '..',
+  'schemas',
+  'lifecycle',
+);
+
+const VALID_PHASES = new Set([
+  'init',
+  'implementing',
+  'closing',
+  'blocked',
+  'done',
+]);
+
+const VALID_OUTCOMES = new Set(['done', 'blocked', 'failed', 'skipped']);
+
+/** Lazily-compiled AJV validators, one per event schema. */
+const _validators = new Map();
+
+function getValidator(event) {
+  let validator = _validators.get(event);
+  if (!validator) {
+    const schema = JSON.parse(
+      readFileSync(path.join(SCHEMA_DIR, `${event}.schema.json`), 'utf8'),
+    );
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    addFormats(ajv);
+    validator = ajv.compile(schema);
+    _validators.set(event, validator);
+  }
+  return validator;
+}
+
+function assertEpicId(epicId) {
+  if (!Number.isInteger(epicId) || epicId < 1) {
+    throw new Error('emit-slice-lifecycle: epicId must be a positive integer');
+  }
+}
+
+function assertSliceId(sliceId) {
+  if (typeof sliceId !== 'string' || sliceId.length === 0) {
+    throw new Error('emit-slice-lifecycle: sliceId must be a non-empty string');
+  }
+}
+
+/**
+ * Validate `payload` against `<event>.schema.json`, then append it as a single
+ * NDJSON `emitted` record to the Epic ledger. Shared tail of all three
+ * emitters.
+ *
+ * @param {string} event
+ * @param {object} payload
+ * @param {{ epicId: number, timestamp: string, config?: object, ledgerPath?: string }} ctx
+ * @returns {{ ledgerPath: string, record: object }}
+ */
+function appendSliceEvent(
+  event,
+  payload,
+  { epicId, timestamp, config, ledgerPath: ledgerPathOverride },
+) {
+  const validator = getValidator(event);
+  if (!validator(payload)) {
+    const detail = (validator.errors ?? [])
+      .map((e) => `${e.instancePath || '/'} ${e.message}`)
+      .join('; ');
+    throw new Error(
+      `emit-slice-lifecycle: ${event} payload failed schema validation: ${detail}`,
+    );
+  }
+
+  const ledgerPath = ledgerPathOverride ?? epicLedgerPath(epicId, config);
+  mkdirSync(path.dirname(ledgerPath), { recursive: true });
+  const record = { kind: 'emitted', ts: timestamp, event, payload };
+  appendFileSync(ledgerPath, `${JSON.stringify(record)}\n`, 'utf8');
+  return { ledgerPath, record };
+}
+
+/**
+ * Append one `slice.start` record as the executor begins implementing a slice.
+ *
+ * @param {object} opts
+ * @param {number} opts.epicId
+ * @param {string} opts.sliceId       Stable slice-map key (e.g. `slice-1`).
+ * @param {number} [opts.sliceIndex]  Zero-based position in the Delivery
+ *                                    Slicing table.
+ * @param {string} [opts.title]       Human-readable slice label.
+ * @param {string} [opts.timestamp]   ISO-8601 wall clock. Defaults to now().
+ * @param {object} [opts.config]
+ * @param {string} [opts.ledgerPath]  Override for tests.
+ * @returns {{ ledgerPath: string, record: object }}
+ */
+export function emitSliceStart(opts) {
+  const {
+    epicId,
+    sliceId,
+    sliceIndex,
+    title,
+    timestamp = new Date().toISOString(),
+    config,
+    ledgerPath,
+  } = opts ?? {};
+  assertEpicId(epicId);
+  assertSliceId(sliceId);
+
+  const payload = {
+    event: 'slice.start',
+    epicId,
+    sliceId,
+    ...(Number.isInteger(sliceIndex) ? { sliceIndex } : {}),
+    ...(typeof title === 'string' ? { title } : {}),
+    timestamp,
+  };
+  return appendSliceEvent('slice.start', payload, {
+    epicId,
+    timestamp,
+    config,
+    ledgerPath,
+  });
+}
+
+/**
+ * Append one `slice.end` record when a slice finishes. A `done` outcome is
+ * what the slice-map checkpoint flips `slices[id].status` to before the walk
+ * advances.
+ *
+ * @param {object} opts
+ * @param {number} opts.epicId
+ * @param {string} opts.sliceId
+ * @param {'done'|'blocked'|'failed'|'skipped'} opts.outcome
+ * @param {number} [opts.sliceIndex]
+ * @param {number} [opts.durationMs]
+ * @param {string} [opts.timestamp]
+ * @param {object} [opts.config]
+ * @param {string} [opts.ledgerPath]
+ * @returns {{ ledgerPath: string, record: object }}
+ */
+export function emitSliceEnd(opts) {
+  const {
+    epicId,
+    sliceId,
+    outcome,
+    sliceIndex,
+    durationMs,
+    timestamp = new Date().toISOString(),
+    config,
+    ledgerPath,
+  } = opts ?? {};
+  assertEpicId(epicId);
+  assertSliceId(sliceId);
+  if (!VALID_OUTCOMES.has(outcome)) {
+    throw new Error(
+      `emit-slice-lifecycle: slice.end outcome "${outcome}" must be one of: ${[...VALID_OUTCOMES].join(', ')}`,
+    );
+  }
+
+  const payload = {
+    event: 'slice.end',
+    epicId,
+    sliceId,
+    ...(Number.isInteger(sliceIndex) ? { sliceIndex } : {}),
+    outcome,
+    ...(Number.isInteger(durationMs) ? { durationMs } : {}),
+    timestamp,
+  };
+  return appendSliceEvent('slice.end', payload, {
+    epicId,
+    timestamp,
+    config,
+    ledgerPath,
+  });
+}
+
+/**
+ * Append one `slice.heartbeat` record from inside a slice's implementation
+ * loop — the forward-progress signal the idle watchdog reads for the single
+ * long session.
+ *
+ * @param {object} opts
+ * @param {number} opts.epicId
+ * @param {string} opts.sliceId
+ * @param {string} [opts.phase='implementing']  init|implementing|closing|blocked|done.
+ * @param {string} [opts.timestamp]
+ * @param {string} [opts.operator]  Optional lease-owner handle; included only
+ *                                  when a non-empty string is supplied.
+ * @param {object} [opts.config]
+ * @param {string} [opts.ledgerPath]
+ * @returns {{ ledgerPath: string, record: object }}
+ */
+export function emitSliceHeartbeat(opts) {
+  const {
+    epicId,
+    sliceId,
+    phase = 'implementing',
+    timestamp = new Date().toISOString(),
+    operator,
+    config,
+    ledgerPath,
+  } = opts ?? {};
+  assertEpicId(epicId);
+  assertSliceId(sliceId);
+  if (!VALID_PHASES.has(phase)) {
+    throw new Error(
+      `emit-slice-lifecycle: slice.heartbeat phase "${phase}" must be one of: ${[...VALID_PHASES].join(', ')}`,
+    );
+  }
+  if (
+    operator !== undefined &&
+    (typeof operator !== 'string' || operator.length === 0)
+  ) {
+    throw new Error(
+      'emit-slice-lifecycle: operator, when supplied, must be a non-empty string',
+    );
+  }
+
+  const payload = {
+    event: 'slice.heartbeat',
+    epicId,
+    sliceId,
+    phase,
+    timestamp,
+    ...(operator !== undefined ? { operator } : {}),
+  };
+  return appendSliceEvent('slice.heartbeat', payload, {
+    epicId,
+    timestamp,
+    config,
+    ledgerPath,
+  });
+}