mandrel 2.64.0 → 2.66.0

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

@@ -3,23 +3,20 @@
  * maker-blind `runCodeReview` invocation out of any phase file.
  */
 
-import { countChangedLines } from '../../../audit-suite/index.js';
 import { gitSpawn } from '../../../git-utils.js';
-import { appendFindingsYield } from '../../../observability/metrics-ledger.js';
 import { computeChangeSet } from '../../change-set.js';
 import { runCodeReview } from '../../code-review.js';
-import { runLocalLensReview } from './local-lens-review.js';
 
 /**
- * Run the local-lens pass and `runCodeReview` over one change set and return
- * the review result. Throws propagate; the caller picks the advisory posture.
- * Review depth is derived by `runCodeReview` from the changed files and is
- * input-only — it never alters the output envelope.
+ * Run `runCodeReview` over one change set and return the review result.
+ * Throws propagate; the caller picks the advisory posture. Review depth is
+ * derived by `runCodeReview` from the changed files and is input-only — it
+ * never alters the output envelope.
  *
- * The diff is enumerated exactly once here and injected into both consumers,
- * so lens roster and review depth agree on what changed even if a commit
- * lands in between. An unenumerable diff injects `null` ("already tried"),
- * which both consumers honour without re-spawning git.
+ * The diff is enumerated exactly once here and injected into the review, so
+ * review depth scores the same file set the change set names even if a
+ * commit lands in between. An unenumerable diff injects `null` ("already
+ * tried"), which the review honours without re-spawning git.
  *
  * @param {{
  *   storyId: number|string,
@@ -32,12 +29,9 @@ import { runLocalLensReview } from './local-lens-review.js';
  *   gitSpawnFn?: import('../../change-set.js').GitSpawnFn,
  *   computeChangeSetFn?: typeof computeChangeSet,
  *   runCodeReviewFn?: typeof runCodeReview,
- *   runLocalLensReviewFn?: typeof runLocalLensReview,
- *   countChangedLinesFn?: typeof countChangedLines,
- *   appendFindingsYieldFn?: typeof appendFindingsYield,
  * }} args
- * @returns {Promise<object>} The `runCodeReview` result plus
- *   `localLensReview` and the computed `changeSet`.
+ * @returns {Promise<object>} The `runCodeReview` result plus the computed
+ *   `changeSet`.
  */
 export async function runStoryReviewCore({
   storyId,
@@ -50,24 +44,12 @@ export async function runStoryReviewCore({
   gitSpawnFn = gitSpawn,
   computeChangeSetFn = computeChangeSet,
   runCodeReviewFn = runCodeReview,
-  runLocalLensReviewFn = runLocalLensReview,
-  countChangedLinesFn = countChangedLines,
-  appendFindingsYieldFn = appendFindingsYield,
 }) {
-  const storyIdNum = Number(storyId);
-
   const changeSet = computeChangeSetFn({ baseRef, headRef, gitSpawnFn });
 
-  // Line count for the lens diff-floor, probed only for a non-empty file set;
-  // `null` = unknown, and the floor fails open.
-  const changedLineCount =
-    Array.isArray(changeSet.files) && changeSet.files.length > 0
-      ? countChangedLinesFn({ baseRef, headRef, gitSpawnFn })
-      : null;
-
   const opts = {
     scope: 'story',
-    ticketId: storyIdNum,
+    ticketId: Number(storyId),
     baseRef,
     headRef,
     provider,
@@ -82,63 +64,6 @@ export async function runStoryReviewCore({
     opts.commentTargetId = commentTargetId;
   }
 
-  const localLensReview = await runLocalLensReviewFn({
-    baseRef,
-    headRef,
-    changedFiles: changeSet.files,
-    changedLineCount,
-    storyId: storyIdNum,
-    progress,
-    progressTag,
-    gitSpawnFn,
-  });
-
   const result = await runCodeReviewFn(opts);
-
-  // Best-effort findings-yield ledger, for tuning the roster on measurement.
-  try {
-    const yieldEntries = buildLensYieldEntries(localLensReview);
-    if (yieldEntries !== null) {
-      await appendFindingsYieldFn({
-        storyId: storyIdNum,
-        cli: 'story-close-review',
-        lenses: yieldEntries,
-        diffFloor: localLensReview?.floorSkip ?? null,
-      });
-    }
-  } catch (err) {
-    progress(
-      progressTag,
-      `⚠️ findings-yield ledger append failed (continuing): ${err?.message ?? err}`,
-    );
-  }
-
-  return { ...result, localLensReview, changeSet };
-}
-
-/**
- * One findings-yield entry per matched lens; `null` for an empty roster.
- *
- * @param {object|null|undefined} localLensReview
- * @returns {Array<{ lens: string, findings: number, skippedByFloor: boolean }>|null}
- */
-function buildLensYieldEntries(localLensReview) {
-  const lenses = Array.isArray(localLensReview?.lenses)
-    ? localLensReview.lenses.filter((l) => typeof l === 'string' && l.length)
-    : [];
-  if (lenses.length === 0) return null;
-  const skippedByFloor = localLensReview?.floorSkip?.skip === true;
-  const findingsByLens = new Map();
-  for (const finding of localLensReview?.materialized?.findings ?? []) {
-    if (typeof finding?.audit !== 'string') continue;
-    findingsByLens.set(
-      finding.audit,
-      (findingsByLens.get(finding.audit) ?? 0) + 1,
-    );
-  }
-  return lenses.map((lens) => ({
-    lens,
-    findings: skippedByFloor ? 0 : (findingsByLens.get(lens) ?? 0),
-    skippedByFloor,
-  }));
+  return { ...result, changeSet };
 }

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

@@ -116,6 +116,7 @@ function compact(obj) {
  * @param {object|null} [args.waitBudget]
  * @param {{ waitedSeconds: number, expired: boolean }|null} [args.lockWait]
  *   Full-suite lock wait; `waitBudget` is merge-wait only.
+ * @param {Record<string, number>|null} [args.phaseDurations] Seconds per phase.
  * @param {string} [args.timestamp]
  * @param {{ schema: object|null, error: string|null }} [args.schemaSource]
  *   Test seam.
@@ -137,6 +138,7 @@ export function buildTerminalEnvelope({
   elapsedSeconds = 0,
   waitBudget,
   lockWait,
+  phaseDurations,
   timestamp = new Date().toISOString(),
   schemaSource,
 }) {
@@ -158,6 +160,7 @@ export function buildTerminalEnvelope({
     elapsedSeconds: Math.max(0, Number(elapsedSeconds) || 0),
     waitBudget: waitBudget ?? null,
     lockWait: lockWait ?? null,
+    phaseDurations,
     timestamp,
   });
 

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

@@ -60,49 +60,32 @@ function collectTaskPathReferences(task) {
  */
 function collectTaskChangesPaths(task) {
   const paths = new Set();
-  const body = task.body;
+  const source = resolveChangesSource(task);
+  if (source === null) return paths;
+  for (const arrName of ['changes', 'references']) {
+    const arr = source[arrName];
+    if (!Array.isArray(arr)) continue;
+    for (const item of arr) collectChangesItem(item, paths);
+  }
+  return paths;
+}
 
+function resolveChangesSource(task) {
+  const body = task.body;
   // A parse failure throws rather than yielding an empty whitelist, which
   // would misreport every declared path as missing.
   if (typeof body === 'string' && body.trim().length > 0) {
-    const parsed = parseStoryBodyOrThrow(task);
-    for (const arrName of ['changes', 'references']) {
-      const arr = parsed[arrName];
-      if (!Array.isArray(arr)) continue;
-      for (const item of arr) {
-        if (typeof item === 'string') {
-          collectPathsFromText(item, paths);
-        } else if (
-          item !== null &&
-          typeof item === 'object' &&
-          typeof item.path === 'string' &&
-          item.path.length > 0
-        ) {
-          paths.add(item.path);
-        }
-      }
-    }
-    return paths;
+    return parseStoryBodyOrThrow(task);
   }
+  return body !== null && typeof body === 'object' ? body : null;
+}
 
-  if (body === null || typeof body !== 'object') return paths;
-  for (const arrName of ['changes', 'references']) {
-    const arr = body[arrName];
-    if (!Array.isArray(arr)) continue;
-    for (const item of arr) {
-      if (typeof item === 'string') {
-        collectPathsFromText(item, paths);
-      } else if (
-        item !== null &&
-        typeof item === 'object' &&
-        typeof item.path === 'string' &&
-        item.path.length > 0
-      ) {
-        paths.add(item.path);
-      }
-    }
+function collectChangesItem(item, paths) {
+  if (typeof item === 'string') {
+    collectPathsFromText(item, paths);
+  } else if (typeof item?.path === 'string' && item.path.length > 0) {
+    paths.add(item.path);
   }
-  return paths;
 }
 
 function defaultGitRunner({ baseBranchRef, path, cwd }) {

package/.agents/scripts/lib/signals/detectors/common.js

@@ -51,9 +51,12 @@ export function extractTool(rec) {
  */
 export function validateDetectorArgs(args, opts) {
   const { fnName } = opts;
-  const requireTracesPath = opts.requireTracesPath ?? true;
-  const requireStoryId = opts.requireStoryId ?? true;
-  const requireThreshold = opts.requireThreshold ?? true;
+  const gates = {
+    always: true,
+    requireTracesPath: opts.requireTracesPath ?? true,
+    requireStoryId: opts.requireStoryId ?? true,
+    requireThreshold: opts.requireThreshold ?? true,
+  };
 
   if (args == null || typeof args !== 'object') {
     throw new TypeError(
@@ -61,57 +64,66 @@ export function validateDetectorArgs(args, opts) {
     );
   }
 
-  const { tracesPath, epicId, storyId, threshold } = args;
-  const taskId = args.taskId ?? null;
-
-  if (args.nowFn != null && typeof args.nowFn !== 'function') {
-    throw new TypeError(
-      `${fnName}: nowFn, when provided, must be a function (got ${typeof args.nowFn})`,
-    );
-  }
-  const nowFn = args.nowFn ?? (() => new Date().toISOString());
-
-  if (requireTracesPath) {
-    if (typeof tracesPath !== 'string' || tracesPath.length === 0) {
-      throw new TypeError(
-        `${fnName}: tracesPath must be a non-empty string (got ${tracesPath})`,
-      );
-    }
-  }
-
-  if (!isPositiveInt(epicId)) {
-    throw new RangeError(
-      `${fnName}: epicId must be a positive integer (got ${epicId})`,
-    );
-  }
-
-  if (requireStoryId) {
-    if (!isPositiveInt(storyId)) {
-      throw new RangeError(
-        `${fnName}: storyId must be a positive integer (got ${storyId})`,
-      );
-    }
-    if (taskId !== null && !isPositiveInt(taskId)) {
-      throw new RangeError(
-        `${fnName}: taskId must be a positive integer or null (got ${taskId})`,
-      );
-    }
-  }
-
-  if (requireThreshold) {
-    if (!Number.isInteger(threshold) || threshold < 0) {
-      throw new RangeError(
-        `${fnName}: threshold must be a non-negative integer (got ${threshold})`,
-      );
+  const values = { ...args, taskId: args.taskId ?? null };
+  for (const rule of DETECTOR_ARG_RULES) {
+    const value = values[rule.field];
+    if (gates[rule.gate] && rule.invalid(value)) {
+      throw new rule.Error(`${fnName}: ${rule.message(value)}`);
     }
   }
 
   return {
-    tracesPath: requireTracesPath ? tracesPath : undefined,
-    epicId,
-    storyId: requireStoryId ? storyId : undefined,
-    taskId: requireStoryId ? taskId : undefined,
-    threshold: requireThreshold ? threshold : undefined,
-    nowFn,
+    tracesPath: gates.requireTracesPath ? values.tracesPath : undefined,
+    epicId: values.epicId,
+    storyId: gates.requireStoryId ? values.storyId : undefined,
+    taskId: gates.requireStoryId ? values.taskId : undefined,
+    threshold: gates.requireThreshold ? values.threshold : undefined,
+    nowFn: args.nowFn ?? (() => new Date().toISOString()),
   };
 }
+
+const DETECTOR_ARG_RULES = [
+  {
+    field: 'nowFn',
+    gate: 'always',
+    invalid: (v) => v != null && typeof v !== 'function',
+    Error: TypeError,
+    message: (v) =>
+      `nowFn, when provided, must be a function (got ${typeof v})`,
+  },
+  {
+    field: 'tracesPath',
+    gate: 'requireTracesPath',
+    invalid: (v) => typeof v !== 'string' || v.length === 0,
+    Error: TypeError,
+    message: (v) => `tracesPath must be a non-empty string (got ${v})`,
+  },
+  {
+    field: 'epicId',
+    gate: 'always',
+    invalid: (v) => !isPositiveInt(v),
+    Error: RangeError,
+    message: (v) => `epicId must be a positive integer (got ${v})`,
+  },
+  {
+    field: 'storyId',
+    gate: 'requireStoryId',
+    invalid: (v) => !isPositiveInt(v),
+    Error: RangeError,
+    message: (v) => `storyId must be a positive integer (got ${v})`,
+  },
+  {
+    field: 'taskId',
+    gate: 'requireStoryId',
+    invalid: (v) => v !== null && !isPositiveInt(v),
+    Error: RangeError,
+    message: (v) => `taskId must be a positive integer or null (got ${v})`,
+  },
+  {
+    field: 'threshold',
+    gate: 'requireThreshold',
+    invalid: (v) => !Number.isInteger(v) || v < 0,
+    Error: RangeError,
+    message: (v) => `threshold must be a non-negative integer (got ${v})`,
+  },
+];

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -31,13 +31,11 @@ export function renderStoryAuthorCore() {
     (lint) =>
       `- **${lint.id}** — ${lint.summary} Example: \`${lint.goodExample}\``,
   ).join('\n');
-  return `You are an expert Senior Project Manager and Orchestrator.
-Your job is to turn a plan seed / Tech Spec into a Story ticket array for an AI Agent to execute.
+  return `Turn a plan seed / Tech Spec into Story tickets for an AI agent to execute. The emitted stories template (see STORY BODY SCHEMA) is the ticket shape.
 
 ### HIERARCHY RULES (v2 default-single):
 1. **Emit exactly one Story by default.** Split into N>1 only when pieces have near-zero overlap or sit across an architectural seam. Coupled work stays one Story — put intra-session checkpoints in \`## Slicing\` and fold the Tech Spec into \`## Spec\`.
 2. **Stories**: Specific user-facing or architectural capabilities (e.g., "Implement JWT Token Exchange").
-   - There is NO Epic parent ticket, NO Feature tier, and NO Task layer.
    - **Story-Level Execution**: Each Story is executed end-to-end on a single branch by a single agent. Acceptance criteria and verification commands live as top-level \`acceptance[]\` / \`verify[]\` arrays on the Story ticket (see STORY BODY SCHEMA below).
    - Thematic grouping is prose in the Story's folded \`## Spec\` / \`## Slicing\`, never sibling tickets for coupled work.
 
@@ -46,27 +44,10 @@ Your job is to turn a plan seed / Tech Spec into a Story ticket array for an AI
 - \`labels[]\` is **optional**. Emit it only to request an *additional* label; persist sanitizes the list before applying it.
 - Do **not** emit \`agent::*\` labels — lifecycle state is runtime-owned, and persist applies \`agent::ready\` itself once every checkpoint is on the ticket.
 
-### OUTPUT FORMAT:
-You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown blocks.
-
-### JSON SCHEMA:
-[
-  {
-    "slug": "hyphen-case-id",
-    "type": "story",
-    "title": "Short descriptive title",
-    "body": <string — see STORY BODY SCHEMA below>,
-    "acceptance": ["<outcome a PR reviewer can confirm>", ...],
-    "verify": ["<exact command or test path>", ...],
-    "labels": ["<extra-label>"] (optional — type::story is applied automatically; omit this field unless you need an additional label),
-    "depends_on": ["slug-of-blocking-dependency"] (optional array of Story slugs that block execution)
-  }
-]
-
 **Slug format**: \`^[a-z0-9][a-z0-9-]*$\` — hyphen-case only. Underscores are rejected by the validator.
 
 ### STORY BODY SCHEMA (REQUIRED FOR EVERY STORY):
-\`body\` is either the serialized markdown **string** (the section format below) or a **structured object** carrying the same fields (\`goal\`, optional \`slicing\` / \`spec\`, \`changes\`, optional \`non_goals\`) — persist parses either shape and serializes the canonical markdown itself, so you never need to read \`story-body.js\` or hand-assemble the markdown (the \`stories.template.json\` file emitted next to the plan-context envelope is a ready-to-fill structured-object skeleton). Stories are consumed by non-interactive sub-agents that must self-verify from the Story ticket alone — so the ticket must carry everything an agent needs to execute and self-verify.
+\`body\` is either the serialized markdown **string** (the section format below) or a **structured object** carrying the same fields (\`goal\`, optional \`slicing\` / \`spec\`, \`changes\`, optional \`non_goals\`) — persist parses either shape and serializes the canonical markdown itself, so you never need to read \`story-body.js\` or hand-assemble the markdown (the \`stories.template.json\` file emitted next to the plan-context envelope is a ready-to-fill structured-object skeleton). The executing sub-agent is non-interactive and self-verifies from the ticket alone, so the ticket carries everything it needs.
 
 The \`acceptance[]\` and \`verify[]\` arrays live at the **top level** of the Story ticket object — that is the machine contract the validator reads. Author each list **once, at top level**, and **omit** the \`## Acceptance\` / \`## Verify\` sections from the authored \`body\` string: persist syncs the top-level arrays into those sections so the GitHub issue stays a complete executable document. The validator resolves both fields from the top level, so an omitted section is the expected shape, not a violation.
 
@@ -153,9 +134,9 @@ ${envelopeFloor}
 - A Story touching UI (\`*.tsx\`, \`*.astro\`, \`*.svelte\`, \`*.vue\`, a components folder) states the \`data-testid\` contract in \`acceptance[]\` per the testid contract in \`.agents/skills/stack/qa/playwright/SKILL.md\`.
 - A Story touching user-visible copy, brand assets or visual style cites the relevant section of \`docs/style-guide.md\` in \`acceptance[]\` when that file exists.
 
-CRITICAL: Dependencies should follow execution blockers. There is no parent ticket — never emit a 'parent_slug' field.
-IMPORTANT DEPENDENCY RULE: Story-to-Story dependencies are expressed via \`depends_on\` (one Story depends_on another Story's slug). Use this to express execution ordering across the plan.
-**Never stop mid-array.** Always emit complete JSON — partial arrays are rejected by the validator.`;
+#### ORDERING:
+
+Express execution ordering between Stories with \`depends_on\` — the slugs of the Stories that must land first. Never emit a parent field.`;
 }
 
 /**

package/.agents/scripts/lib/transpile.js

@@ -8,6 +8,9 @@ const require = createRequire(import.meta.url);
 
 const TS_EXTS = new Set(['.ts', '.tsx', '.mts', '.cts']);
 
+/** TS 7 moved `transpileModule` under `unstable/*`; mirrors the peer range. */
+const SUPPORTED_TS_RANGE = '>=5.0.0 <7';
+
 let _ts = null;
 let _tsLoadFailed = false;
 
@@ -23,6 +26,27 @@ function loadTypeScript() {
   }
 }
 
+/** Compiler modules already diagnosed as API-less — one warning per module. */
+const _unsupportedDiagnosed = new WeakSet();
+
+/**
+ * Warn once per API-less module rather than once per file.
+ *
+ * @param {object} ts
+ * @returns {boolean}
+ */
+function isUsableCompiler(ts) {
+  if (typeof ts.transpileModule === 'function') return true;
+  if (!_unsupportedDiagnosed.has(ts)) {
+    _unsupportedDiagnosed.add(ts);
+    Logger.warn(
+      `[Maintainability] ⚠ typescript ${ts.version ?? 'unknown'} exposes no transpileModule API; ` +
+        `TypeScript files are not scored. Supported range: ${SUPPORTED_TS_RANGE}.`,
+    );
+  }
+  return false;
+}
+
 let _tsVersion = null;
 
 /**
@@ -100,7 +124,7 @@ function buildLineMapper(sourceMapText, code) {
  *
  * @param {string} filePath
  * @param {string} source
- * @param {{withLineMap?: boolean}} [opts]
+ * @param {{withLineMap?: boolean, typescript?: object}} [opts]
  * @returns {string|null|{code: string, mapLine: ((line: number) => number|null)|null}}
  */
 export function transpileIfNeeded(filePath, source, opts = {}) {
@@ -108,14 +132,15 @@ export function transpileIfNeeded(filePath, source, opts = {}) {
   if (!isTypeScriptPath(filePath)) {
     return withLineMap ? { code: source, mapLine: null } : source;
   }
-  const ts = loadTypeScript();
+  const ts = opts?.typescript ?? loadTypeScript();
   if (!ts) {
     Logger.warn(
       `[Maintainability] ⚠ typescript package not resolvable; cannot score ${filePath}. ` +
-        "Install with 'npm install --save-dev typescript' (peer dep, >=5.0.0).",
+        `Install with 'npm install --save-dev typescript' (peer dep, ${SUPPORTED_TS_RANGE}).`,
     );
     return null;
   }
+  if (!isUsableCompiler(ts)) return null;
   try {
     const result = ts.transpileModule(source, {
       compilerOptions: {

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

@@ -138,38 +138,29 @@ export class IssuesGateway {
 
   /**
    * Resolve an issue's container parent in one request via `Issue.parent`.
-   * Never throws: no parent, an odd shape, or sub-issues being unavailable all
-   * return `null`, leaving the caller's checklist fallback to run.
+   * `null` means "no parent"; a degraded lookup throws after retries.
    *
    * @param {number} number Issue number whose parent to resolve.
    * @returns {Promise<object|null>} Mapped parent ticket, or null.
+   * @throws {Error} When the lookup degrades.
    * @field-manifest GraphQL Issue.parent: number, id, title, body, state,
    *                 labels.nodes.name, assignees.nodes.login
    */
   async getParentIssue(number) {
     const issueNumber = Number(number);
     if (!Number.isInteger(issueNumber) || issueNumber <= 0) return null;
-    let data;
-    try {
-      data = await withTransientRetry(
-        () =>
-          this.ghGraphql(
-            PARENT_ISSUE_QUERY,
-            { owner: this.owner, repo: this.repo, number: issueNumber },
-            { headers: { 'GraphQL-Features': 'sub_issues' } },
-          ),
-        {
-          label: `getParentIssue #${issueNumber}`,
-          onRetry: defaultRetryWarn,
-        },
-      );
-    } catch (err) {
-      Logger.warn(
-        `[GitHubProvider] parent lookup for #${issueNumber} degraded to none ` +
-          `(${err?.message ?? err}).`,
-      );
-      return null;
-    }
+    const data = await withTransientRetry(
+      () =>
+        this.ghGraphql(
+          PARENT_ISSUE_QUERY,
+          { owner: this.owner, repo: this.repo, number: issueNumber },
+          { headers: { 'GraphQL-Features': 'sub_issues' } },
+        ),
+      {
+        label: `getParentIssue #${issueNumber}`,
+        onRetry: defaultRetryWarn,
+      },
+    );
     return subIssueNodeToTicket(data?.repository?.issue?.parent ?? null);
   }
 

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

@@ -16,7 +16,11 @@
  *                              [--merge-watch-mode <sync|async>]
  *                              [--rerun-advisory <n>]
  *                              [--override-review-block <reason>]
+ *                              [--worker-tokens <n>]
  *
+ * `--worker-tokens <n>` is the story-worker's host-reported token total,
+ * recorded best-effort in the close result's `telemetry` (absent or invalid →
+ * `null` plus a warning; never a change of status or exit code).
  * `--override-review-block <reason>` is the audited escape past a code-review
  * CRITICAL blocker (instead of a hand-merge with no record).
  * `--merge-watch-mode async` is passed per close by the orchestrator, the only
@@ -35,7 +39,7 @@ import { parseSprintArgsTolerant } from './lib/cli-args.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { formatCliError } from './lib/error-redactor.js';
 import { Logger } from './lib/Logger.js';
-import { emitTerminalFriction } from './lib/observability/runtime-friction.js';
+import { emitCloseTerminalSignals } from './lib/observability/close-telemetry.js';
 import { resolveRunScopedConfig } from './lib/orchestration/run-scoped-config.js';
 import {
   failedTerminalFor,
@@ -91,7 +95,7 @@ async function main() {
     // Mirrors runAsCli's default error line, which this catch pre-empts.
     Logger.error(`[single-story-close] Fatal error: ${formatCliError(err)}`);
     emitTerminalEnvelope(terminal);
-    await emitTerminalFriction({ envelope: terminal });
+    await emitCloseTerminalSignals({ envelope: terminal });
     return exitCodeForTerminal(terminal);
   }
 }
@@ -130,6 +134,10 @@ runAsCli(import.meta.url, main, {
         // forbids that literal outside `phases/auto-merge.js`.
         'Land despite a Story-scope code-review CRITICAL blocker you have reviewed and judged wrong. The reason is mandatory (≥12 chars) and is recorded on the Story, on the PR, and as a `review-block-overridden` friction signal; the terminal envelope reports `gates.codeReview: "overridden"`. Use this instead of merging the PR by hand with the GitHub CLI — a hand-merge bypasses the gate with no record at all.',
       ],
+      [
+        '--worker-tokens <n>',
+        'The story-worker’s host-reported total tokens, recorded in the close result’s `telemetry.workerTokens`. Best-effort: an absent or non-integer value records null with a warning and never changes the status or exit code.',
+      ],
     ],
     notes: [
       'Exit codes:\n  0  landed\n  1  blocked or failed\n  3  pending (resumable — run the envelope’s nextCommand)',