@dzhechkov/harness-core 0.8.33 → 0.8.34

package/src/publish-sibling-drift.ts

@@ -28,10 +28,24 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { join, relative } from 'node:path';
+import { join, relative, isAbsolute } from 'node:path';
 
 export type SiblingDriftStatus = 'same' | 'drift' | 'unavailable';
 
+/**
+ * AM-6 (feature publish-gate-audit-durable): which mechanism produced BOTH sides' file inventory
+ * for this comparison — named on every result, never left implicit. `'npm-pack'`: the caller
+ * injected {@link DetectSiblingDriftOptions.localInventory} (the CLI's `npm pack --dry-run --json`
+ * via {@link parseNpmPackInventory}); the workspace side is exactly what npm will ship, and the
+ * published side is hashed by a FULL recursive walk of the already-unpacked tarball (AM-1 — the
+ * two sides must be symmetric: "every file npm put there" on one side, "every file npm will put
+ * there" on the other). `'readdir-approximation'`: no provider was injected — BOTH sides fall back
+ * to the pre-existing `dist`/`files`/`bin` walk ({@link shippedInventoryDirs}), which stays
+ * symmetric by construction (same function, same rules, both sides) but can miss a file
+ * `.npmignore` excludes or include one npm would never ship.
+ */
+export type InventorySource = 'npm-pack' | 'pnpm-pack' | 'readdir-approximation';
+
 export interface SiblingDriftResult {
   readonly name: string;
   readonly version: string;
@@ -42,6 +56,12 @@ export interface SiblingDriftResult {
   readonly missingExports: readonly string[];
   /** Present only when status === 'unavailable'. */
   readonly reason?: string;
+  /**
+   * AM-6: named per-result (not merely per-call) because `detectSiblingDrift` short-circuits to
+   * `'unavailable'` before ever reaching the hashing step for some entries — those still carry the
+   * source that WOULD have been used, so a reader never has to guess.
+   */
+  readonly inventorySource: InventorySource;
 }
 
 export interface FetchedPublished {
@@ -65,6 +85,21 @@ export interface DetectSiblingDriftOptions {
   /** Names being published in THIS batch — they publish fresh, so drift cannot be measured against them. */
   readonly batch: ReadonlySet<string>;
   readonly fetchPublished: FetchPublished;
+  /**
+   * FR-3 (feature publish-gate-audit-durable): the LOCAL (workspace) package's shipped-file
+   * inventory, asked from npm instead of approximated by walking `dist`/`files`/`bin` by hand —
+   * `.npmignore` and nested ignore rules make the hand-rolled walk wrong in both directions (a file
+   * npm will never ship can still be read off disk, producing a false drift). No production default
+   * lives in THIS module — core stays pure (never spawns `npm`, per the core-boundary import
+   * ratchet). The CLI runs `npm pack --dry-run --json` and hands the stdout to
+   * {@link parseNpmPackInventory}, then passes the resulting closure here; a caller that injects
+   * nothing (`undefined`) makes `detectSiblingDrift` fall back to the named
+   * `'readdir-approximation'` {@link InventorySource} on BOTH sides (AM-1) — never a silent "no
+   * drift".
+   */
+  readonly localInventory?: LocalInventory;
+  /** Label for the injected provider's source (default `'npm-pack'`); the CLI passes `'pnpm-pack'` for a packed tree. */
+  readonly localInventorySource?: InventorySource;
 }
 
 function listFilesRecursive(root: string, dir: string): string[] {
@@ -83,6 +118,120 @@ function sha256(data: string | Buffer): string {
   return createHash('sha256').update(data).digest('hex');
 }
 
+// ── FR-3 (feature publish-gate-audit-durable): ask npm, don't approximate ──────────────────────
+
+/** The exact set of relative paths `npm pack` will ship for a package — no `.npmignore` guessing. */
+export interface PackInventory {
+  readonly paths: readonly string[];
+}
+
+/** `npm pack --dry-run --json` could not be run or answered in a shape this code cannot use. */
+export interface PackInventoryUnavailable {
+  readonly unavailable: string;
+}
+
+/**
+ * Lead fix after the fix-round's live dry-run (2026-09-14 01:02): the workspace side PACKED BY THE
+ * LIVE TRANSPORT (`pnpm pack`) and unpacked into `packedDir`. pnpm synthesises a LICENSE from the
+ * workspace root into the tarball of a package whose own tree has none; `npm pack --dry-run --json`
+ * never lists that file, so a `paths` inventory read every such sibling as "LICENSE only in the
+ * published copy" — 2 false drifts (harness-presets, scout) on a tree unchanged since publication.
+ * A packed tree is hashed by the SAME full walk as the published side, symmetric by construction.
+ */
+export interface PackedTree {
+  readonly packedDir: string;
+}
+
+export type LocalInventoryResult = PackInventory | PackedTree | PackInventoryUnavailable;
+
+/** Ask what npm would ship for the package rooted at `dir`. Injected in tests (no subprocess). */
+export type LocalInventory = (dir: string) => LocalInventoryResult;
+
+/**
+ * C-1/AM-4: `npm pack --dry-run --json` is a real subprocess call — the CLI caches its result per
+ * absolute directory for the lifetime of ONE `dz publish` run (not per package being checked), so
+ * a run that checks the same sibling from more than one dependent package packs it only once. Core
+ * itself never runs the subprocess or owns the cache (core-boundary import ratchet) — this parser
+ * is the pure half only.
+ *
+ * Parses `npm pack --dry-run --json`'s stdout (an array with one element; `files[]` holds
+ * `{path,size,mode}` per shipped path, plus `integrity`/`shasum`/`entryCount`) into the exact set of
+ * relative paths npm intends to ship, honouring `.npmignore`/`files`/default-ignore exactly the way
+ * a real `npm publish` would. A failure to run, parse, or make sense of the shape — including a
+ * malformed individual `files[]` element (AM-5: a corrupt entry is a reason to say the WHOLE
+ * inventory is untrustworthy, never a file to silently drop) — is `{ unavailable: reason }`: an
+ * input this gate cannot read is a reason to say so, never a silent "nothing to compare".
+ */
+export function parseNpmPackInventory(stdout: string): LocalInventoryResult {
+  try {
+    const parsed: unknown = JSON.parse(stdout);
+    const entry = Array.isArray(parsed) ? (parsed[0] as unknown) : undefined;
+    const files = entry !== null && typeof entry === 'object' ? (entry as Record<string, unknown>)['files'] : undefined;
+    if (!Array.isArray(files)) return { unavailable: 'npm pack --dry-run --json returned no files[] array' };
+    // AM-5 (Codex round-1 finding 6, medium): a malformed element used to be `.filter()`ed out
+    // silently — a `files[]` entry npm itself always shapes as `{path,size,mode}` should never fail
+    // to parse; if one DOES (missing/non-string `path`, or a non-object element), that is a signal
+    // this output cannot be trusted, not a single file to quietly drop from the comparison. Say so.
+    const paths: string[] = [];
+    for (let i = 0; i < files.length; i++) {
+      const f = files[i];
+      if (f === null || typeof f !== 'object') {
+        return { unavailable: `npm pack --dry-run --json files[${i}] is not an object (got ${JSON.stringify(f)})` };
+      }
+      const path = (f as Record<string, unknown>)['path'];
+      if (typeof path !== 'string' || path === '') {
+        return { unavailable: `npm pack --dry-run --json files[${i}].path is missing or not a non-empty string (got ${JSON.stringify(path)})` };
+      }
+      paths.push(path);
+    }
+    return { paths };
+  } catch (err) {
+    return { unavailable: `npm pack --dry-run --json output could not be parsed: ${(err as Error).message.split('\n')[0]}` };
+  }
+}
+
+/** Hash exactly the paths `npm pack` names (package.json normalized separately, as {@link hashTree} does). */
+/**
+ * Codex round-2 (2026-09-14) new findings 1+2: a listed path that is absent, a directory, absolute,
+ * or that climbs out of `dir` via `..` used to be SKIPPED silently — a comparison over a listing
+ * the tree does not match is not a comparison, it is `unavailable`; and an inventory must never
+ * read outside the package directory. Thrown here, turned into an `unavailable` result by the caller.
+ */
+class InventoryListingError extends Error {}
+
+function hashTreeFromPaths(dir: string, paths: readonly string[], manifest: Record<string, unknown>): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const rel of paths) {
+    if (rel === 'package.json') continue; // normalized below, not hashed raw
+    if (isAbsolute(rel) || rel.split(/[\\/]/).includes('..')) {
+      throw new InventoryListingError(`inventory path "${rel}" is absolute or leaves the package directory`);
+    }
+    const abs = join(dir, rel);
+    if (!existsSync(abs)) throw new InventoryListingError(`inventory path "${rel}" does not exist in the workspace copy`);
+    if (statSync(abs).isDirectory()) throw new InventoryListingError(`inventory path "${rel}" is a directory, not a file`);
+    map.set(rel, sha256(readFileSync(abs)));
+  }
+  map.set('package.json', sha256(normalizedPackageJsonText(manifest)));
+  return map;
+}
+
+/**
+ * AM-1: hash EVERY file under `dir` (the already-unpacked published tarball) — the literal "full
+ * recursive walk of what npm put there" the amendment names, used ONLY as the symmetric partner to
+ * {@link hashTreeFromPaths} (i.e. only when a `localInventory` provider is injected). `dir` here is
+ * always an extracted tarball, never the workspace tree, so there is no `.npmignore` to consult:
+ * everything that exists on disk is, by construction, exactly what npm shipped.
+ */
+function hashTreeFull(dir: string, manifest: Record<string, unknown>): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const rel of listFilesRecursive(dir, dir)) {
+    if (rel === 'package.json') continue; // normalized below, not hashed raw
+    map.set(rel, sha256(readFileSync(join(dir, rel))));
+  }
+  map.set('package.json', sha256(normalizedPackageJsonText(manifest)));
+  return map;
+}
+
 /**
  * package.json PARSED and validated. `null` (never `undefined`) means "this side cannot be built
  * at all" — AM-3: a missing or unparseable manifest on EITHER side must surface as `unavailable`,
@@ -208,6 +357,9 @@ function missingExportNames(publishedDir: string, workspaceDir: string): string[
 export function detectSiblingDrift(opts: DetectSiblingDriftOptions): SiblingDriftResult[] {
   const results: SiblingDriftResult[] = [];
   const seen = new Set<string>();
+  // AM-6: named ONCE per call — every result below (including the short-circuited `unavailable`
+  // ones) carries the source that is or would have been used for this comparison.
+  const inventorySource: InventorySource = opts.localInventory !== undefined ? (opts.localInventorySource ?? 'npm-pack') : 'readdir-approximation';
   // AM-3: `optionalDependencies` ships and pins EXACTLY like `dependencies`/`peerDependencies` —
   // checking only the first two let a stale optional sibling through untouched (round-1 finding 3).
   const entries = [
@@ -233,6 +385,7 @@ export function detectSiblingDrift(opts: DetectSiblingDriftOptions): SiblingDrif
         changedFiles: [],
         missingExports: [],
         reason: `${dep} is declared workspace:-protocol but is not a known workspace package`,
+        inventorySource,
       });
       continue;
     }
@@ -246,6 +399,7 @@ export function detectSiblingDrift(opts: DetectSiblingDriftOptions): SiblingDrif
         changedFiles: [],
         missingExports: [],
         reason: `could not fetch ${dep}@${version} from the registry (network unavailable or the version was not found)`,
+        inventorySource,
       });
       continue;
     }
@@ -264,12 +418,62 @@ export function detectSiblingDrift(opts: DetectSiblingDriftOptions): SiblingDrif
         changedFiles: [],
         missingExports: [],
         reason: `${dep}@${version}: package.json in ${side} is missing or not valid JSON — cannot compare`,
+        inventorySource,
       });
       continue;
     }
 
-    const publishedHashes = hashTree(fetched.dir, publishedManifest);
-    const workspaceHashes = hashTree(workspaceDir, workspaceManifest);
+    // FR-3/AM-1: the LOCAL package's inventory comes from npm, not from a hand-rolled dist/files/bin
+    // walk — `.npmignore` (and nested ignore rules) can exclude a file this gate would otherwise walk
+    // straight into, producing a false drift about a file npm was never going to ship. AM-1 (Codex
+    // review, round-1 finding 3, high): the two sides must stay SYMMETRIC. With a provider injected,
+    // the workspace side is npm's OWN shipped-path list; the published side must then be hashed by a
+    // FULL recursive walk of the already-unpacked tarball (every file npm actually put there —
+    // README/LICENSE included, since npm auto-packs those regardless of `files`), not the narrower
+    // `dist`/`files`/`bin` approximation `hashTree` uses — that approximation would silently OMIT an
+    // auto-packed README/LICENSE from the published side while the workspace side (via real `npm
+    // pack`) correctly includes them, reading as a false "only in workspace" drift. WITHOUT a
+    // provider, core has no way to ask npm on either side, so it degrades to the SAME approximation
+    // on BOTH sides (symmetry preserved, just cruder) — a named approximation, never a subprocess.
+    let workspaceHashes: Map<string, string>;
+    let publishedHashes: Map<string, string>;
+    if (opts.localInventory !== undefined) {
+      const localResult = opts.localInventory(workspaceDir);
+      if ('unavailable' in localResult) {
+        results.push({
+          name: dep,
+          version,
+          status: 'unavailable',
+          changedFiles: [],
+          missingExports: [],
+          reason: `${dep}@${version}: local package inventory unavailable (${localResult.unavailable})`,
+          inventorySource,
+        });
+        continue;
+      }
+      try {
+        workspaceHashes = 'packedDir' in localResult
+          ? hashTreeFull(localResult.packedDir, workspaceManifest)
+          : hashTreeFromPaths(workspaceDir, localResult.paths, workspaceManifest);
+      } catch (err) {
+        if (!(err instanceof InventoryListingError)) throw err;
+        results.push({
+          name: dep,
+          version,
+          status: 'unavailable',
+          changedFiles: [],
+          missingExports: [],
+          reason: `${dep}@${version}: local package inventory unusable (${err.message})`,
+          inventorySource,
+        });
+        continue;
+      }
+      publishedHashes = hashTreeFull(fetched.dir, publishedManifest);
+    } else {
+      workspaceHashes = hashTree(workspaceDir, workspaceManifest);
+      publishedHashes = hashTree(fetched.dir, publishedManifest);
+    }
+
     const allKeys = new Set<string>([...publishedHashes.keys(), ...workspaceHashes.keys()]);
     const changed: string[] = [];
     for (const key of allKeys) {
@@ -278,7 +482,7 @@ export function detectSiblingDrift(opts: DetectSiblingDriftOptions): SiblingDrif
     changed.sort();
 
     if (changed.length === 0) {
-      results.push({ name: dep, version, status: 'same', changedFiles: [], missingExports: [] });
+      results.push({ name: dep, version, status: 'same', changedFiles: [], missingExports: [], inventorySource });
     } else {
       results.push({
         name: dep,
@@ -286,6 +490,7 @@ export function detectSiblingDrift(opts: DetectSiblingDriftOptions): SiblingDrif
         status: 'drift',
         changedFiles: changed,
         missingExports: missingExportNames(fetched.dir, workspaceDir),
+        inventorySource,
       });
     }
   }

package/src/release.ts

@@ -142,6 +142,19 @@ export interface GateFailure {
   readonly pkg?: string | undefined;
   readonly reason: string;
   readonly class: ReleaseFailureClass;
+  /**
+   * Feature release-gate-output-tail (AM-4): the last non-empty lines of the step's stdout and
+   * stderr, KEPT SEPARATE — each stream through {@link outputTail} on its own, never merged —
+   * so a reader can tell which stream a line came from. Set for `tests`/`syntax`/`smoke`
+   * EXIT_NONZERO/TIMEOUT failures; absent for `audit` (its own detail line already summarizes)
+   * and for failures with no execution record (e.g. UNEXECUTED_STEP).
+   *
+   * Scope honesty (AM-4): the two streams are captured independently, so a printed/issued
+   * `stdout:`/`stderr:` pair does NOT reconstruct the chronological interleaving of the two
+   * streams as the process actually emitted them — only each stream's own tail order is
+   * preserved. Documented in the CLI README (AM-8), not silently implied.
+   */
+  readonly tails?: { readonly stdout: string; readonly stderr: string };
 }
 
 /** Per-gate verdict. `skip` = the gate had nothing to execute (still not a pass). */
@@ -600,6 +613,138 @@ function firstLine(...chunks: readonly unknown[]): string {
   return '';
 }
 
+/**
+ * Strip ANSI/VT100 escape sequences (colour codes, cursor moves, OSC hyperlinks) so pattern
+ * matching sees the plain text a human reads on a non-colour terminal. AM-2/AM-1 precondition:
+ * `testsFailureDetail` and the issue-body redaction both run this FIRST, before any regex tries
+ * to recognise a runner's summary/FAIL lines or a secret value — a coloured `FAIL` token (e.g.
+ * `\x1b[31mFAIL\x1b[0m`) must still match `/^FAIL\b/` once stripped.
+ */
+// eslint-disable-next-line no-control-regex -- deliberately matching raw ESC control bytes
+function stripAnsi(s: string): string {
+  return s
+    .replace(/\x1B\][^\x07\x1B]*(?:\x07|\x1B\\)/g, '') // OSC …  BEL | OSC … ST
+    .replace(/\x1B[[()#;?]*[0-9]*(?:;[0-9]*)*[a-zA-Z@]/g, ''); // CSI/other short escapes
+}
+
+/**
+ * Feature release-gate-output-tail (FR-1, amended AM-2): a one-line-ish detail for a
+ * `tests`/`syntax`/`smoke` EXIT_NONZERO/TIMEOUT failure that names the ACTUAL failure — not
+ * just the first output line, which for `pnpm test`/vitest is routinely an unrelated
+ * vite/esbuild deprecation warning (MEASURED 2026-09-13 16:05/18:52).
+ *
+ * AM-2: ANSI escapes are stripped FIRST (a coloured runner must match the same patterns as a
+ * plain one). Recognised shapes, collected in this priority order and joined:
+ * 1. vitest summary lines (`Tests …`, `Test Files …`);
+ * 2. up to 5 `FAIL …` / `× …` / `❯ …` lines (failing test names/paths);
+ * 3. node:test (TAP) lines: `not ok N - name` and `# fail N`.
+ *
+ * If NONE of the above is present (a non-vitest, non-TAP failure, or empty output), fall back
+ * to the prior `firstLine` behavior, marked `(no test-runner summary recognised)` so a reader
+ * knows the detail is a guess, not a parsed summary — UNLESS `firstLine` itself is empty (no
+ * output at all), in which case the mark would manufacture a synthetic line where none existed
+ * and is withheld. Capped at 600 chars — a detail line, not a dump.
+ */
+export function testsFailureDetail(stdout: unknown, stderr: unknown): string {
+  const all = stripAnsi(`${stdout == null ? '' : String(stdout)}\n${stderr == null ? '' : String(stderr)}`);
+  const lines = all
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
+  const summaryLines = lines.filter((l) => /^(Tests|Test Files)\b/.test(l));
+  const failLines = lines.filter((l) => /^(FAIL\b|×|❯)/.test(l)).slice(0, 5);
+  const tapNotOkLines = lines.filter((l) => /^not ok \d+/.test(l)).slice(0, 5);
+  const tapFailCountLines = lines.filter((l) => /^# fail \d+/i.test(l));
+  const parts = [...summaryLines, ...failLines, ...tapNotOkLines, ...tapFailCountLines];
+  if (parts.length === 0) {
+    // lead r2: the fallback is derived from the ANSI-STRIPPED text, never the raw stream
+    const fl = lines[0] ?? '';
+    return fl.length === 0 ? '' : `${fl.slice(0, 200)} (no test-runner summary recognised)`;
+  }
+  return parts.join(' — ').slice(0, 600);
+}
+
+/** Truncate `s` to at most `maxBytes` UTF-8 bytes, never splitting a multi-byte character. */
+function truncateToBytes(s: string, maxBytes: number): string {
+  if (maxBytes <= 0) return '';
+  const buf = Buffer.from(s, 'utf-8');
+  if (buf.length <= maxBytes) return s;
+  let end = maxBytes;
+  // back off while the next byte is a UTF-8 continuation byte (10xxxxxx)
+  while (end > 0 && (buf[end]! & 0xc0) === 0x80) end -= 1;
+  return buf.subarray(0, end).toString('utf-8');
+}
+
+/**
+ * Feature release-gate-output-tail (FR-2/FR-3, amended AM-3): the last non-empty lines of ONE
+ * stream (call separately for stdout and stderr — AM-4), bounded on BOTH axes (line count and
+ * byte size) so a runaway suite cannot blow up a report or an issue body.
+ *
+ * AM-3 bounds, each an explicit branch rather than an emergent `Array.slice(-0)` accident
+ * (`slice(-0)` returns the WHOLE array, not `[]` — the pre-amendment bug):
+ * - `maxLines <= 0` → `''`; `maxBytes <= 0` → `''`.
+ * - Whole-line selection: lines are pulled from the END while the running BYTE total (each
+ *   line's UTF-8 byte length plus its joining `\n`) stays `<= maxBytes` — never a partial line.
+ * - A single most-recent line that ALONE exceeds `maxBytes` is truncated at a UTF-8 CHARACTER
+ *   boundary (never splitting a multi-byte codepoint) and marked `… (line truncated)`.
+ *
+ * Empty/whitespace-only output → `''` (never a synthetic line).
+ */
+export function outputTail(stdout: unknown, stderr: unknown, maxLines = 40, maxBytes = 8192): string {
+  if (maxLines <= 0 || maxBytes <= 0) return '';
+  const all = `${stdout == null ? '' : String(stdout)}\n${stderr == null ? '' : String(stderr)}`;
+  const nonEmpty = all
+    .split('\n')
+    .map((l) => l.replace(/\r$/, ''))
+    .filter((l) => l.trim().length > 0);
+  const tailLines = nonEmpty.slice(-maxLines);
+  if (tailLines.length === 0) return '';
+
+  const lastLine = tailLines[tailLines.length - 1]!;
+  if (Buffer.byteLength(lastLine, 'utf-8') > maxBytes) {
+    // lead r2: the marker lives INSIDE the byte budget, so the returned text never exceeds maxBytes
+    const marker = '… (line truncated)';
+    const room = Math.max(0, maxBytes - Buffer.byteLength(marker, 'utf-8'));
+    return `${truncateToBytes(lastLine, room)}${marker}`;
+  }
+
+  const selected: string[] = [];
+  let bytes = 0;
+  for (let i = tailLines.length - 1; i >= 0; i--) {
+    const line = tailLines[i]!;
+    const lineBytes = Buffer.byteLength(line, 'utf-8');
+    const joinerBytes = selected.length > 0 ? 1 : 0; // the '\n' this line adds once prepended
+    if (bytes + lineBytes + joinerBytes > maxBytes) break;
+    selected.unshift(line);
+    bytes += lineBytes + joinerBytes;
+  }
+  return selected.join('\n');
+}
+
+/**
+ * Feature release-gate-output-tail (AM-1): redact secret-shaped substrings before ANY tail text
+ * reaches a GitHub issue body. Patterns, each independently redacted:
+ * - `token`/`secret`/`password` (case-insensitive) as a `key: value` or `key=value` pair — the
+ *   KEY survives, only the value is replaced;
+ * - `Bearer <token>` HTTP auth headers;
+ * - vendor-prefixed tokens: `npm_…`, `ghp_…`, `sk-…`, `AKIA…`;
+ * - long opaque strings (base64/hex-ish, `[A-Za-z0-9+/=]{32,}`) that look like a key/secret even
+ *   without a recognisable prefix.
+ * Order matters: prefixed/labelled patterns run BEFORE the generic long-opaque-string pattern so
+ * a `Bearer …` token is redacted as a whole rather than surviving as a shorter unlabelled blob.
+ */
+export function redactSecrets(text: string): string {
+  let out = text;
+  out = out.replace(/\bBearer\s+\S+/gi, 'Bearer [redacted]');
+  out = out.replace(/\bnpm_[A-Za-z0-9]+/g, '[redacted]');
+  out = out.replace(/\bghp_[A-Za-z0-9]+/g, '[redacted]');
+  out = out.replace(/\bsk-[A-Za-z0-9]+/g, '[redacted]');
+  out = out.replace(/\bAKIA[A-Za-z0-9]+/g, '[redacted]');
+  out = out.replace(/\b(token|secret|password)(\s*[:=]\s*)(\S+)/gi, '$1$2[redacted]');
+  out = out.replace(/\b[A-Za-z0-9+/=]{32,}\b/g, '[redacted]');
+  return out;
+}
+
 /**
  * Merge plan + executions into the {@link ReleaseVerdict} — the single fail-closed decision
  * point (ADR load-bearing property):
@@ -670,6 +815,9 @@ export function classifyGateExecutions(
             pkg: step.pkg,
             reason: `timed out after ${step.timeoutMs}ms: ${step.cmd}`,
             class: gate === 'smoke' ? 'SMOKE_TIMEOUT' : 'TIMEOUT',
+            // FR-3 / AM-4: a killed-by-timeout step still has whatever it printed before the
+            // kill — captured per-stream, never merged (see GateFailure.tails doc comment).
+            tails: { stdout: outputTail(exec.stdout, undefined), stderr: outputTail(undefined, exec.stderr) },
           });
           continue;
         }
@@ -679,10 +827,15 @@ export function classifyGateExecutions(
             const detail = auditDetailLine(exec.stdout, exec.stderr);
             failures.push({ pkg: step.pkg, reason: `${reason}${detail ? ` — ${detail}` : ''}`, class: cls });
           } else {
+            // FR-1: for tests/syntax/smoke, name the ACTUAL failure (summary + failing tests),
+            // not just the first output line — see testsFailureDetail's doc comment for why.
+            const detail = testsFailureDetail(exec.stderr, exec.stdout);
             failures.push({
               pkg: step.pkg,
-              reason: `exit ${String(exec.exitCode)}: ${step.cmd}${firstLine(exec.stderr, exec.stdout) ? ` — ${firstLine(exec.stderr, exec.stdout)}` : ''}`,
+              reason: `exit ${String(exec.exitCode)}: ${step.cmd}${detail ? ` — ${detail}` : ''}`,
               class: 'EXIT_NONZERO',
+              // AM-4: per-stream tails, never merged — see GateFailure.tails doc comment.
+              tails: { stdout: outputTail(exec.stdout, undefined), stderr: outputTail(undefined, exec.stderr) },
             });
           }
           continue;
@@ -744,32 +897,125 @@ export interface FailureIssueContext {
   readonly repo?: string | undefined;
 }
 
+/** AM-1: total issue-body cap — a courier never balloons into an unpostable payload. */
+const MAX_ISSUE_BODY_BYTES = 60 * 1024;
+
+/**
+ * AM-5: fence `text` so the payload can never prematurely close the code block — the fence is
+ * N+1 backticks, where N is the LONGEST run of consecutive backticks already present in `text`.
+ * Every content line (and the fence itself) carries `indent` so a multi-line block renders as a
+ * continuation of the enclosing markdown list item, not as a sibling paragraph.
+ */
+function fencedBlock(text: string, indent = '    '): string[] {
+  const runs = text.match(/`+/g) ?? [];
+  const longestRun = runs.reduce((m, r) => Math.max(m, r.length), 0);
+  // GFM needs >= 3 backticks for a FENCED (block) code fence — fewer reads as inline code.
+  const fence = '`'.repeat(Math.max(3, longestRun + 1));
+  const contentLines = text.split('\n').map((l) => `${indent}${l}`);
+  return [`${indent}${fence}`, ...contentLines, `${indent}${fence}`];
+}
+
 /**
  * gh-2.4-safe `gh issue create` payload (only `--title`/`--body` are assumed downstream).
  * Pure + deterministic for a fixed verdict — the issue is the verdict's echo, never its judge.
+ *
+ * AM-1/AM-4/AM-5: every tail is (a) redacted (secret-shaped substrings replaced — see
+ * {@link redactSecrets}) and ANSI-stripped BEFORE it is ever considered for the body; (b) shown
+ * per STREAM, labelled `stdout:`/`stderr:` — AM-4's scope note applies here too: the two labelled
+ * blocks do NOT reconstruct chronological interleaving between the streams; (c) fenced so the
+ * payload cannot break out of its code block; (d) the WHOLE body is capped at
+ * {@link MAX_ISSUE_BODY_BYTES} — when it would exceed the cap, every tail is shrunk EVENLY
+ * (byte-proportional), not by dropping some tails whole while keeping others untouched.
  */
 export function buildFailureIssue(verdict: ReleaseVerdict, ctx: FailureIssueContext = {}): { title: string; body: string } {
   const failed = verdict.gates.filter((g) => g.status === 'fail').map((g) => g.gate);
   const title = `dz release: gate failure — ${failed.length > 0 ? failed.join(', ') : 'nothing verified'}`;
-  const lines: string[] = [
-    `Verified release blocked at ${verdict.timestamp}.`,
-    '',
-    ...(ctx.invocation ? [`Invocation: \`${ctx.invocation}\``, ''] : []),
-    ...(ctx.repo ? [`Repo: ${ctx.repo}`, ''] : []),
-    '## Gate verdict',
-    '',
-  ];
+
+  interface TailRef {
+    readonly stream: 'stdout' | 'stderr';
+    text: string;
+    readonly rawBytes: number;
+  }
+  const refsByFailure = new Map<GateFailure, TailRef[]>();
   for (const g of verdict.gates) {
-    const icon = g.status === 'pass' ? '✓' : g.status === 'fail' ? '✗' : '○';
-    lines.push(`- ${icon} **${g.gate}** — ${g.status} (${g.passed} passed, ${g.failures.length} failed, ${g.skips.length} skipped)`);
-    for (const f of g.failures) lines.push(`  - [${f.class}] ${f.pkg ? `${f.pkg}: ` : ''}${f.reason}`);
+    for (const f of g.failures) {
+      if (f.tails === undefined) continue;
+      const refs: TailRef[] = [];
+      for (const stream of ['stdout', 'stderr'] as const) {
+        const raw = f.tails[stream];
+        if (raw.length === 0) continue;
+        const clean = redactSecrets(stripAnsi(raw));
+        refs.push({ stream, text: clean, rawBytes: Buffer.byteLength(clean, 'utf-8') });
+      }
+      if (refs.length > 0) refsByFailure.set(f, refs);
+    }
   }
-  if (verdict.skipped.length > 0) {
-    lines.push('', '## Skipped (honestly reported, never counted as passed)', '');
-    for (const s of verdict.skipped) lines.push(`- [${s.class}] ${s.pkg}: ${s.reason}`);
+
+  const render = (): string => {
+    const lines: string[] = [
+      `Verified release blocked at ${verdict.timestamp}.`,
+      '',
+      ...(ctx.invocation ? [`Invocation: \`${redactSecrets(stripAnsi(ctx.invocation)).replace(/`/g, "'")}\``, ''] : []),
+      ...(ctx.repo ? [`Repo: ${ctx.repo}`, ''] : []),
+      '## Gate verdict',
+      '',
+    ];
+    for (const g of verdict.gates) {
+      const icon = g.status === 'pass' ? '✓' : g.status === 'fail' ? '✗' : '○';
+      lines.push(`- ${icon} **${g.gate}** — ${g.status} (${g.passed} passed, ${g.failures.length} failed, ${g.skips.length} skipped)`);
+      for (const f of g.failures) {
+        // lead r2 (HIGH): the reason is output-derived free text — strip ANSI and redact it like a tail
+        lines.push(`  - [${f.class}] ${f.pkg ? `${f.pkg}: ` : ''}${redactSecrets(stripAnsi(f.reason))}`);
+        // FR-2 / AM-4 / AM-5: a labelled, fenced block per non-empty stream — the issue is the
+        // echo of the verdict, so a reader can see the actual failing output without re-running.
+        for (const ref of refsByFailure.get(f) ?? []) {
+          lines.push(`    ${ref.stream}:`, ...fencedBlock(ref.text));
+        }
+      }
+    }
+    if (verdict.skipped.length > 0) {
+      lines.push('', '## Skipped (honestly reported, never counted as passed)', '');
+      for (const s of verdict.skipped) lines.push(`- [${s.class}] ${s.pkg}: ${s.reason}`);
+    }
+    lines.push(
+      '',
+      `Blocked by: ${verdict.blockedBy.join('; ')}`,
+      '',
+      '_Auto-created by `dz release` (best-effort; the release verdict is independent of this issue)._',
+    );
+    return lines.join('\n');
+  };
+
+  let body = render();
+  let bodyBytes = Buffer.byteLength(body, 'utf-8');
+
+  if (bodyBytes > MAX_ISSUE_BODY_BYTES && refsByFailure.size > 0) {
+    const allRefs = [...refsByFailure.values()].flat();
+    let overage = bodyBytes - MAX_ISSUE_BODY_BYTES;
+    // Bounded iteration: each pass's cut is based on the LATEST measured overage (markup like
+    // "… (truncated)" adds a few bytes back per ref, so one pass rarely lands exactly) — a few
+    // passes converge; the safety net below closes any pathological remainder.
+    for (let pass = 0; pass < 3 && overage > 0; pass++) {
+      const perRefCut = Math.ceil(overage / allRefs.length);
+      for (const ref of allRefs) {
+        const targetBytes = Math.max(0, ref.rawBytes - perRefCut);
+        if (Buffer.byteLength(ref.text, 'utf-8') > targetBytes) {
+          ref.text = `${truncateToBytes(ref.text, targetBytes)}… (truncated)`;
+        }
+      }
+      body = render();
+      bodyBytes = Buffer.byteLength(body, 'utf-8');
+      overage = bodyBytes - MAX_ISSUE_BODY_BYTES;
+    }
+    // Safety net: a pathological shape (a huge non-tail skeleton, tiny/no tails) can still exceed
+    // the cap after every tail is wiped — hard-truncate the whole body as the last resort so the
+    // cap is an INVARIANT, never a best-effort.
+    if (bodyBytes > MAX_ISSUE_BODY_BYTES) {
+      body = `${truncateToBytes(body, MAX_ISSUE_BODY_BYTES - 20)}\n… (truncated)`;
+    }
   }
-  lines.push('', `Blocked by: ${verdict.blockedBy.join('; ')}`, '', '_Auto-created by `dz release` (best-effort; the release verdict is independent of this issue)._');
-  return { title, body: lines.join('\n') };
+
+  return { title, body };
 }
 
 /** Short, bounded release notes from injected `git log --oneline`-style lines. */