mandrel 2.9.0 → 2.10.0

package/.agents/scripts/lib/audit-suite/selector.js

@@ -702,7 +702,7 @@ const SOURCE_CODE_EXTENSIONS = Object.freeze([
 const TEST_FILE_RE = new RegExp(String.raw`\.(test|spec)\.[cm]?[jt]sx?$`);
 // biome-ignore lint/complexity/useRegexLiterals: constructor form keeps the MI walker able to score this module.
 const TEST_DIR_RE = new RegExp(
-  String.raw`(^|/)(tests?|__tests__|spec|e2e|__mocks__)(/|$)`,
+  '(^|/)(tests?|__tests__|spec|e2e|__mocks__)(/|$)',
 );
 // biome-ignore lint/complexity/useRegexLiterals: constructor form keeps the MI walker able to score this module.
 const CODE_EXT_RE = new RegExp(String.raw`\.[cm]?[jt]sx?$`);

package/.agents/scripts/lib/config/temp-paths.js

@@ -52,6 +52,8 @@
  */
 
 import { execFileSync } from 'node:child_process';
+import { mkdtempSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 
 /**
@@ -114,6 +116,81 @@ export function _clearMainCheckoutRootCache() {
   _mainCheckoutRootCache.clear();
 }
 
+/**
+ * Environment variable naming an absolute per-process scratch tempRoot that
+ * every stream writer must land in during a test run (Story #4696).
+ *
+ * The shared test bootstrap (`lib/test-env.js`) sets this to a fresh
+ * `os.tmpdir()` directory before spawning the test runner, so any test that
+ * reaches a writer (`signals-writer`, the lifecycle `LedgerWriter`, etc.)
+ * *without* explicitly injecting an absolute tempRoot still resolves under
+ * scratch instead of the repo's real `temp/` tree. This is the single
+ * injection seam: because every path helper funnels a relative root through
+ * `anchorTempRoot`, one redirect here covers all writers regardless of how
+ * each one resolved its root.
+ */
+export const TEST_TEMP_ROOT_ENV = 'MANDREL_TEST_TEMP_ROOT';
+
+/**
+ * Resolve the absolute scratch tempRoot override, or `null` when none is
+ * configured. Only an **absolute** value is honoured — a relative override
+ * would re-anchor against the repo tree and defeat the isolation, so it is
+ * ignored (treated as unset). Module-internal: the behaviour is exercised
+ * through `anchorTempRoot`, so it is deliberately not exported (keeps the
+ * public seam to `anchorTempRoot` + `TEST_TEMP_ROOT_ENV`).
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {string|null}
+ */
+function testScratchTempRoot(env = process.env) {
+  const override = env?.[TEST_TEMP_ROOT_ENV];
+  return typeof override === 'string' &&
+    override.length > 0 &&
+    path.isAbsolute(override)
+    ? override
+    : null;
+}
+
+/**
+ * Environment variable that opts a test-context process back into the real
+ * `temp/` tree (Story #4711). The `anchorTempRoot` test-context fallback
+ * refuses to anchor a relative root into the repo's telemetry tree when the
+ * process is a node:test context; a test that genuinely needs the real tree
+ * sets this to `'1'` on its own spawn — an explicit, greppable opt-out
+ * instead of a silent bypass.
+ */
+export const TEST_ALLOW_REAL_TEMP_ENV = 'MANDREL_TEST_ALLOW_REAL_TEMP';
+
+/**
+ * Per-process memo for the lazily-created test-context scratch dir, so every
+ * relative-root resolution in one test process converges on a single scratch
+ * tree (mirrors the `_mainCheckoutRootCache` pattern above).
+ */
+let _testContextScratchDir = null;
+
+/**
+ * Test-only: clear the test-context scratch memo so a suite can exercise the
+ * lazy-arming branch repeatedly in one process.
+ */
+export function _clearTestContextScratchCache() {
+  _testContextScratchDir = null;
+}
+
+/**
+ * Is this process a node:test context? True when the env carries
+ * `NODE_TEST_CONTEXT` (set by the node:test runner on every spawned test
+ * child, regardless of how the runner itself was launched) or when the
+ * process was started with the `--test` flag (a direct `node --test <file>`
+ * runner process, or in-process isolation modes).
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string[]} execArgv
+ * @returns {boolean}
+ */
+function inNodeTestContext(env, execArgv) {
+  return Boolean(env?.NODE_TEST_CONTEXT) || execArgv.includes('--test');
+}
+
 /**
  * Anchor a resolved `tempRoot` to the main checkout root when it is a
  * relative path (Story #3900). Absolute roots are returned verbatim; a
@@ -123,11 +200,54 @@ export function _clearMainCheckoutRootCache() {
  * root is returned unchanged so behaviour degrades to the prior
  * cwd-relative semantics rather than throwing.
  *
+ * Test isolation (Story #4696): when the scratch override
+ * (`MANDREL_TEST_TEMP_ROOT`) is set, a relative root is joined onto the
+ * scratch dir instead of the main checkout root, so a writer that reaches
+ * the default (or any relative) root under the test bootstrap lands in
+ * scratch and never pollutes the repo's real `temp/` telemetry tree. An
+ * absolute root injected by a well-behaved test still bypasses the redirect
+ * verbatim.
+ *
+ * Process-level arming (Story #4711): the wrapper-armed override above only
+ * covers processes spawned by `run-tests.js` — a direct `node --test <file>`
+ * run used to bypass it and append fixture records to the real tree. When no
+ * override is armed but the process *is* a node:test context (see
+ * `inNodeTestContext`), a per-process scratch dir is created lazily and the
+ * relative root anchors there instead. The scratch dir is memoized and — for
+ * the real `process.env` — written back to `MANDREL_TEST_TEMP_ROOT` so child
+ * processes the test spawns inherit the same scratch tree. Escape hatch: a
+ * test that genuinely needs the real tree sets
+ * `MANDREL_TEST_ALLOW_REAL_TEMP=1` (`TEST_ALLOW_REAL_TEMP_ENV`) to restore
+ * main-checkout anchoring; the `check-test-temp-hygiene` guard remains the
+ * backstop either way.
+ *
  * @param {string} tempRoot
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @param {{ mkdtemp?: typeof mkdtempSync, execArgv?: string[] }} [deps]
+ *   Injectable for tests.
  * @returns {string}
  */
-export function anchorTempRoot(tempRoot) {
+export function anchorTempRoot(tempRoot, env = process.env, deps = {}) {
   if (path.isAbsolute(tempRoot)) return tempRoot;
+  const scratch = testScratchTempRoot(env);
+  if (scratch) return path.join(scratch, tempRoot);
+  const execArgv = deps.execArgv ?? process.execArgv;
+  if (
+    inNodeTestContext(env, execArgv) &&
+    env?.[TEST_ALLOW_REAL_TEMP_ENV] !== '1'
+  ) {
+    if (_testContextScratchDir === null) {
+      const mkdtemp = deps.mkdtemp ?? mkdtempSync;
+      _testContextScratchDir = mkdtemp(
+        path.join(os.tmpdir(), 'mandrel-test-temp-'),
+      );
+      if (env === process.env) {
+        // Children spawned by this test process inherit the same scratch.
+        process.env[TEST_TEMP_ROOT_ENV] = _testContextScratchDir;
+      }
+    }
+    return path.join(_testContextScratchDir, tempRoot);
+  }
   const root = mainCheckoutRoot();
   return root ? path.join(root, tempRoot) : tempRoot;
 }

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -160,10 +160,19 @@ const SIGNALS_SCHEMA = {
  * behind-the-base PR up to date before giving the branch up as unwinnable,
  * rather than waiting out the budget behind a base it could have merged.
  * All keys default in the consumer when omitted (30s / 300s / 3600s / 3).
+ *
+ * `mode` selects the close-time merge posture (Story #4698). Default `sync`
+ * keeps the in-close foreground wait unchanged. `async` caps the per-invocation
+ * wait to a short probe window (~60s: catches instant merges and instantly-red
+ * required checks) and then returns the resumable `pending` terminal, so a
+ * slow-CI consumer no longer burns ~5 minutes of the host tool slot on a merge
+ * that lands after the wait would have expired anyway — the worker launches the
+ * `pending` envelope's `nextCommand` in the background instead.
  */
 const MERGE_WATCH_SCHEMA = {
   type: 'object',
   properties: {
+    mode: { type: 'string', enum: ['sync', 'async'] },
     intervalSeconds: { type: 'integer', minimum: 1 },
     maxWaitSeconds: { type: 'integer', minimum: 1 },
     maxBudgetSeconds: { type: 'integer', minimum: 1 },
@@ -280,6 +289,26 @@ const ACCEPTANCE_EVAL_SCHEMA = {
   additionalProperties: false,
 };
 
+/**
+ * `delivery.review` — close-scope review tuning (Story #4699). `lensDiffFloor`
+ * is the changed-line floor below which the Story-scope local-lens pass skips
+ * lens materialization for a diff with zero sensitive-path hits (default 40
+ * via `lib/audit-suite/lens-diff-floor.js`; `0` disables the skip). The
+ * maker-blind code-review pass and all hard gates are untouched by the floor.
+ */
+const REVIEW_SCHEMA = {
+  type: 'object',
+  properties: {
+    lensDiffFloor: {
+      type: 'integer',
+      minimum: 0,
+      description:
+        'Changed-line floor for the close-scope lens walk (Story #4699). A diff strictly below this many changed lines (additions + deletions) with zero sensitive-path hits skips lens materialization and records the skip in the findings-yield ledger. Default 40; 0 disables the skip. Hard gates and the maker-blind code-review pass are unaffected.',
+    },
+  },
+  additionalProperties: false,
+};
+
 /**
  * `delivery.feedbackLoop` — opt-out toggles consumed by the Epic finalize
  * listener's auto-file graduators (`lib/feedback-loop/*-graduator.js`, read
@@ -335,6 +364,7 @@ export const DELIVERY_SCHEMA = {
     quality: QUALITY_SCHEMA,
     mergeWatch: MERGE_WATCH_SCHEMA,
     codeReview: CODE_REVIEW_SCHEMA,
+    review: REVIEW_SCHEMA,
     refactorStage: REFACTOR_STAGE_SCHEMA,
     acceptanceEval: ACCEPTANCE_EVAL_SCHEMA,
     feedbackLoop: FEEDBACK_LOOP_SCHEMA,

package/.agents/scripts/lib/config-settings-schema.js

@@ -299,7 +299,7 @@ const PLANNING_SCHEMA = {
           type: 'integer',
           minimum: 0,
           description:
-            'Seed prose word ceiling for the lite path. A seed above this many words is not trivial and takes the full path. Default 60.',
+            'Seed prose word ceiling for the lite path. A seed above this many words is not trivial and takes the full path. Default 150.',
         },
         maxArtifacts: {
           type: 'integer',

package/.agents/scripts/lib/observability/metrics-ledger.js

@@ -0,0 +1,217 @@
+/**
+ * metrics-ledger.js — the narrow shared metrics-ledger boundary (Story #4712).
+ *
+ * Owns the one append-tail implementation for the plan-metrics ledger:
+ * path resolution, serialization, lazy directory creation, size-capped
+ * rotation, and the append itself. Every ledger writer — the plan-domain
+ * appenders in `../orchestration/plan-metrics.js` and the close-domain
+ * findings-yield entry point below — routes through
+ * {@link appendLedgerRecord}, so the open→append→rotate→close tail exists
+ * exactly once and cannot drift between call sites.
+ *
+ * The findings-yield entry point (Story #4699) lives here rather than in
+ * the plan-domain module so the story-close review spine
+ * (`../orchestration/story-close/phases/review-core.js`) depends on this
+ * narrow shared ledger module instead of plan-domain internals.
+ *
+ * Wire contract (unchanged by the #4712 re-home): record shapes, file
+ * locations (`temp/run-<id>/plan-metrics.json` / the standalone stream),
+ * and the rotation threshold are exactly what `plan-metrics.js` shipped —
+ * readers (`readPlanMetrics` / `summarizePlanMetrics`) stay plan-side and
+ * key kinded records on `kind`, never on absent fields.
+ *
+ * Robustness contract (mirrors `signals-writer.js`):
+ *   - **No buffering.** Each append opens, writes one line, closes.
+ *   - **Rotation.** When an append would push the ledger past
+ *     `maxBytes`, the current file is renamed to `<name>.1` (replacing any
+ *     prior rollover) and the append starts a fresh ledger.
+ *   - **Best-effort at the entry points.** {@link appendLedgerRecord}
+ *     itself throws on fs failure; each public appender catches, warns via
+ *     `Logger`, and returns `false` so metric capture can never fail the
+ *     wrapped plan phase or Story close.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  anchorTempRoot,
+  runArtifactPath,
+  tempRootFrom,
+} from '../config/temp-paths.js';
+import { Logger } from '../Logger.js';
+
+export const PLAN_METRICS_BASENAME = 'plan-metrics.json';
+export const PLAN_METRICS_SCHEMA_VERSION = 1;
+
+/**
+ * Record kind for a per-close, per-lens findings-yield entry (Story #4699).
+ * One record per Story close whose review ran (or floor-skipped) at least
+ * one local lens:
+ *
+ * ```json
+ * { "v": 1, "kind": "findings-yield", "cli": "story-close-review",
+ *   "storyId": 4699, "epicId": null,
+ *   "lenses": [{ "lens": "audit-clean-code", "findings": 0,
+ *                "skippedByFloor": false }],
+ *   "diffFloor": { "skip": false, "reason": "at-or-above-floor",
+ *                  "floor": 40, "changedLineCount": 120 },
+ *   "at": "..." }
+ * ```
+ *
+ * The ledger only records — no roster behavior changes ride on it. Its
+ * purpose is evidentiary: a lens that stays at zero findings across N
+ * closes becomes droppable on measurement instead of assumption.
+ */
+const PLAN_METRICS_KIND_FINDINGS_YIELD = 'findings-yield';
+
+/**
+ * Rotation threshold. At ~200 bytes per record this is ~5000 invocations —
+ * far beyond any real plan run, so rotation only fires on pathological
+ * accumulation.
+ */
+export const MAX_LEDGER_BYTES = 1024 * 1024;
+
+/**
+ * Resolve the ledger path for an Epic (or the standalone stream when
+ * `epicId` is `null` — the `story-plan.js` / Epic-less healthcheck case).
+ *
+ * @param {number|null} epicId
+ * @param {object} [config] Resolved config (threads `project.paths.tempRoot`).
+ * @returns {string}
+ */
+export function planMetricsPath(epicId, config) {
+  if (epicId === null || epicId === undefined) {
+    return path.join(
+      anchorTempRoot(tempRootFrom(config)),
+      'standalone',
+      PLAN_METRICS_BASENAME,
+    );
+  }
+  return runArtifactPath(epicId, PLAN_METRICS_BASENAME, config);
+}
+
+/**
+ * Rotate the ledger when appending `incomingBytes` would exceed
+ * `maxBytes`. Single-generation rollover: `plan-metrics.json` →
+ * `plan-metrics.json.1` (any prior `.1` is replaced).
+ *
+ * @param {string} filePath
+ * @param {number} incomingBytes
+ * @param {number} maxBytes
+ * @returns {Promise<boolean>} true when a rotation happened.
+ */
+async function rotateIfNeeded(filePath, incomingBytes, maxBytes) {
+  let size = 0;
+  try {
+    size = (await fs.stat(filePath)).size;
+  } catch {
+    return false; // No existing ledger — nothing to rotate.
+  }
+  if (size + incomingBytes <= maxBytes) return false;
+  await fs.rename(filePath, `${filePath}.1`);
+  return true;
+}
+
+/**
+ * The single ledger append tail (Story #4712): serialize the record to one
+ * newline-terminated JSON line, create the ledger directory lazily, rotate
+ * when the byte cap would be exceeded, and append.
+ *
+ * Throws on any fs failure — the best-effort posture (warn + `false`,
+ * never throw) belongs to the public appenders that wrap this, because
+ * each labels its own failure mode.
+ *
+ * @param {object} record Fully-built ledger record (already validated).
+ * @param {{
+ *   epicId?: number|null,
+ *   config?: object,
+ *   maxBytes?: number,
+ * }} [opts] `maxBytes` is a test seam for the rotation threshold.
+ * @returns {Promise<void>}
+ */
+export async function appendLedgerRecord(record, opts = {}) {
+  const filePath = planMetricsPath(opts.epicId ?? null, opts.config);
+  const line = `${JSON.stringify(record)}\n`;
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await rotateIfNeeded(
+    filePath,
+    Buffer.byteLength(line),
+    opts.maxBytes ?? MAX_LEDGER_BYTES,
+  );
+  await fs.appendFile(filePath, line, 'utf8');
+}
+
+/**
+ * Append one findings-yield record (Story #4699). Called once per Story
+ * close by the review spine when the local-lens pass matched (or
+ * floor-skipped) at least one lens. Best-effort: returns `false` (after a
+ * `Logger.warn`) instead of throwing on any failure, so a ledger failure
+ * can never fail the close.
+ *
+ * @param {{
+ *   storyId: number,
+ *   lenses: Array<{ lens: string, findings?: number, skippedByFloor?: boolean }>,
+ *   cli?: string,
+ *   epicId?: number|null,
+ *   diffFloor?: object|null,
+ * }} entry
+ * @param {object} [config]
+ * @param {{ maxBytes?: number }} [opts] Test seam for the rotation threshold.
+ * @returns {Promise<boolean>} true when the line was written.
+ */
+export async function appendFindingsYield(entry, config, opts = {}) {
+  try {
+    if (!entry || typeof entry !== 'object') {
+      throw new TypeError('appendFindingsYield requires an entry object');
+    }
+    const storyId = Number(entry.storyId);
+    if (!Number.isInteger(storyId) || storyId <= 0) {
+      throw new TypeError(
+        'appendFindingsYield requires a positive integer entry.storyId',
+      );
+    }
+    if (!Array.isArray(entry.lenses) || entry.lenses.length === 0) {
+      throw new TypeError(
+        'appendFindingsYield requires a non-empty entry.lenses array',
+      );
+    }
+    const epicId = entry.epicId ?? null;
+    const record = {
+      v: PLAN_METRICS_SCHEMA_VERSION,
+      kind: PLAN_METRICS_KIND_FINDINGS_YIELD,
+      cli:
+        typeof entry.cli === 'string' && entry.cli.length > 0
+          ? entry.cli
+          : 'story-close-review',
+      storyId,
+      epicId,
+      lenses: entry.lenses
+        .filter((l) => l && typeof l.lens === 'string' && l.lens.length > 0)
+        .map((l) => ({
+          lens: l.lens,
+          findings:
+            typeof l.findings === 'number' && Number.isFinite(l.findings)
+              ? l.findings
+              : 0,
+          skippedByFloor: l.skippedByFloor === true,
+        })),
+      diffFloor:
+        entry.diffFloor && typeof entry.diffFloor === 'object'
+          ? entry.diffFloor
+          : null,
+      at: new Date().toISOString(),
+    };
+    await appendLedgerRecord(record, {
+      epicId,
+      config,
+      maxBytes: opts.maxBytes,
+    });
+    return true;
+  } catch (err) {
+    Logger.warn(
+      `[plan-metrics] findings-yield append failed (non-fatal): ${err?.message ?? err}`,
+    );
+    return false;
+  }
+}

package/.agents/scripts/lib/observability/runtime-friction.js

@@ -68,6 +68,13 @@ export const RUNTIME_FRICTION_CATEGORIES = Object.freeze({
   CLOSE_FAILED: 'close-failed',
   /** A bounded merge wait expired with the PR still in flight. */
   MERGE_WAIT_EXHAUSTED: 'merge-wait-exhausted',
+  /**
+   * A review/lens tool failed to *execute* (binary missing, unparseable
+   * output, materialization crash) — an operational degradation, not a code
+   * finding. Story #4699 routes these here so findings severity tiers
+   * reflect code findings only.
+   */
+  TOOL_DEGRADED: 'tool-degraded',
 });
 
 /** Cap on free-form reason text copied into a signal's `details`. */

package/.agents/scripts/lib/orchestration/complexity-gate.js

@@ -38,13 +38,31 @@
  * `planning.complexityGate` in `.agentrc.json`:
  *
  *   - `enabled`      (default `true`)  — `false` forces every seed to `full`.
- *   - `maxSeedWords` (default `60`)    — seed prose word ceiling for `lite`.
+ *   - `maxSeedWords` (default `150`)   — seed prose word ceiling for `lite`.
  *   - `maxArtifacts` (default `1`)     — enumerated-artifact ceiling for `lite`.
  *
  * Resolution clamps every field toward the conservative default: a malformed or
  * negative ceiling falls back to the framework default rather than widening the
  * lite path.
  *
+ * ## Planner downgrade + the persisted route marker (Story #4707)
+ *
+ * Seed word count is a poor complexity proxy: a well-written 70-word trivial
+ * seed is no less trivial than a terse 40-word one, which is why the ceiling
+ * sits at 150 rather than 60. Two adjacent surfaces live here with the gate so
+ * the whole lite-routing contract has one home:
+ *
+ *   - {@link applyPlannerDowngrade} — the planner may downgrade a `full`
+ *     verdict to `lite` **only** with a recorded reason. The deterministic
+ *     gate itself is unchanged (it still fails toward `full`); the downgrade
+ *     is an auditable model judgment layered on top, never a silent gate
+ *     change. Absent a non-empty reason the deterministic verdict stands.
+ *   - {@link resolveStoryDispatchMode} — the deliver-side reader of the
+ *     persisted {@link LITE_ROUTE_LABEL} marker. A lite-routed Story executes
+ *     inline in the deliver session (no story-worker or acceptance-critic
+ *     sub-agent boots); everything else dispatches as before. Model-side
+ *     fan-out only — never a deterministic close gate.
+ *
  * @typedef {'lite'|'full'} ComplexityRoute
  */
 
@@ -55,10 +73,21 @@
  */
 const DEFAULT_COMPLEXITY_GATE = Object.freeze({
   enabled: true,
-  maxSeedWords: 60,
+  maxSeedWords: 150,
   maxArtifacts: 1,
 });
 
+/**
+ * The persisted route marker for a lite-routed Story (Story #4707).
+ *
+ * Applied by plan-persist at create time and read by `/deliver` (via the
+ * resolver envelope's `stories[].labels`) through
+ * {@link resolveStoryDispatchMode}. A full-routed Story carries no marker —
+ * absence is the conservative default, so an unlabelled Story always takes
+ * the sub-agent dispatch path.
+ */
+export const LITE_ROUTE_LABEL = 'route::lite';
+
 /**
  * The non-negotiables the ceremony-lite path preserves. This is the
  * contract behind Story #4683 AC-2: collapsing ceremony never means dropping
@@ -205,3 +234,85 @@ export function buildComplexityRouteSignal({ seedText = '', config } = {}) {
     `trivial single-artifact scope (${wordCount} words ≤ ${threshold.maxSeedWords}, ${artifactCount} enumerated artifact(s) ≤ ${threshold.maxArtifacts}) — collapsed ceremony-lite path; non-negotiables preserved`,
   );
 }
+
+/**
+ * Apply an auditable planner downgrade to a `full` complexity verdict
+ * (Story #4707).
+ *
+ * The deterministic gate is conservative by construction, and seed word count
+ * is a poor complexity proxy — so the planner is allowed to judge a `full`
+ * verdict down to `lite`, but **only** with a recorded reason. The contract:
+ *
+ *   - No non-empty reason → the deterministic verdict stands, unchanged. A
+ *     downgrade without a reason is indistinguishable from a silent gate
+ *     change, which is exactly what this path must never be.
+ *   - A signal that is not a `full` verdict (already `lite`, or absent) is
+ *     returned unchanged — there is nothing to downgrade.
+ *   - Otherwise the returned signal routes `lite`, appends the reason to
+ *     `reasons`, and carries a frozen `downgraded: { from: 'full', reason }`
+ *     record so the judgment is ledgerable on plan state (plan-persist writes
+ *     it into every created Story's `story-plan-state` checkpoint).
+ *
+ * Pure and total: never mutates `signal`, never throws on malformed input.
+ * The gate itself ({@link buildComplexityRouteSignal}) is untouched — it
+ * still fails toward `full` on any doubt.
+ *
+ * @param {ReturnType<typeof buildComplexityRouteSignal>|null|undefined} signal
+ * @param {{ reason?: unknown }} [args]
+ * @returns {object|null|undefined} The (possibly downgraded) signal.
+ */
+export function applyPlannerDowngrade(signal, { reason } = {}) {
+  if (!signal || typeof signal !== 'object' || signal.route !== 'full') {
+    return signal;
+  }
+  const recorded = typeof reason === 'string' ? reason.trim() : '';
+  if (recorded === '') return signal;
+  return {
+    ...signal,
+    route: 'lite',
+    reasons: [
+      ...(Array.isArray(signal.reasons) ? signal.reasons : []),
+      `planner downgrade full → lite (recorded reason): ${recorded}`,
+    ],
+    downgraded: Object.freeze({ from: 'full', reason: recorded }),
+  };
+}
+
+/**
+ * Decide how `/deliver` executes a Story from its persisted route marker
+ * (Story #4707).
+ *
+ * Reads the labels the resolver envelope already carries. A Story labelled
+ * {@link LITE_ROUTE_LABEL} executes **inline** in the deliver session — no
+ * story-worker sub-agent boot and no fresh acceptance-critic sub-agent
+ * dispatch (sub-agent boots are the dominant deliver-phase token cost at
+ * trivial scope). Every other Story — including one with missing or
+ * malformed labels — dispatches as a sub-agent: absence of the marker is the
+ * conservative default, mirroring the gate's fail-toward-`full` posture.
+ *
+ * Inline execution removes model-side fan-out only. Every deterministic
+ * `single-story-close.js` gate (validation, security baseline, PR-to-`main`)
+ * runs unchanged regardless of mode — see {@link LITE_PATH_INVARIANTS}.
+ *
+ * @param {{ labels?: unknown }} [args]
+ * @returns {{ mode: 'inline'|'subagent', reasons: string[] }}
+ */
+export function resolveStoryDispatchMode({ labels } = {}) {
+  const list = Array.isArray(labels)
+    ? labels.filter((l) => typeof l === 'string')
+    : [];
+  if (list.includes(LITE_ROUTE_LABEL)) {
+    return {
+      mode: 'inline',
+      reasons: [
+        `Story carries the ${LITE_ROUTE_LABEL} route marker — execute deliver-story inline; no story-worker or acceptance-critic sub-agent dispatch (close gates unchanged)`,
+      ],
+    };
+  }
+  return {
+    mode: 'subagent',
+    reasons: [
+      `no ${LITE_ROUTE_LABEL} route marker — standard sub-agent dispatch`,
+    ],
+  };
+}