@dzhechkov/harness-core 0.8.32 → 0.8.34

package/src/release.ts

@@ -23,9 +23,11 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import type { Dirent } from 'node:fs';
-import { join } from 'node:path';
+import { join, relative } from 'node:path';
 
 import { discoverPackages, orderByDependencies } from './publish.js';
+import { planPackedInstallSmoke, judgePackedInstallSmoke } from './packed-install-smoke.js';
+import type { PackedInstallPlan, PackedInstallExecution } from './packed-install-smoke.js';
 
 /** The four HARD verify gates, in execution order. */
 export type ReleaseGateId = 'tests' | 'audit' | 'syntax' | 'smoke';
@@ -114,6 +116,15 @@ export interface GatePlan {
   readonly skips: readonly GateSkip[];
   /** Package names in the release set (dependency order). */
   readonly packages: readonly string[];
+  /**
+   * AM-7 (feature publish-sibling-drift-gate): the packed-install sub-plan, carried through so
+   * {@link classifyGateExecutions} can re-judge its `bin-version`/`bin-exists` steps through the
+   * SAME judge `dz publish` uses (`judgePackedInstallSmoke`: exit 0 AND non-empty stdout, AND the
+   * declared bin must exist post-install) instead of the generic exit-code-only check every other
+   * step gets. Without this, a silently no-op bin could pass `dz release` while `dz publish`
+   * refuses it — the two doors would not be equal, contradicting FR-6's own claim.
+   */
+  readonly packedInstallPlan?: PackedInstallPlan | undefined;
 }
 
 /** The CLI's record of running one exec step. */
@@ -131,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). */
@@ -303,6 +327,12 @@ export interface PlanReleaseGatesOptions {
   readonly auditTimeoutMs?: number | undefined;
   readonly syntaxTimeoutMs?: number | undefined;
   readonly smokeTimeoutMs?: number | undefined;
+  /**
+   * FR-6 (feature publish-sibling-drift-gate): real tmp dirs for the packed-install smoke,
+   * supplied by the CLI (planning stays pure — it never calls mkdtemp itself). Omitted ⇒ no
+   * packed-install steps are planned, byte-identical to the pre-feature behavior.
+   */
+  readonly packedInstall?: { readonly packDir: string; readonly installDir: string } | undefined;
 }
 
 /**
@@ -481,7 +511,50 @@ export function planReleaseGates(facts: readonly ReleasePackageFacts[], opts: Pl
     }
   }
 
-  return { steps, skips, packages: facts.map((f) => f.name) };
+  // FR-6 (feature publish-sibling-drift-gate): the packed-install smoke joins the SAME smoke
+  // gate `dz publish` runs (planPackedInstallSmoke, ADR-001 Decision 2) — so both doors apply
+  // the identical rule. Opt-in via `opts.packedInstall` (real tmp dirs, supplied by the CLI):
+  // omitted, this is byte-identical to the pre-feature plan, which every existing planner test
+  // relies on. Skipped entirely when nothing in the batch has a bin — packing siblings nobody
+  // will boot proves nothing a fresh `npm install` doesn't already cover elsewhere.
+  let packedInstallPlan: PackedInstallPlan | undefined;
+  if (opts.packedInstall !== undefined) {
+    const bins = facts.flatMap((f) =>
+      f.bins.map((b) => ({ pkg: f.name, binName: b.name, relPath: relative(f.dir, b.path) })),
+    );
+    if (bins.length > 0) {
+      const packages = facts.map((f) => ({ name: f.name, dir: f.dir, version: f.version }));
+      const smokePlan = planPackedInstallSmoke({
+        packages,
+        bins,
+        packDir: opts.packedInstall.packDir,
+        installDir: opts.packedInstall.installDir,
+      });
+      packedInstallPlan = smokePlan; // AM-7: kept for classifyGateExecutions's re-judge pass
+      for (const s of smokePlan.steps) {
+        const reason =
+          s.kind === 'pack'
+            ? `pack ${s.pkg} for the packed-install smoke — the tarball a consumer would actually receive`
+            : s.kind === 'install'
+              ? 'install every packed tarball together in a clean dir — out-of-batch siblings resolve from the registry, exactly like a fresh user'
+              : s.kind === 'bin-exists'
+                ? `bin "${s.binName}" must EXIST after the packed install (AM-8)`
+                : `bin "${s.binName}" must boot from the PACKED install (--version, exit 0, non-empty stdout)`;
+        steps.push({
+          id: `smoke:packed-install:${s.id}`,
+          gate: 'smoke',
+          pkg: s.pkg,
+          cmd: s.cmd,
+          cwd: s.cwd,
+          timeoutMs: s.timeoutMs,
+          reason,
+          kind: 'exec',
+        });
+      }
+    }
+  }
+
+  return { steps, skips, packages: facts.map((f) => f.name), ...(packedInstallPlan !== undefined ? { packedInstallPlan } : {}) };
 }
 
 /* ------------------------------------------------------------------ */
@@ -540,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):
@@ -559,6 +764,30 @@ export function classifyGateExecutions(
     if (e != null && typeof e.stepId === 'string') byId.set(e.stepId, e);
   }
 
+  // AM-7: `bin-exists`/`bin-version` packed-install steps are judged through
+  // `judgePackedInstallSmoke` — the SAME rule `dz publish` applies (exit 0 AND non-empty stdout,
+  // AND the declared bin must exist post-install) — instead of the generic exit-code-only check
+  // every other step gets. The generic loop below SKIPS these step ids; the judged verdict is
+  // folded into the 'smoke' gate's failures/passed count after the loop.
+  const packedInstallPlan = plan?.packedInstallPlan;
+  const packedInstallBinStepIds = new Set(
+    (packedInstallPlan?.steps ?? []).filter((s) => s.kind === 'bin-exists' || s.kind === 'bin-version').map((s) => `smoke:packed-install:${s.id}`),
+  );
+  let packedInstallVerdict: ReturnType<typeof judgePackedInstallSmoke> | undefined;
+  if (packedInstallPlan !== undefined) {
+    const prefix = 'smoke:packed-install:';
+    const translated: PackedInstallExecution[] = (executions ?? [])
+      .filter((e): e is GateExecution => e != null && typeof e.stepId === 'string' && e.stepId.startsWith(prefix))
+      .map((e) => ({
+        stepId: e.stepId.slice(prefix.length),
+        exitCode: e.exitCode,
+        stdout: e.stdout ?? '',
+        stderr: e.stderr ?? '',
+        ...(e.timedOut !== undefined ? { timedOut: e.timedOut } : {}),
+      }));
+    packedInstallVerdict = judgePackedInstallSmoke(packedInstallPlan, translated);
+  }
+
   const gates: GateResult[] = RELEASE_GATE_ORDER.map((gate) => {
     const gateSteps = (plan?.steps ?? []).filter((s) => s?.gate === gate);
     const gateSkips = (plan?.skips ?? []).filter((s) => s?.gate === gate);
@@ -567,6 +796,7 @@ export function classifyGateExecutions(
 
     for (const step of gateSteps) {
       try {
+        if (packedInstallBinStepIds.has(step.id)) continue; // judged separately below (AM-7)
         if (step.kind === 'synthetic-fail') {
           failures.push({ pkg: step.pkg, reason: step.reason, class: step.failClass ?? 'EXIT_NONZERO' });
           continue;
@@ -585,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;
         }
@@ -594,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;
@@ -609,6 +847,22 @@ export function classifyGateExecutions(
       }
     }
 
+    // AM-7: fold the packed-install bin verdicts (judged via judgePackedInstallSmoke, above) into
+    // the 'smoke' gate — the ONLY gate that ever plans packed-install steps.
+    if (gate === 'smoke' && packedInstallVerdict !== undefined) {
+      for (const bin of packedInstallVerdict.bins) {
+        if (bin.ok) {
+          passed += 1;
+        } else {
+          failures.push({
+            pkg: bin.pkg,
+            reason: `packed-install bin "${bin.binName}" ${bin.detail ?? 'failed'}`,
+            class: 'EXIT_NONZERO',
+          });
+        }
+      }
+    }
+
     const status: GateResult['status'] = failures.length > 0 ? 'fail' : passed > 0 ? 'pass' : 'skip';
     return { gate, status, passed, failures, skips: gateSkips };
   });
@@ -643,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. */

package/src/setup.ts

@@ -44,6 +44,77 @@ import {
 /** Memory backend type. */
 export type MemoryBackend = 'jsonl' | 'agentdb';
 
+/** Where a resolved setup memory backend came from (feature `setup-backend-from-config`). */
+export type MemoryBackendSource = 'flag' | 'config' | 'default' | 'default-unreadable' | 'disabled';
+
+/** Result of {@link resolveSetupMemoryBackend}. */
+export interface ResolvedSetupMemoryBackend {
+  readonly backend: MemoryBackend;
+  readonly source: MemoryBackendSource;
+  /** `true` only when an explicit `--memory jsonl` pulled an agentdb-configured project down to jsonl (FR-2). */
+  readonly downgraded: boolean;
+}
+
+/**
+ * FR-1/FR-2/FR-3 (feature `setup-backend-from-config`). Before this function, `runSetup` decided
+ * the backend as `opts.memory ?? 'jsonl'` — a repeat `dz setup --target claude-code` (no `--memory`)
+ * on an agentdb project silently reset it to jsonl and dropped `.dz/agentdb-writer.mjs` from
+ * `SessionStart` (AC-1, red-first). This is the ONE place that decides the backend for a run, so
+ * the config write, the printed source line, and the doctor cross-check can never disagree.
+ *
+ * - An explicit `--memory <x>` always wins (`source: 'flag'`) — including the one case that
+ *   DOWNGRADES an agentdb-configured project to jsonl (FR-2): `downgraded` is set so the caller can
+ *   warn and force the config write back in sync even without `--force`.
+ * - No flag, and `.dz/config.json` has a recognised `memory.backend` → that value, `source: 'config'`.
+ * - No flag, and no config (absent, unreadable, or an unrecognised backend value) → `jsonl`,
+ *   `source: 'default'` — the literal ticket command on an empty project (no change, named in
+ *   01_requirements.md "Что НЕ чинится").
+ */
+export function resolveSetupMemoryBackend(
+  projectRoot: string,
+  memoryOpt: MemoryBackend | undefined,
+  noMemory: boolean = false,
+): ResolvedSetupMemoryBackend {
+  // Lead edit after Codex review (findings 5/6): a config that EXISTS but cannot be read, or names an
+  // unknown backend, is not "no config" — its source is labeled so, and a later step never overwrites
+  // it silently. `--no-memory` disables memory entirely: no downgrade, no config rewrite.
+  let configuredBackend: MemoryBackend | undefined;
+  let configUnreadable = false;
+  const configPath = join(projectRoot, '.dz', 'config.json');
+  if (existsSync(configPath)) {
+    try {
+      const cfg = JSON.parse(readFileSync(configPath, 'utf-8')) as { memory?: { backend?: string } };
+      if (cfg.memory?.backend === 'agentdb') configuredBackend = 'agentdb';
+      else if (cfg.memory?.backend === 'jsonl') configuredBackend = 'jsonl';
+      else configUnreadable = true;
+    } catch {
+      configUnreadable = true;
+    }
+  }
+  if (noMemory) {
+    return { backend: memoryOpt ?? configuredBackend ?? 'jsonl', source: 'disabled', downgraded: false };
+  }
+  if (memoryOpt !== undefined) {
+    return { backend: memoryOpt, source: 'flag', downgraded: memoryOpt === 'jsonl' && configuredBackend === 'agentdb' };
+  }
+  if (configuredBackend !== undefined) {
+    return { backend: configuredBackend, source: 'config', downgraded: false };
+  }
+  return { backend: 'jsonl', source: configUnreadable ? 'default-unreadable' : 'default', downgraded: false };
+}
+
+/**
+ * FR-3: the human-readable "source" suffix, shared between `runSetup`'s own warning step and the
+ * CLI's printed `memory backend: …` line so the two texts can never drift apart.
+ */
+export function memoryBackendSourceLabel(source: MemoryBackendSource): string {
+  if (source === 'flag') return 'from --memory';
+  if (source === 'config') return 'from .dz/config.json';
+  if (source === 'default-unreadable') return 'default — .dz/config.json unreadable or names no known backend';
+  if (source === 'disabled') return 'memory disabled (--no-memory)';
+  return 'default — no .dz/config.json';
+}
+
 /** Setup options. */
 export interface SetupOptions {
   readonly projectRoot: string;
@@ -72,6 +143,12 @@ export interface SetupResult {
   readonly totalSteps: number;
   readonly completed: number;
   readonly skipped: number;
+  /** The memory backend this run actually used (feature `setup-backend-from-config`, FR-1). */
+  readonly memoryBackend: MemoryBackend;
+  /** Where {@link memoryBackend} came from — FR-3, also the `--json` field name. */
+  readonly memoryBackendSource: MemoryBackendSource;
+  /** `true` when an explicit `--memory jsonl` pulled an agentdb-configured project down (FR-2). */
+  readonly memoryBackendDowngraded: boolean;
 }
 
 /** A single setup step. */
@@ -809,7 +886,10 @@ function applyLegStepResult(opts: SetupOptions, backend: MemoryBackend): SetupSt
 export function runSetup(opts: SetupOptions): SetupResult {
   const steps: SetupStep[] = [];
   const dzDir = join(opts.projectRoot, '.dz');
-  const backend: MemoryBackend = opts.memory ?? 'jsonl';
+  // FR-1/FR-2/FR-3 (feature `setup-backend-from-config`): read BEFORE this run writes anything, so
+  // the comparison is against the PRIOR config, never the one this same call is about to produce.
+  const resolvedMemory = resolveSetupMemoryBackend(opts.projectRoot, opts.memory, opts.noMemory === true);
+  const backend: MemoryBackend = resolvedMemory.backend;
 
   // Step 0: Install agentdb + better-sqlite3 locally so the session-hook writer can import them
   // and share a native store with the MCP server. Best-effort — the writer self-degrades to a
@@ -835,14 +915,37 @@ export function runSetup(opts: SetupOptions): SetupResult {
     steps.push({ name: 'Create .dz directory', status: 'skipped', detail: 'already exists' });
   }
 
-  // Step 2: Write .dz/config.json
+  // Step 2: Write .dz/config.json. FR-2: a DOWNGRADE (explicit --memory jsonl over an
+  // agentdb-configured project) forces the write even without --force — "two truths after any
+  // setup coincide" means the config may not keep claiming agentdb once the caller has explicitly
+  // asked for jsonl.
   const configPath = join(dzDir, 'config.json');
   if (!existsSync(configPath) || opts.force) {
     writeFileSync(configPath, generateDzConfig(opts.target, opts.preset, backend));
     steps.push({ name: 'Write .dz/config.json', status: 'done', detail: `${backend} backend` });
+  } else if (resolvedMemory.downgraded) {
+    // Lead edit after Codex review (finding 3): a downgrade changes ONLY memory.backend — every other
+    // field the owner keeps in .dz/config.json survives; an unparsable file falls back to regeneration.
+    let rewritten = false;
+    try {
+      const cfg = JSON.parse(readFileSync(configPath, 'utf-8')) as Record<string, unknown>;
+      const memory = (cfg['memory'] !== null && typeof cfg['memory'] === 'object') ? (cfg['memory'] as Record<string, unknown>) : {};
+      cfg['memory'] = { ...memory, backend };
+      writeFileSync(configPath, JSON.stringify(cfg, null, 2) + '\n');
+      rewritten = true;
+    } catch { /* fall through to regeneration */ }
+    if (!rewritten) writeFileSync(configPath, generateDzConfig(opts.target, opts.preset, backend));
+    steps.push({ name: 'Write .dz/config.json', status: 'done', detail: `memory.backend → ${backend} (other fields kept)` });
   } else {
     steps.push({ name: 'Write .dz/config.json', status: 'skipped', detail: 'already exists (use --force)' });
   }
+  if (resolvedMemory.downgraded) {
+    steps.push({
+      name: 'Memory backend downgrade',
+      status: 'done',
+      detail: '⚠ memory backend downgraded agentdb → jsonl by --memory jsonl',
+    });
+  }
 
   // Step 3: Initialize session log
   const sessionsPath = join(dzDir, 'sessions.jsonl');
@@ -1219,5 +1322,8 @@ export function runSetup(opts: SetupOptions): SetupResult {
     totalSteps: steps.length,
     completed: steps.filter((s) => s.status === 'done').length,
     skipped: steps.filter((s) => s.status === 'skipped').length,
+    memoryBackend: resolvedMemory.backend,
+    memoryBackendSource: resolvedMemory.source,
+    memoryBackendDowngraded: resolvedMemory.downgraded,
   };
 }