mandrel 2.8.0 → 2.9.0

package/.agents/docs/configuration.md

@@ -102,6 +102,10 @@ top-level keys are validation errors.
 | `codebaseSnapshot.include` | No | `array<string>` | — | — |
 | `codebaseSnapshot.exclude` | No | `array<string>` | — | — |
 | `codebaseSnapshot.recentCommitWindow` | No | `integer` | — | — |
+| `complexityGate` | No | `object` | — | Plan-time ceremony-lite complexity gate. Routes trivial single-artifact seeds onto a collapsed plan/deliver path; conservative (full on any doubt). Never relaxes the Story-ticket / PR-to-main / repo-gates / security-baseline non-negotiables. |
+| `complexityGate.enabled` | No | `boolean` | — | Master switch. When false, every seed takes the full plan/deliver ceremony. Default true. |
+| `complexityGate.maxSeedWords` | No | `integer` | — | Seed prose word ceiling for the lite path. A seed above this many words is not trivial and takes the full path. Default 60. |
+| `complexityGate.maxArtifacts` | No | `integer` | — | Enumerated-artifact ceiling for the lite path. A seed enumerating more than this many candidate artifacts is multi-capability and takes the full path. Default 1. |
 | `failOnSharedEditors` | No | `boolean` | — | When true, upgrade shared-editor conflict findings to hard errors (default false — advisory soft findings only). |
 | `requireExplicitCrossStoryDeps` | No | `boolean` | — | When true, upgrade implicit cross-Story dependency findings to hard errors (default false — advisory soft findings only). |
 | `failOnRegistryConflicts` | No | `boolean` | — | When true, upgrade cross-cutting registry conflict findings to hard errors (default false). |
@@ -344,6 +348,28 @@ scans `.agents/scripts/**`, `src/**`, `lib/**`, `app/**`, `packages/**` and
 `exclude` drops `node_modules`, build dirs, and test files. Override `include`
 only when the project's source layout differs.
 
+- **`complexityGate`.** Plan-time ceremony-lite routing (Story #4683). The full
+  two-session plan/deliver ceremony buys measurable quality on capability-sized
+  work but imposes a large fixed cost premium on genuinely trivial
+  single-artifact scopes with no measured quality gain. The gate reads the
+  planning seed and emits a `complexityRoute` signal on the `/plan` context
+  envelope: `lite` collapses the plan/deliver session split and skips the
+  fresh-critic / Tech-Spec ceremony a one-artifact scope does not earn; `full`
+  keeps the whole ceremony. It is **deterministic and conservative** — `lite`
+  only when every trivial-scope signal agrees (seed ≤ `maxSeedWords` words **and**
+  ≤ `maxArtifacts` enumerated items), and `full` on any doubt (empty seed, over
+  the ceiling, multi-capability enumeration, or the gate disabled). The lite path
+  **never** relaxes a non-negotiable: it still produces a Story ticket, still
+  lands via a PR to `main`, still runs every repo quality gate, and still honours
+  `rules/security-baseline.md` — those gates run in `single-story-close.js`
+  regardless of route. **Threshold + override:** `enabled` (default `true`;
+  `false` forces every seed to `full`), `maxSeedWords` (default `60`), and
+  `maxArtifacts` (default `1`). The defaults are the single source of truth on
+  `DEFAULT_COMPLEXITY_GATE` in
+  [`lib/orchestration/complexity-gate.js`](../scripts/lib/orchestration/complexity-gate.js);
+  a malformed or negative ceiling falls back to the default rather than widening
+  the lite path.
+
 ### `delivery`
 
 - **`docsFreshness.paths`.** Files refreshed during the post-PR-merge release

package/.agents/schemas/agentrc.schema.json

@@ -327,6 +327,27 @@
         "codebaseSnapshot": {
           "$ref": "#/$defs/codebaseSnapshot"
         },
+        "complexityGate": {
+          "type": "object",
+          "description": "Plan-time ceremony-lite complexity gate. Routes trivial single-artifact seeds onto a collapsed plan/deliver path; conservative (full on any doubt). Never relaxes the Story-ticket / PR-to-main / repo-gates / security-baseline non-negotiables.",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "Master switch. When false, every seed takes the full plan/deliver ceremony. Default true."
+            },
+            "maxSeedWords": {
+              "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."
+            },
+            "maxArtifacts": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Enumerated-artifact ceiling for the lite path. A seed enumerating more than this many candidate artifacts is multi-capability and takes the full path. Default 1."
+            }
+          },
+          "additionalProperties": false
+        },
         "failOnSharedEditors": {
           "type": "boolean",
           "description": "When true, upgrade shared-editor conflict findings to hard errors (default false — advisory soft findings only)."

package/.agents/scripts/audit-to-stories.js

@@ -31,6 +31,7 @@ import fs from 'node:fs';
 import { glob } from 'node:fs/promises';
 import path from 'node:path';
 import process from 'node:process';
+import { pathToFileURL } from 'node:url';
 import { parseArgs } from 'node:util';
 import { buildStoryBody } from './lib/audit-to-stories/build-story-body.js';
 import { classifyGroupsAgainstGitHub } from './lib/audit-to-stories/dedupe-against-github.js';
@@ -85,12 +86,30 @@ function tallyBySeverity(findings) {
   return t;
 }
 
+/**
+ * Test-only seam: when `AUDIT_TO_STORIES_PROVIDER_FIXTURE` names a module, load
+ * its default export as the dedup provider (ports) instead of the live GitHub
+ * provider. This lets the soft-fail contract be exercised end-to-end through
+ * the real `--scan` CLI with a search port that fails for a subset of groups
+ * (Story #4678, AC-8), with no network. Returns null when the env var is unset.
+ *
+ * @returns {Promise<object|null>}
+ */
+async function loadFixtureProvider() {
+  const fixturePath = process.env.AUDIT_TO_STORIES_PROVIDER_FIXTURE;
+  if (!fixturePath) return null;
+  const mod = await import(pathToFileURL(fixturePath).href);
+  return mod.default ?? null;
+}
+
 async function loadProvider({ createProviderImpl, resolveConfigImpl } = {}) {
   // The provider is optional — when missing, the dedupe step emits a
   // create-only classification and the workflow operator is informed. The
   // `createProviderImpl` / `resolveConfigImpl` seams let a contract test drive
   // this exact adapter (fingerprint + semantic-candidate ports) with an
   // in-memory issue store instead of the live GitHub provider.
+  const fixture = await loadFixtureProvider();
+  if (fixture) return fixture;
   try {
     const resolveConfig =
       resolveConfigImpl ??
@@ -180,6 +199,31 @@ function dedupSkippedWarning(reason) {
   );
 }
 
+/**
+ * Render the loud, operator-visible warning emitted when Phase 6 dedup ran but
+ * one or more groups' lookups could not complete (an HTTP 422, or a rate limit
+ * still exhausted after the endpoint budget's cooldown). Those groups degrade
+ * to `create` rather than aborting the whole scan (Story #4678); this warning
+ * names each affected group so the operator knows exactly which to check by
+ * hand. Mirrors the `dedupSkippedWarning` shape so a partially-checked plan
+ * reads as clearly as a wholly-unchecked one.
+ *
+ * Pure: returns the message string so `buildPlan` owns the single `Logger.warn`
+ * write site (stderr) and the text stays unit-testable.
+ *
+ * @param {Array<{ group: string, reason: string }>} entries
+ * @returns {string}
+ */
+function dedupDegradedWarning(entries) {
+  const lines = (entries ?? []).map((e) => `  - ${e.group}: ${e.reason}`);
+  return (
+    `dedup degraded for ${lines.length} group(s): their GitHub lookup could ` +
+    'not complete, so they are classified "create" WITHOUT a dedup check. A ' +
+    'run that creates Stories from this plan may open duplicates of these ' +
+    `groups — verify each by hand before opening:\n${lines.join('\n')}`
+  );
+}
+
 async function buildPlan({ glob: pattern, severity, useProvider, ledger }) {
   const reportPaths = await collectReportPaths(pattern ?? DEFAULT_GLOB);
   if (reportPaths.length === 0) {
@@ -227,6 +271,12 @@ async function buildPlan({ glob: pattern, severity, useProvider, ledger }) {
       classifications = result.classifications;
       summary = result.summary;
       dedupApplied = true;
+      // A partially-checked plan is a useful result — warn loudly (stderr, so
+      // the --scan JSON on stdout stays clean) naming the groups that degraded
+      // to create because their lookup could not complete (Story #4678).
+      if (summary.dedupDegraded?.count > 0) {
+        Logger.warn(dedupDegradedWarning(summary.dedupDegraded.groups));
+      }
     } else {
       // The provider could not resolve a searchIssues port — the dedup gate
       // is silently a no-op without this. Surface it loudly (stderr, so the
@@ -488,6 +538,7 @@ export const __testing = {
   buildPlan,
   loadProvider,
   dedupSkippedWarning,
+  dedupDegradedWarning,
   buildAndGateStories,
   runAuto,
   resolveSeverityFloor,

package/.agents/scripts/lib/audit-to-stories/dedupe-against-github.js

@@ -36,6 +36,92 @@ import { toCanonicalFinding } from './finding-adapter.js';
  * @property {string[]} matchedFingerprints — full sha1 list that triggered the match.
  */
 
+/**
+ * Render a short, operator-legible reason from a dedup-lookup failure. Pure —
+ * no imports, no I/O — so the module stays pure orchestration (Story #4678).
+ * @param {unknown} err
+ * @returns {string}
+ */
+function describeDegradeReason(err) {
+  const status = err?.status;
+  const message = err?.message ?? String(err);
+  if (status === 422 || /\b422\b/.test(message)) {
+    return 'search query rejected (HTTP 422)';
+  }
+  if (/rate limit/i.test(message)) {
+    return 'rate limit still exhausted after cooldown';
+  }
+  return `dedup lookup failed: ${message}`;
+}
+
+/**
+ * Stable operator-facing label for a group in a degrade report.
+ * @param {object} group
+ * @returns {string}
+ */
+function groupLabel(group) {
+  return group?.groupKey ?? group?.title ?? '(unlabelled group)';
+}
+
+/**
+ * Route every finding in one group and fold the per-finding decisions up to a
+ * group action. Extracted so the top-level loop can wrap it in one try/catch:
+ * a search failure that survives the endpoint budget (an HTTP 422, or a rate
+ * limit still exhausted after the cooldown) throws out of here and is caught
+ * once per group rather than aborting the whole scan (Story #4678).
+ *
+ * @param {object} group
+ * @param {object} routing — `{ searchIssues, semanticPort, routeOptions }`.
+ * @returns {Promise<{ action: string, matchedIssues: Array, matchedFingerprints: string[] }>}
+ */
+async function classifyOneGroup(
+  group,
+  { searchIssues, semanticPort, routeOptions },
+) {
+  const findings = group.findings ?? [];
+  const matchedIssues = [];
+  const matchedFingerprints = [];
+  let sawOpen = false;
+  let sawClosed = false;
+
+  for (const finding of findings) {
+    const sha = finding?.fingerprint?.full;
+    if (typeof sha !== 'string' || sha.length !== 40) continue;
+
+    const canonical = toCanonicalFinding(finding);
+    const { decision, matchedIssue, fingerprint } = await routeFinding(
+      canonical,
+      semanticPort
+        ? { searchIssues, searchCandidates: () => semanticPort(canonical) }
+        : { searchIssues },
+      routeOptions,
+    );
+
+    if (decision === 'new') continue;
+
+    if (matchedIssue) {
+      matchedIssues.push({
+        number: matchedIssue.number,
+        state: matchedIssue.state,
+      });
+    }
+    if (!matchedFingerprints.includes(fingerprint)) {
+      matchedFingerprints.push(fingerprint);
+    }
+    if (decision === 'update-existing' || decision === 'duplicate') {
+      sawOpen = true;
+    } else if (decision === 'regression-of-closed') {
+      sawClosed = true;
+    }
+  }
+
+  let action = 'create';
+  if (sawOpen) action = 'skip-open';
+  else if (sawClosed) action = 'skip-reoccurring';
+
+  return { action, matchedIssues, matchedFingerprints };
+}
+
 /**
  * @param {object} params
  * @param {Array<object>} params.groups — output of `groupFindings`.
@@ -44,12 +130,18 @@ import { toCanonicalFinding } from './finding-adapter.js';
  *   Optional meaning-first candidate search (production: `semantic-issue-search.js`).
  *   When supplied, routing runs the Stage-1 semantic pass and opts into
  *   location-based semantic-key confirmation.
- * @returns {Promise<{ classifications: GroupClassification[], summary: { create: number, skipOpen: number, skipReoccurring: number } }>}
+ * @param {(entry: { group: object, reason: string }) => void} [params.onDegraded]
+ *   Optional sink notified once per group whose dedup lookup could not complete
+ *   (Story #4678). The group is then classified `create` — a soft-fail, never
+ *   fatal. Pure orchestration: this module performs no network I/O and swallows
+ *   no failure silently.
+ * @returns {Promise<{ classifications: GroupClassification[], summary: { create: number, skipOpen: number, skipReoccurring: number, dedupDegraded: { count: number, groups: Array<{ group: string, reason: string }> } } }>}
  */
 export async function classifyGroupsAgainstGitHub({
   groups,
   provider,
   searchCandidates,
+  onDegraded,
 }) {
   if (!Array.isArray(groups)) {
     throw new Error('classifyGroupsAgainstGitHub: groups must be an array');
@@ -67,67 +159,40 @@ export async function classifyGroupsAgainstGitHub({
   const searchIssues = (sha) => provider.findIssuesByFingerprint(sha);
   const semanticPort =
     typeof searchCandidates === 'function' ? searchCandidates : undefined;
-  const routeOptions = { semanticKeyConfirm: Boolean(semanticPort) };
+  const routing = {
+    searchIssues,
+    semanticPort,
+    routeOptions: { semanticKeyConfirm: Boolean(semanticPort) },
+  };
 
   const classifications = [];
-  const summary = { create: 0, skipOpen: 0, skipReoccurring: 0 };
+  const summary = {
+    create: 0,
+    skipOpen: 0,
+    skipReoccurring: 0,
+    dedupDegraded: { count: 0, groups: [] },
+  };
 
   for (const group of groups) {
-    const findings = group.findings ?? [];
-
-    const matchedIssues = [];
-    const matchedFingerprints = [];
-    let sawOpen = false;
-    let sawClosed = false;
-
-    for (const finding of findings) {
-      const sha = finding?.fingerprint?.full;
-      if (typeof sha !== 'string' || sha.length !== 40) continue;
-
-      const canonical = toCanonicalFinding(finding);
-      const { decision, matchedIssue, fingerprint } = await routeFinding(
-        canonical,
-        semanticPort
-          ? { searchIssues, searchCandidates: () => semanticPort(canonical) }
-          : { searchIssues },
-        routeOptions,
-      );
-
-      if (decision === 'new') continue;
-
-      if (matchedIssue) {
-        matchedIssues.push({
-          number: matchedIssue.number,
-          state: matchedIssue.state,
-        });
-      }
-      if (!matchedFingerprints.includes(fingerprint)) {
-        matchedFingerprints.push(fingerprint);
-      }
-      if (decision === 'update-existing' || decision === 'duplicate') {
-        sawOpen = true;
-      } else if (decision === 'regression-of-closed') {
-        sawClosed = true;
-      }
+    let result;
+    try {
+      result = await classifyOneGroup(group, routing);
+    } catch (err) {
+      // A dedup lookup that cannot complete degrades this group to `create`
+      // with a recorded reason — never aborts the whole scan.
+      const reason = describeDegradeReason(err);
+      const entry = { group: groupLabel(group), reason };
+      summary.dedupDegraded.count += 1;
+      summary.dedupDegraded.groups.push(entry);
+      if (typeof onDegraded === 'function') onDegraded({ group, reason });
+      result = { action: 'create', matchedIssues: [], matchedFingerprints: [] };
     }
 
-    let action = 'create';
-    if (sawOpen) {
-      action = 'skip-open';
-      summary.skipOpen += 1;
-    } else if (sawClosed) {
-      action = 'skip-reoccurring';
-      summary.skipReoccurring += 1;
-    } else {
-      summary.create += 1;
-    }
+    if (result.action === 'skip-open') summary.skipOpen += 1;
+    else if (result.action === 'skip-reoccurring') summary.skipReoccurring += 1;
+    else summary.create += 1;
 
-    classifications.push({
-      group,
-      action,
-      matchedIssues,
-      matchedFingerprints,
-    });
+    classifications.push({ group, ...result });
   }
 
   return { classifications, summary };

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

@@ -278,6 +278,38 @@ const PLANNING_SCHEMA = {
   properties: {
     riskHeuristics: LIST_OR_EXTENDER_OF_STRINGS,
     codebaseSnapshot: CODEBASE_SNAPSHOT_SCHEMA,
+    // Story #4683 — plan-time ceremony-lite complexity gate. Routes a trivial
+    // single-artifact seed onto a collapsed plan/deliver path while a
+    // multi-capability seed keeps the full ceremony. Deterministic and
+    // conservative (full on any doubt); the lite path never relaxes a
+    // non-negotiable (Story ticket, PR-to-main, repo gates, security baseline).
+    // Defaults live on DEFAULT_COMPLEXITY_GATE in
+    // `lib/orchestration/complexity-gate.js`.
+    complexityGate: {
+      type: 'object',
+      description:
+        'Plan-time ceremony-lite complexity gate. Routes trivial single-artifact seeds onto a collapsed plan/deliver path; conservative (full on any doubt). Never relaxes the Story-ticket / PR-to-main / repo-gates / security-baseline non-negotiables.',
+      properties: {
+        enabled: {
+          type: 'boolean',
+          description:
+            'Master switch. When false, every seed takes the full plan/deliver ceremony. Default true.',
+        },
+        maxSeedWords: {
+          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.',
+        },
+        maxArtifacts: {
+          type: 'integer',
+          minimum: 0,
+          description:
+            'Enumerated-artifact ceiling for the lite path. A seed enumerating more than this many candidate artifacts is multi-capability and takes the full path. Default 1.',
+        },
+      },
+      additionalProperties: false,
+    },
     // Cross-Story conflict-finding severity gates. Off by default so
     // existing repos keep advisory-only behaviour; flipping either to
     // `true` upgrades the matching finding class to `'hard'`, which routes

package/.agents/scripts/lib/findings/semantic-issue-search.js

@@ -23,6 +23,13 @@
 
 const DEFAULT_LIMIT = 25;
 
+/**
+ * Character budget for the query {@link buildQuery} emits. Default 200 leaves
+ * headroom under GitHub Search's 256-char limit for the `repo:` / `type:`
+ * qualifiers `searchIssues` appends (Story #4678).
+ */
+const DEFAULT_QUERY_BUDGET = 200;
+
 /**
  * Normalise a free-text string for token comparison: lowercased, trimmed,
  * punctuation collapsed to spaces.
@@ -68,18 +75,49 @@ function jaccard(a, b) {
   return union === 0 ? 0 : intersection / union;
 }
 
+/**
+ * The trailing path segment of a slash-or-backslash-delimited path. A deep
+ * `primaryFile` like `src/very/deep/module.js` contributes only `module.js`
+ * to the query — the basename carries the discriminating signal while the
+ * mangled path spends the character budget for nothing (Story #4678).
+ * @param {unknown} value
+ * @returns {string}
+ */
+function basename(value) {
+  const str = String(value ?? '');
+  const cut = str.split(/[\\/]/).filter(Boolean);
+  return cut.length > 0 ? cut[cut.length - 1] : '';
+}
+
 /**
  * Build the search query text for a finding. The title carries the strongest
- * signal; area and primaryFile sharpen it. This is the text both the
- * (production) full-text search port and the local relevance scorer key on.
+ * signal; area and the primaryFile **basename** sharpen it. This is the text
+ * both the (production) full-text search port and the local relevance scorer
+ * key on. The result is filled highest-signal-first (title, then area, then
+ * basename) up to `budget` characters on a whole-token boundary so a long title
+ * over a deep path never blows GitHub Search's length limit (Story #4678).
  * @param {object} finding
+ * @param {object} [options]
+ * @param {number} [options.budget] — max query length in characters.
  * @returns {string}
  */
-export function buildQuery(finding) {
-  return [finding?.title, finding?.area, finding?.primaryFile]
+export function buildQuery(finding, { budget = DEFAULT_QUERY_BUDGET } = {}) {
+  const tokens = [finding?.title, finding?.area, basename(finding?.primaryFile)]
     .map((v) => normaliseText(v))
     .filter((v) => v.length > 0)
-    .join(' ');
+    .join(' ')
+    .split(' ')
+    .filter(Boolean);
+
+  const kept = [];
+  let length = 0;
+  for (const token of tokens) {
+    const cost = kept.length === 0 ? token.length : token.length + 1;
+    if (length + cost > budget) break;
+    kept.push(token);
+    length += cost;
+  }
+  return kept.join(' ');
 }
 
 /**

package/.agents/scripts/lib/observability/terse-result.js

@@ -0,0 +1,114 @@
+import nodeFs from 'node:fs';
+import path from 'node:path';
+
+import { Logger } from '../Logger.js';
+
+/**
+ * Terse hot-path result emission (Story #4685).
+ *
+ * The orchestration CLIs an agent invokes on every delivery turn
+ * (`single-story-init`, `single-story-close`, `single-story-confirm-merge`,
+ * `sync-branch-from-base`, the close `emit-blocked` path) historically dumped
+ * their whole result object to stdout as pretty-printed JSON:
+ *
+ *   --- STORY CLOSE RESULT ---
+ *   { ... every field, 2-space indented ... }
+ *   --- END RESULT ---
+ *
+ * That blob stays resident for the rest of the session and is re-read as
+ * cache every subsequent turn, yet the agent acts on only a handful of its
+ * fields (the machine contract is the separate terminal envelope). This helper
+ * routes the full detail to a temp log the agent can read on demand and emits
+ * a single structured summary line in its place.
+ *
+ * The escape hatch `MANDREL_RESULT_DETAIL=inline` restores the old inline
+ * pretty dump for interactive debugging.
+ */
+
+/** Env var that restores the legacy inline pretty dump when set to `inline`. */
+const RESULT_DETAIL_ENV = 'MANDREL_RESULT_DETAIL';
+
+/**
+ * Turn a human label (`STORY CLOSE RESULT`) into a filesystem-safe log
+ * basename fragment (`story-close-result`).
+ *
+ * @param {string} label
+ * @returns {string}
+ */
+function slugify(label) {
+  return (
+    String(label)
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '') || 'result'
+  );
+}
+
+/**
+ * The full detail block, byte-compatible with the legacy dump the hot-path
+ * scripts used to write to stdout — same markers, same pretty JSON — so a log
+ * a human opens reads exactly as the old inline dump did.
+ *
+ * @param {string} label
+ * @param {unknown} result
+ * @returns {string}
+ */
+function detailBlock(label, result) {
+  return `--- ${label} ---\n${JSON.stringify(result, null, 2)}\n--- END RESULT ---`;
+}
+
+/**
+ * Route a verbose result object off the agent's turn-resident stdout: write the
+ * full pretty detail to a temp log and emit a single-line structured summary in
+ * its place.
+ *
+ * @param {object} args
+ * @param {string} args.label Human label for the result (e.g. `STORY CLOSE RESULT`).
+ * @param {unknown} args.result The full result object; pretty-printed to the log.
+ * @param {Record<string, unknown>} [args.summary] The few fields the agent acts
+ *   on; serialized compactly onto the single summary line.
+ * @param {string|number} [args.scope] Disambiguating suffix for the log name
+ *   (typically the Story id) so concurrent deliveries don't clobber one file.
+ * @param {string} [args.logDir] Directory for the detail log. Defaults to
+ *   `<cwd>/temp/orchestration`.
+ * @param {typeof nodeFs} [args.fs] Filesystem seam (tests).
+ * @param {{ info: (m: string) => void }} [args.log] Logger seam (tests).
+ * @param {NodeJS.ProcessEnv} [args.env] Environment seam (tests).
+ * @returns {{ logPath: string|null, inline: boolean, error?: string }}
+ */
+export function emitTerseResult({
+  label,
+  result,
+  summary = {},
+  scope,
+  logDir,
+  fs = nodeFs,
+  log = Logger,
+  env = process.env,
+} = {}) {
+  const body = detailBlock(label, result);
+
+  // Escape hatch: restore the full inline pretty dump for interactive debugging.
+  if (String(env[RESULT_DETAIL_ENV] ?? '').toLowerCase() === 'inline') {
+    log.info?.(`\n${body}\n`);
+    return { logPath: null, inline: true };
+  }
+
+  const dir = logDir ?? path.join(process.cwd(), 'temp', 'orchestration');
+  const name = `${slugify(label)}${scope ? `-${scope}` : ''}.log`;
+
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    const logPath = path.join(dir, name);
+    fs.writeFileSync(logPath, `${body}\n`);
+    log.info?.(
+      `${label} · ${JSON.stringify(summary)} · full detail → ${logPath}`,
+    );
+    return { logPath, inline: false };
+  } catch (err) {
+    // Never lose detail: if the log write fails, fall back to the inline dump
+    // so the result is still recoverable from the transcript.
+    log.info?.(`\n${body}\n`);
+    return { logPath: null, inline: true, error: err?.message ?? String(err) };
+  }
+}