mandrel 2.65.0 → 2.66.0

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/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/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)',