mandrel 1.88.0 → 1.90.0

package/.agents/scripts/lib/signals/schema.js

@@ -18,48 +18,50 @@
  * the codebase as of Epic #1181 (audit-snapshot 2026-05-11):
  *
  * Signals-writer `appendSignal` call sites:
- *   - `friction`       — quality-gate / runtime friction (check-crap.js,
- *                        check-maintainability.js, diagnose-friction.js,
- *                        post-merge-pipeline.js, progress-reporter.js,
- *                        auto-refresh-runner.js)
- *   - `dispatched`     — (no live emitter; retained pending Story #3908 sweep)
+ *   - `friction`       — quality-gate / runtime friction (diagnose-friction.js,
+ *                        lib/gates/friction.js, auto-refresh-runner.js,
+ *                        worktree-reap.js, lifecycle-emit.js)
+ *   - `acceptance-eval` — acceptance-eval.js per-criterion terminus signal.
  *   - `wave-start` / `wave-complete` — `lib/wave-runner/tick.js` (read by
  *                        perf-aggregator's `waveParallelism` report;
  *                        `wave-start` also anchors span-tree Story spans)
- *   - `wave-end`       — span-tree pairing anchor (no live emitter after the
- *                        Epic #2646 listener deletion; retained for span-tree)
- *   - `state-transition` — orchestration/ticketing.js
+ *   - `wave-end`       — span-tree pairing anchor (retained for span-tree)
+ *   - `state-transition` — notification-derived window anchor read by the
+ *                        waveParallelism bucketer.
  *
- * Story #3909 retired the write-only wave kinds with no consumer (`wave-tick`,
- * `epic-complete`) — they duplicated the checkpoint + `epic-run-progress`
- * rollup and nothing read them back.
+ * The `dispatched` kind was deleted in the Epic #4406 signal-contract
+ * cutover — it had no live emitter and no consumer.
  *
  * Signals-writer `appendTrace` call sites (traces.ndjson sibling, but
  * sharing the same envelope shape — `tool-trace-hook.js`):
  *   - `trace`          — per-tool-call timing record
  *
- * Aggregator-consumed kinds (perf-aggregator.js scans these — emitters
- * for `hotspot`, `rework`, `churn`, `idle`, `retry` are future Epic #1030
- * detector Stories that the aggregator was built to receive; the schema
- * pins the names so emitters land on a known shape):
+ * Detector-emitted / aggregator-consumed kinds (`rework`, `retry` are
+ * emitted by `lib/signals/detectors/*`; `hotspot`, `churn`, `idle` remain
+ * pinned in the enum for the aggregator's kind-count rollup even though no
+ * live detector emits them):
  *   - `hotspot`, `rework`, `churn`, `idle`, `retry`
  *
- * ## Common envelope
+ * ## Common envelope (canonical — Epic #4406 / Story #4413)
  *
  * Every signal MUST carry at minimum:
- *   - `ts`     — ISO-8601 timestamp string (writers historically used
- *                `timestamp:` instead; both keys are accepted by the
- *                guards below for backward-compat — the migration to
- *                `ts:` lands in a follow-on Story).
- *   - `epic`   — integer Epic ID (writers historically used `epicId:`;
- *                same backward-compat note).
+ *   - `ts`     — ISO-8601 timestamp string. The single canonical
+ *                timestamp key; the legacy `timestamp:` alias was deleted
+ *                from every writer and this guard in the same PR.
  *   - `kind`   — one of `EVENT_KINDS`.
  *
+ * Scoped signals additionally carry:
+ *   - `epicId` — integer Epic ID (or `null` for standalone-Story
+ *                friction). The single canonical epic-id key; the legacy
+ *                `epic:` alias was deleted.
+ *
  * Optional but commonly carried:
- *   - `story` / `storyId`  — integer Story ID
- *   - `task` / `taskId`    — integer Task ID (nullable)
- *   - `source`             — `{ tool: string }`
- *   - `details`            — kind-specific payload (object or string)
+ *   - `storyId`  — integer Story ID
+ *   - `taskId`   — integer Task ID (nullable)
+ *   - `emitter`  — `{ tool: string, command?: string }` provenance
+ *   - `source`   — `"framework" | "consumer"` classifier tag
+ *   - `category` — top-level friction category string
+ *   - `details`  — kind-specific payload (always an object)
  *
  * @module lib/signals/schema
  */
@@ -77,7 +79,6 @@ import { isPositiveInt } from './detectors/common.js';
 export const EVENT_KINDS = Object.freeze({
   FRICTION: 'friction',
   TRACE: 'trace',
-  DISPATCHED: 'dispatched',
   // Wave-window forensics signals: `wave-start` / `wave-end` anchor the
   // span-tree's Story spans, and the perf-aggregator brackets each wave's
   // wall-clock from `wave-start` → `wave-complete` (the `waveParallelism`
@@ -101,6 +102,13 @@ export const EVENT_KINDS = Object.freeze({
   // the retro and /plan Phase 0 feedback fetch can see acceptance
   // churn alongside friction/hotspot data.
   ACCEPTANCE_EVAL: 'acceptance-eval',
+  // Forensic breadcrumb appended to the per-Epic stream by the notify
+  // dispatcher (lib/orchestration/lifecycle/listeners/notify-dispatcher.js)
+  // when a lifecycle event maps to a webhook notification — the resume
+  // suite reads it back to prove a dispatch survived a crash window without
+  // duplicating. Enumerated so the write-time validator (Story #4413) does
+  // not drop it; it is a deliberate write, not malformed data.
+  NOTIFICATION_EMITTED: 'notification.emitted',
 });
 
 /**
@@ -117,20 +125,17 @@ export const EVENT_KIND_VALUES = Object.freeze(
  * spread string literals across the module graph.
  */
 export const FIELDS = Object.freeze({
-  // Envelope (canonical names — migration to these is in flight)
+  // Canonical envelope keys — there is exactly one key per concept. The
+  // legacy `timestamp` / `epic` / `story` / `task` aliases were deleted in
+  // the Epic #4406 signal-contract cutover; no reader tolerates them.
   TS: 'ts',
-  EPIC: 'epic',
-  STORY: 'story',
-  TASK: 'task',
-  KIND: 'kind',
-
-  // Legacy envelope aliases still emitted by some writers
-  TIMESTAMP: 'timestamp',
   EPIC_ID: 'epicId',
   STORY_ID: 'storyId',
   TASK_ID: 'taskId',
+  KIND: 'kind',
 
   // Common payload fields
+  EMITTER: 'emitter',
   SOURCE: 'source',
   DETAILS: 'details',
   CATEGORY: 'category',
@@ -150,8 +155,9 @@ function isTimestamp(v) {
 }
 
 /**
- * Common envelope guard: every signal MUST carry `ts` (or legacy
- * `timestamp`), `epic` (or legacy `epicId`), and a recognised `kind`.
+ * Common envelope guard: every signal MUST carry `ts`, `epicId`, and a
+ * recognised `kind`. Canonical keys only — the legacy `timestamp` / `epic`
+ * aliases were deleted in the Epic #4406 cutover.
  *
  * Returns true when the envelope is well-formed. Used by `lib/signals/read`
  * to discard malformed lines before yielding them to the consumer.
@@ -164,16 +170,24 @@ export function hasCommonEnvelope(evt) {
   if (typeof evt.kind !== 'string' || !EVENT_KIND_VALUES.has(evt.kind)) {
     return false;
   }
-  const ts = evt.ts ?? evt.timestamp;
-  if (!isTimestamp(ts)) return false;
-  const epic = evt.epic ?? evt.epicId;
-  if (!isPositiveInt(epic)) return false;
+  if (!isTimestamp(evt.ts)) return false;
+  // The canonical `epicId` key MUST be present — a record carrying only the
+  // legacy `epic` alias is rejected (the cutover deleted that alias). Its
+  // value is nullable by contract: standalone-Story friction carries
+  // `epicId: null` (see signal-event.schema.json, where epicId is
+  // `["integer","null"]`). So accept an explicit null, reject a missing key
+  // or a present-but-non-positive-int value.
+  if (!Object.hasOwn(evt, 'epicId')) return false;
+  if (evt.epicId !== null && !isPositiveInt(evt.epicId)) return false;
   return true;
 }
 
 /**
  * Generic per-kind guard. Returns true when the envelope is well-formed
- * AND (when `kind` is supplied) the event's `kind` matches.
+ * AND (when `kind` is supplied) the event's `kind` matches. The full
+ * canonical-shape check lives in the AJV validator compiled from
+ * `signal-event.schema.json` (see `lib/observability/signal-validator.js`);
+ * this predicate is the cheap envelope gate the streaming reader uses.
  *
  * @param {unknown} evt
  * @param {string} [kind] — optional kind to match (one of `EVENT_KINDS`).
@@ -184,42 +198,3 @@ export function isValidSignal(evt, kind) {
   if (kind != null && evt.kind !== kind) return false;
   return true;
 }
-
-/**
- * Per-kind shape guards. Each entry asserts the envelope plus any
- * required per-kind fields. Unknown kinds fall back to the envelope
- * check.
- *
- * The guards are intentionally lax — they reject records that are
- * obviously malformed (missing `kind`, missing `ts`, missing `epic`),
- * not records with extra fields or future schema extensions. The
- * aggregator (perf-aggregator.js) carries its own per-kind narrowing.
- *
- * @type {Readonly<Record<string, (evt: unknown) => boolean>>}
- */
-export const GUARDS = Object.freeze({
-  [EVENT_KINDS.FRICTION]: (evt) => {
-    if (!isValidSignal(evt, EVENT_KINDS.FRICTION)) return false;
-    // friction signals commonly carry a `category` field, but some
-    // writers (early in the migration) omit it. We accept both.
-    return true;
-  },
-  [EVENT_KINDS.TRACE]: (evt) => isValidSignal(evt, EVENT_KINDS.TRACE),
-  [EVENT_KINDS.DISPATCHED]: (evt) => isValidSignal(evt, EVENT_KINDS.DISPATCHED),
-  [EVENT_KINDS.WAVE_START]: (evt) => isValidSignal(evt, EVENT_KINDS.WAVE_START),
-  [EVENT_KINDS.WAVE_END]: (evt) => isValidSignal(evt, EVENT_KINDS.WAVE_END),
-  [EVENT_KINDS.WAVE_TICK]: (evt) => isValidSignal(evt, EVENT_KINDS.WAVE_TICK),
-  [EVENT_KINDS.WAVE_COMPLETE]: (evt) =>
-    isValidSignal(evt, EVENT_KINDS.WAVE_COMPLETE),
-  [EVENT_KINDS.EPIC_COMPLETE]: (evt) =>
-    isValidSignal(evt, EVENT_KINDS.EPIC_COMPLETE),
-  [EVENT_KINDS.STATE_TRANSITION]: (evt) =>
-    isValidSignal(evt, EVENT_KINDS.STATE_TRANSITION),
-  [EVENT_KINDS.HOTSPOT]: (evt) => isValidSignal(evt, EVENT_KINDS.HOTSPOT),
-  [EVENT_KINDS.REWORK]: (evt) => isValidSignal(evt, EVENT_KINDS.REWORK),
-  [EVENT_KINDS.CHURN]: (evt) => isValidSignal(evt, EVENT_KINDS.CHURN),
-  [EVENT_KINDS.IDLE]: (evt) => isValidSignal(evt, EVENT_KINDS.IDLE),
-  [EVENT_KINDS.RETRY]: (evt) => isValidSignal(evt, EVENT_KINDS.RETRY),
-  [EVENT_KINDS.ACCEPTANCE_EVAL]: (evt) =>
-    isValidSignal(evt, EVENT_KINDS.ACCEPTANCE_EVAL),
-});

package/.agents/scripts/lib/signals/span-tree.js

@@ -51,20 +51,21 @@
  */
 
 function tsOf(evt) {
-  // Schema accepts both `ts` (canonical) and `timestamp` (legacy).
-  return evt?.ts ?? evt?.timestamp ?? null;
+  // Canonical envelope only (Epic #4406) — the legacy `timestamp` alias
+  // was deleted from every writer in the same PR.
+  return evt?.ts ?? null;
 }
 
 function epicOf(evt) {
-  return evt?.epic ?? evt?.epicId ?? null;
+  return evt?.epicId ?? null;
 }
 
 function storyOf(evt) {
-  return evt?.story ?? evt?.storyId ?? null;
+  return evt?.storyId ?? null;
 }
 
 function taskOf(evt) {
-  return evt?.task ?? evt?.taskId ?? null;
+  return evt?.taskId ?? null;
 }
 
 /**

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

@@ -193,6 +193,7 @@ export async function loadBodyTemplate(projectRoot) {
  *   bodyTemplate: string,
  *   duplicateCandidates: Array<object>,
  *   techStack?: string|null,
+ *   corpusContext?: { docsDigest: string|null, relevantSections: Array<object> }|null,
  *   maxResults?: number,
  * }} opts
  */
@@ -203,6 +204,7 @@ export function buildContextEnvelope({
   bodyTemplate,
   duplicateCandidates,
   techStack = null,
+  corpusContext = null,
   maxResults = DEFAULT_DUPLICATE_MAX_RESULTS,
 }) {
   return {
@@ -218,6 +220,7 @@ export function buildContextEnvelope({
       candidates: duplicateCandidates,
     },
     techStack,
+    corpusContext,
     deliverContract: {
       workflow: '.agents/workflows/helpers/single-story-deliver.md',
       requiredLabels: ['type::story', `persona::${persona}`],

package/.agents/scripts/lib/wave-runner/tick.js

@@ -425,7 +425,13 @@ export function planTick(state, records, inFlight) {
       inFlight.length === 0
     ) {
       signals.push({
+        // `index` is what the perf-aggregator's `bucketWaves` keys on to
+        // bracket a wave's wall-clock (Epic #4406 / Story #4413). Without
+        // it every wave-start collapsed to NaN and the waveParallelism
+        // table rendered structurally empty. The continuous ready-set
+        // scheduler runs a single logical wave, so `index: 0`.
         kind: 'wave-start',
+        index: 0,
         stories: records.map((s) => ({ id: s.id, title: s.title })),
       });
     }
@@ -443,7 +449,7 @@ export function planTick(state, records, inFlight) {
     nextAction = { kind: 'observe', waitingOn };
   } else if (allDone) {
     // Every Story is done and nothing is in flight: the run is complete.
-    signals.push({ kind: 'wave-complete' });
+    signals.push({ kind: 'wave-complete', index: 0 });
     nextAction = { kind: 'epic-complete' };
   } else {
     // Ready set empty, nothing in flight, but not all Stories are done — a
@@ -739,7 +745,9 @@ function defaultSignalEmit(epicId, ctx) {
   return async (signal) => {
     await appendEpicSignal({
       epicId,
-      signal: { ts: new Date().toISOString(), epic: epicId, ...signal },
+      // Canonical envelope (Epic #4406 / Story #4413): the single
+      // `epicId` key — the legacy `epic` alias is gone.
+      signal: { ts: new Date().toISOString(), epicId, ...signal },
       config: ctx?.config,
     });
   };

package/.agents/scripts/lifecycle-emit.js

@@ -130,14 +130,27 @@ export function parseArgv(argv) {
 }
 
 /**
- * Build the bus emit payload from parsed argv. `event` is consumed.
- * `--epic` is mapped to `epicId` (integer). All other flags are
- * mapped from kebab-case to camelCase with light value coercion.
+ * Argv keys that are runtime OPTIONS consumed by `main()` /
+ * `runLifecycleEmit()` directly rather than forwarded into the emitted
+ * bus payload. `--headless` (Story #4427) is the first member: every
+ * lifecycle event schema declares `additionalProperties: false`, so a
+ * flag that selects delivery-run behavior (rather than describing the
+ * event itself) would fail schema validation if it leaked into the
+ * payload.
+ */
+const RUNTIME_OPTION_KEYS = Object.freeze(['event', 'headless']);
+
+/**
+ * Build the bus emit payload from parsed argv. `event` and `headless`
+ * (see `RUNTIME_OPTION_KEYS`) are consumed as runtime options, not
+ * payload fields. `--epic` is mapped to `epicId` (integer). All other
+ * flags are mapped from kebab-case to camelCase with light value
+ * coercion.
  */
 export function buildPayload(parsed) {
   const payload = {};
   for (const [key, raw] of Object.entries(parsed)) {
-    if (key === 'event') continue;
+    if (RUNTIME_OPTION_KEYS.includes(key)) continue;
     if (key === 'epic') {
       const n = Number.parseInt(raw, 10);
       if (!Number.isInteger(n) || n < 1) {
@@ -261,11 +274,16 @@ export async function emitBlockedSignal({
       config,
       signal: {
         kind: 'friction',
+        ts: new Date().toISOString(),
+        epicId,
+        category: 'lifecycle-listener-failure',
+        emitter: { tool: 'lifecycle-emit.js' },
         severity: 'high',
         event,
-        message: `lifecycle-emit: ${event} produced failed listener classification(s): ${reasons}`,
-        outcomes: failedOutcomes,
-        timestamp: new Date().toISOString(),
+        details: {
+          message: `lifecycle-emit: ${event} produced failed listener classification(s): ${reasons}`,
+          outcomes: failedOutcomes,
+        },
       },
     });
   } catch (err) {
@@ -321,6 +339,11 @@ export async function emitBlockedSignal({
  *   alongside an injected `bus` (when the caller owns listener wiring) —
  *   lets a test inject a bus + a chain carrying a `failed`-classifying
  *   listener to exercise the non-zero-exit path without the real roster.
+ * @param {boolean} [opts.headless] Explicit must-land signal (Story
+ *   #4427), forwarded to `buildDefaultListenerChain({ headless })` (and
+ *   from there to `MergeWatcher`) when this call constructs the default
+ *   chain. Defaults to `false` — attended-mode behavior is unchanged.
+ *   Ignored when the caller injects its own `bus`/`chain`.
  *
  * @returns {Promise<{ event: string, payload: object, seqId: number,
  *   outcomes: Array<object>, failed: boolean }>} The `outcomes[]` array
@@ -340,6 +363,7 @@ export async function runLifecycleEmit({
   config,
   emitBlockedSignalFn = emitBlockedSignal,
   chain: injectedChain,
+  headless = false,
 } = {}) {
   if (typeof event !== 'string' || event.length === 0) {
     throw new Error('lifecycle-emit: --event is required');
@@ -404,6 +428,7 @@ export async function runLifecycleEmit({
       checkpointer: resolvedCheckpointer,
       config: resolvedConfig,
       logger,
+      headless,
     });
   }
   const { seqId } = await targetBus.emit(event, payload ?? {});
@@ -464,7 +489,13 @@ async function main() {
   }
   const event = parsed.event;
   const payload = buildPayload(parsed);
-  const out = await runLifecycleEmit({ event, payload });
+  // `--headless true` is a runtime option (Story #4427), not a payload
+  // field — see RUNTIME_OPTION_KEYS. Threaded explicitly through
+  // runLifecycleEmit → buildDefaultListenerChain → MergeWatcher so the
+  // epic-path must-land terminal step reads a caller-supplied input
+  // rather than an ambient global.
+  const headless = parsed.headless === 'true';
+  const out = await runLifecycleEmit({ event, payload, headless });
   process.stdout.write(`${JSON.stringify(out)}\n`);
   // Exit non-zero when any listener classification came back `failed` so
   // the workflow's "re-run on non-zero" loop closes the partial-finalize

package/.agents/scripts/providers/github/issues.js

@@ -150,6 +150,14 @@ export class IssuesGateway {
   /**
    * List Epic-typed issues. Filter shape preserved from the old code.
    *
+   * `filters.pageCap` / `filters.perPage` pass through to `paginateRest`
+   * so a caller that only needs a bounded shortlist (e.g. the
+   * standalone-Story corpus lookup in `planning-corpus.js`, which ranks
+   * candidates down to a top-5 shortlist) can cap the scan instead of
+   * inheriting the default 50-page / 5000-item ceiling. Omitted, both
+   * fall back to `paginateRest`'s own defaults — unchanged behavior for
+   * existing callers (e.g. `duplicate-search.js`).
+   *
    * @field-manifest /repos/{owner}/{repo}/issues?labels=type::epic: number,
    *                 title, labels, state, state_reason, pull_request
    */
@@ -160,7 +168,10 @@ export class IssuesGateway {
       labels: TYPE_LABELS.EPIC,
     });
     const endpoint = `/repos/${this.owner}/${this.repo}/issues?${params}`;
-    const issues = await paginateRest(this._gh, endpoint);
+    const issues = await paginateRest(this._gh, endpoint, {
+      pageCap: filters.pageCap,
+      perPage: filters.perPage,
+    });
     return issues
       .filter((issue) => !issue.pull_request)
       .map(issueToEpicListItem);

package/.agents/scripts/resolve-doc-tiers.js

@@ -0,0 +1,83 @@
+/**
+ * CLI: resolve the repository's documentation read-tiers (Story #4438).
+ *
+ * Thin wrapper over `lib/doc-tiers.js#resolveDocTiers` that prints the tier
+ * map — `{ tiers: { alwaysLoaded, mandatoryRead, digestVisible, onDemand } }`,
+ * every entry `{ path, bytes }` — as JSON. Consumed by the `audit-documentation`
+ * lens (read-tier severity weighting), the `check-context-budget.js` ratchet,
+ * and operators inspecting the always-loaded closure.
+ *
+ * Flags:
+ *   --json   emit the tier map as JSON to stdout (default rendering is also
+ *            JSON; the flag is accepted for parity with the sibling ratchets
+ *            and future non-JSON renderings).
+ *   --root <path>  resolve tiers against an explicit repo root (default: the
+ *                  resolved PROJECT_ROOT).
+ *
+ * Exit code is always 0 on success — this is a reporter, not a gate.
+ */
+
+import process from 'node:process';
+import { runAsCli } from './lib/cli-utils.js';
+import { PROJECT_ROOT, resolveConfig } from './lib/config-resolver.js';
+import { resolveDocTiers } from './lib/doc-tiers.js';
+
+/**
+ * Parse argv for `--root <path>` and `--json`.
+ *
+ * @param {string[]} argv
+ * @returns {{ rootPath: string | null, json: boolean }}
+ */
+export function parseArgv(argv = []) {
+  let rootPath = null;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--root') {
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        rootPath = next;
+        i += 1;
+      }
+    } else if (a === '--json') {
+      json = true;
+    }
+  }
+  return { rootPath, json };
+}
+
+/**
+ * Top-level CLI entry. Exported so tests can drive it against a fixture root
+ * with an injected sink and config.
+ *
+ * @param {{
+ *   argv?: string[],
+ *   config?: object,
+ *   root?: string,
+ *   stdout?: { write: (s: string) => void },
+ * }} [opts]
+ * @returns {Promise<number>} always 0
+ */
+export async function runCli({
+  argv = process.argv.slice(2),
+  config,
+  root,
+  stdout = process.stdout,
+} = {}) {
+  const { rootPath } = parseArgv(argv);
+  const resolvedConfig = config ?? resolveConfig();
+  const resolvedRoot = root ?? rootPath ?? PROJECT_ROOT;
+  const result = resolveDocTiers(resolvedConfig, { root: resolvedRoot });
+  stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return 0;
+}
+
+async function main() {
+  return runCli();
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'resolve-doc-tiers',
+  propagateExitCode: true,
+  errorPrefix: '[resolve-doc-tiers] ❌ Fatal error',
+});

package/.agents/scripts/retro-run.js

@@ -37,6 +37,46 @@ import { createLedgerWriter } from './lib/orchestration/lifecycle/ledger-writer.
 import { runRetro } from './lib/orchestration/retro-runner.js';
 import { createProvider } from './lib/provider-factory.js';
 
+/**
+ * Pure: resolve the framework/consumer repo slugs (`"<owner>/<repo>"`)
+ * from a resolved config's `github` block, for threading into the retro's
+ * routed-proposal composer.
+ *
+ * - `consumerRepo` is the project's OWN repo (`github.owner/github.repo`).
+ *   It has **no** silent fallback: when `github.owner` / `github.repo` are
+ *   absent the slug is `''`, which `gatherRetroSignals` treats as "disable
+ *   the consumer pane loudly" rather than routing consumer-tagged friction
+ *   at the framework mirror (Story #4417).
+ * - `frameworkRepo` is the distinct framework mirror
+ *   (`github.frameworkRepo.{owner,repo}`) when configured, otherwise `''`
+ *   — `gatherRetroSignals` then falls back to its `DEFAULT_FRAMEWORK_REPO`
+ *   constant (a stable, known default is legitimate for the framework).
+ *
+ * Exported for tests.
+ *
+ * @param {object} [config]
+ * @returns {{ frameworkRepo: string, consumerRepo: string }}
+ */
+export function resolveRetroRepos(config) {
+  const gh = config?.github ?? {};
+  const consumerRepo =
+    typeof gh.owner === 'string' &&
+    gh.owner.length > 0 &&
+    typeof gh.repo === 'string' &&
+    gh.repo.length > 0
+      ? `${gh.owner}/${gh.repo}`
+      : '';
+  const fw = gh.frameworkRepo ?? {};
+  const frameworkRepo =
+    typeof fw.owner === 'string' &&
+    fw.owner.length > 0 &&
+    typeof fw.repo === 'string' &&
+    fw.repo.length > 0
+      ? `${fw.owner}/${fw.repo}`
+      : '';
+  return { frameworkRepo, consumerRepo };
+}
+
 const HELP = `Usage: node .agents/scripts/retro-run.js --epic <epicId> [--full-retro]
 
 Composes and posts the Epic retro structured comment for Epic #<epicId>,
@@ -125,11 +165,22 @@ export async function runRetroCli({
     : createLedgerWriter({ epicId, tempRoot });
   ledger.register(bus);
 
+  // Story #4417 — thread the framework/consumer repo slugs resolved from
+  // `config.github` into the retro so the routed-proposal composer files
+  // consumer-tagged friction at the project's own repo (not the framework
+  // mirror), and disables the consumer pane loudly when unresolved.
+  const { frameworkRepo, consumerRepo } = resolveRetroRepos(config);
+
   const result = await runRetroFn({
     epicId,
     provider,
     bus,
     forceFull: fullRetro,
+    frameworkRepo,
+    consumerRepo,
+    // Story #4418 — thread the resolved config so the retro auto-filer can
+    // read the `delivery.feedbackLoop.retroProposals` toggle.
+    config,
     logger,
   });
 

package/.agents/scripts/signals-view.js

@@ -161,7 +161,7 @@ function formatDuration(ms) {
 }
 
 function describeEvent(evt) {
-  const ts = evt?.ts ?? evt?.timestamp ?? '(no ts)';
+  const ts = evt?.ts ?? '(no ts)';
   const kind = evt?.kind ?? '(no kind)';
   const phase = evt?.phase ? ` phase=${evt.phase}` : '';
   const category = evt?.category ? ` category=${evt.category}` : '';

package/.agents/scripts/single-story-close.js

@@ -23,6 +23,14 @@
  *                          the post-merge confirmation step,
  *                          `single-story-confirm-merge.js`)
  *   8. worktree-reap     — drop the per-Story worktree
+ *   9. confirm-merge      — Story #4428, headless-only (`--wait-merge`):
+ *                          poll the just-armed PR to merge confirmation
+ *                          (reusing `confirmStoryMerged`) or terminate
+ *                          `agent::blocked` with a classified
+ *                          `merge.unlanded` lifecycle event. Attended runs
+ *                          (the default, no `--wait-merge`) skip this
+ *                          phase entirely and keep resting at
+ *                          `agent::closing`, exactly as before.
  *
  * Existing tests import the re-exported helpers
  * (`runSingleStoryClose`, `ensurePullRequest`, `parsePrNumber`,
@@ -33,8 +41,19 @@
  *   node single-story-close.js --story <STORY_ID> [--cwd <main-repo>]
  *                              [--skip-validation] [--skip-sync]
  *                              [--no-auto-merge] [--no-full-scope-crap]
+ *                              [--wait-merge | --no-wait-merge]
  *
- * Exit codes: 0 ok, 1 error.
+ * `--wait-merge` is the headless must-land signal (Story #4428, Epic
+ * #4425): the invoking surface (a headless `/single-story-deliver` run, a
+ * CI-driven wrapper, or `/deliver`'s standalone multi-Story fan-out) opts
+ * in explicitly — attended runs never pass it, so the default exit shape
+ * (rest at `agent::closing`, issue OPEN) is unchanged. `--no-wait-merge` is
+ * the explicit opt-out that always wins over `--wait-merge`, for a caller
+ * that wants to manage merge confirmation externally even in an otherwise
+ * headless context.
+ *
+ * Exit codes: 0 ok, 1 error (including a headless `--wait-merge` run that
+ * gave up without a confirmed merge — see phase 9 above).
  *
  * @see .agents/workflows/helpers/single-story-deliver.md
  */