@dzhechkov/harness-core 0.8.32 → 0.8.34

package/src/embed-socket-path.ts

@@ -0,0 +1,113 @@
+/**
+ * embed-socket-short-path (feature, ADR-001 D4-A follow-on to `setup-installs-apply-leg`).
+ *
+ * The APPLY-leg daemon binds a unix domain socket at `<projectRoot>/.dz/embed.sock`. Unix sockets
+ * carry a hard platform limit on `sun_path` — 108 bytes on Linux, 104 on macOS, NUL included — and
+ * `Buffer.byteLength`, not `.length`, is the right measure (a multi-byte path component under a
+ * deep, non-ASCII-free checkout costs more bytes than characters). Past that limit `listen()` fails
+ * while everything else about the daemon (deps resolved, model loaded, patterns read) looks fine —
+ * so a deeply nested project got a daemon that logged "ready" and a hook/doctor that both reported
+ * ABSENT, three consumers agreeing on a wrong answer for three different reasons.
+ *
+ * This module is the ONE resolver all three consumers use:
+ *   - the generated daemon ({@link "./apply-leg.js".embedDaemonSource}) — as inlined TEXT, since a
+ *     template string cannot `import` a compiled module (apply-leg-twins.test.ts pins the copies);
+ *   - the generated recall hook ({@link "./apply-leg.js".recallHookSource}) — same inlining;
+ *   - `dz doctor` (`operations.ts`) — a real `import`, since doctor runs compiled code.
+ *
+ * A safety margin (100, not 108/104) is deliberate: it leaves room for the NUL terminator and for
+ * platform differences without needing to fork the threshold per-OS.
+ *
+ * @packageDocumentation
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+/**
+ * Byte-length ceiling this module resolves under, measured via `Buffer.byteLength`. Chosen as a
+ * safety margin below the tightest real platform limit (macOS `sun_path` = 104 bytes incl. NUL;
+ * Linux = 108) rather than as a per-OS fork — a 100-byte project path always fits both.
+ */
+export const EMBED_SOCKET_PATH_BYTES_LIMIT = 100;
+
+/** Why {@link resolveEmbedSocketPath} picked the path it returned. */
+export type EmbedSocketPathReason = 'env' | 'project' | 'tmpdir-short';
+
+/** The resolved socket path plus the reason, so callers can render an honest doctor/log message. */
+export interface ResolvedEmbedSocketPath {
+  readonly path: string;
+  readonly reason: EmbedSocketPathReason;
+  /** The computed fallback itself exceeds the byte limit — the daemon must refuse, not pretend. */
+  readonly tooLong?: boolean;
+}
+
+/**
+ * FR-1. `DZ_EMBED_SOCKET` (if set to a non-empty string) always wins — an explicit override is
+ * never second-guessed. Otherwise: the natural `<projectRoot>/.dz/embed.sock` path if its BYTE
+ * length is within {@link EMBED_SOCKET_PATH_BYTES_LIMIT}; otherwise a short, deterministic path
+ * under `os.tmpdir()` keyed by a 12-hex-char SHA-1 of `projectRoot` — deterministic so a second
+ * process resolving the SAME project (with the SAME `os.tmpdir()`) independently arrives at the
+ * SAME path without needing to read a pointer file first.
+ */
+export function resolveEmbedSocketPath(projectRoot: string, env: NodeJS.ProcessEnv = process.env): ResolvedEmbedSocketPath {
+  const fromEnv = env.DZ_EMBED_SOCKET;
+  if (typeof fromEnv === 'string' && fromEnv !== '') {
+    return { path: fromEnv, reason: 'env' };
+  }
+  const projectPath = join(projectRoot, '.dz', 'embed.sock');
+  if (Buffer.byteLength(projectPath, 'utf8') <= EMBED_SOCKET_PATH_BYTES_LIMIT) {
+    return { path: projectPath, reason: 'project' };
+  }
+  // Lead edit after Codex review (findings 2/4): the short socket lives in a PRIVATE per-user
+  // directory (mode 0700, created by the daemon), never directly in the world-writable tmpdir; and
+  // the fallback itself is measured — a long TMPDIR can still overflow sun_path, which is reported
+  // as `tooLong` for the daemon to refuse with an exact diagnosis instead of a phantom "ready".
+  const hash = createHash('sha1').update(projectRoot).digest('hex').slice(0, 12);
+  const uid = String(process.getuid?.() ?? 'u');
+  const shortPath = join(tmpdir(), `dz-${uid}`, `embed-${hash}.sock`);
+  const tooLong = Buffer.byteLength(shortPath, 'utf8') > EMBED_SOCKET_PATH_BYTES_LIMIT;
+  return tooLong ? { path: shortPath, reason: 'tmpdir-short', tooLong: true } : { path: shortPath, reason: 'tmpdir-short' };
+}
+
+/** FR-2. Where the daemon writes (and a reader looks for) the tmpdir-short pointer file. */
+export function embedSocketPointerPath(projectRoot: string): string {
+  return join(projectRoot, '.dz', 'embed.sock.path');
+}
+
+/**
+ * FR-2. Read back the pointer the daemon wrote when it picked the `tmpdir-short` branch. Returns
+ * `undefined` on anything short of a non-empty file — absent, unreadable, or blank — never throws:
+ * this is a hint a reader may trust, not a contract it depends on.
+ */
+export function readEmbedSocketPointer(projectRoot: string): string | undefined {
+  const pointerPath = embedSocketPointerPath(projectRoot);
+  if (!existsSync(pointerPath)) return undefined;
+  try {
+    const raw = readFileSync(pointerPath, 'utf-8').trim();
+    return raw !== '' ? raw : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * FR-2/FR-5. The read-side combinator the hook and doctor both use: resolve as usual, and — ONLY
+ * when the resolver itself would have picked the `tmpdir-short` branch — prefer an on-disk pointer
+ * if one exists. This is deliberately narrower than "always prefer the pointer": the `env` and
+ * `project` branches are computed the same way in every process (no `os.tmpdir()` dependency), so
+ * there is nothing for a pointer to protect against there. `tmpdir-short` DOES depend on
+ * `os.tmpdir()`, which can differ between the daemon's process and a reader's (a different
+ * `TMPDIR`) — the pointer is the daemon's own record of the path it actually bound, and wins.
+ */
+export function resolveEffectiveEmbedSocketPath(projectRoot: string, env: NodeJS.ProcessEnv = process.env): ResolvedEmbedSocketPath {
+  const resolved = resolveEmbedSocketPath(projectRoot, env);
+  if (resolved.reason !== 'tmpdir-short') return resolved;
+  // Lead edit after Codex review (finding 1): a pointer is trusted only while its target exists —
+  // a stale pointer (daemon gone, TMPDIR changed) falls back to the computed path instead of
+  // steering the hook/doctor at a dead or foreign socket.
+  const pointer = readEmbedSocketPointer(projectRoot);
+  return pointer !== undefined && existsSync(pointer) ? { path: pointer, reason: 'tmpdir-short' } : resolved;
+}

package/src/index.ts

@@ -232,7 +232,9 @@ export type {
   TeachGuardResult,
 } from './vector-tier.js';
 export { runSetup, generateHooksConfig, generateAgentdbWriter, writerVersionOf, AGENTDB_WRITER_VERSION,
-  agentdbStorePath, agentdbMcpStorePath, agentdbStoreSeparationProblem } from './setup.js';
+  agentdbStorePath, agentdbMcpStorePath, agentdbStoreSeparationProblem,
+  resolveSetupMemoryBackend, memoryBackendSourceLabel } from './setup.js';
+export type { MemoryBackend, MemoryBackendSource, ResolvedSetupMemoryBackend } from './setup.js';
 // apply-leg (feature setup-installs-apply-leg, ADR-001): the third self-learning leg (APPLY) as a
 // versioned generator + the ONE measurement dz doctor/parity both read (Decision 3).
 export {
@@ -255,6 +257,16 @@ export type {
   ApplyLegNotInstalledReason,
   ResolvedIdleMs,
 } from './apply-leg.js';
+// embed-socket-short-path: the ONE resolver the daemon (inlined text), the recall hook (inlined
+// text), and dz doctor (real import) all use for the unix-socket sun_path length limit.
+export {
+  EMBED_SOCKET_PATH_BYTES_LIMIT,
+  resolveEmbedSocketPath,
+  embedSocketPointerPath,
+  readEmbedSocketPointer,
+  resolveEffectiveEmbedSocketPath,
+} from './embed-socket-path.js';
+export type { EmbedSocketPathReason, ResolvedEmbedSocketPath } from './embed-socket-path.js';
 export { countLearningStoreRowsReadonly, quarantineTierParity } from './store-counts.js';
 export type { QuarantineTierRow, QuarantineTierParity } from './store-counts.js';
 export type { LearningStoreRowCounts } from './store-counts.js';
@@ -291,7 +303,7 @@ export {
   segmentRun,
 } from './eta.js';
 export type { CheckpointObservation, EtaEstimate, EtaInput, IncompleteCoverageSample, RunSegment, StageDurationSample, StageSample } from './eta.js';
-export { indexPatternsToAgentdb, resolveAgentdbPath, searchAgentdbPatterns, listAgentdbDzIds, resolveAgentdbEmbedder, cosineSimilarity, importVectorsToAgentdb, reindexAgentdbRows, bumpAgentdbUses, clearAgentdbQuarantine, deleteAgentdbByDzIds, readAgentdbRowsByTaskType, DZ_OWNED_TASK_TYPES, ensureAgentdbSchema } from './agentdb-index.js';
+export { indexPatternsToAgentdb, resolveAgentdbPath, searchAgentdbPatterns, listAgentdbDzIds, resolveAgentdbEmbedder, resetAgentdbEmbedderCache, getAgentdbEmbedderCacheStats, cosineSimilarity, importVectorsToAgentdb, reindexAgentdbRows, bumpAgentdbUses, clearAgentdbQuarantine, deleteAgentdbByDzIds, readAgentdbRowsByTaskType, DZ_OWNED_TASK_TYPES, ensureAgentdbSchema } from './agentdb-index.js';
 export type { AgentdbSearchHit, AgentdbSearchResult, AgentdbImportRow } from './agentdb-index.js';
 export { DEFAULT_EMBED_MODEL, LEGACY_EMBED_MODEL, DEFAULT_EMBED_DIM, KNOWN_EMBED_DIMS, resolveEmbedModel, readEmbedManifest, writeEmbedManifest, embedManifestPath, legacyEmbedManifest } from './embedding-config.js';
 export type { EmbedModelConfig, EmbedModelSource, EmbedManifest } from './embedding-config.js';
@@ -717,7 +729,7 @@ export { fetchAllDownloads } from './downloads.js';
 export type { PackageDownloads, DownloadsReport } from './downloads.js';
 export { discoverInstalled, checkUpgrades } from './upgrade.js';
 export type { InstalledSkill, UpgradeCheck, UpgradeReport } from './upgrade.js';
-export type { PublishResult, PublishReport, ProvenanceMode, ProvenanceDecision } from './publish.js';
+export type { PublishResult, PublishReport, ProvenanceMode, ProvenanceDecision, PackedTarballArtifact, PackedTransportSmokeVerdict } from './publish.js';
 // Verified-release engine (feature release-verified, ADR-001) — pure VERIFY-phase planner +
 // classifier in front of the untouched publish path. formatPublishError is re-exported for the
 // CLI executor's captured-output discipline.
@@ -730,6 +742,8 @@ export {
   buildReleaseNotes,
   releaseTagName,
   firstOutputLine,
+  testsFailureDetail,
+  outputTail,
   RELEASE_GATE_ORDER,
   RELEASE_TIMEOUTS,
 } from './release.js';
@@ -750,6 +764,33 @@ export type {
   FailureIssueContext,
 } from './release.js';
 export { formatPublishError } from './publish.js';
+// Sibling-drift + packed-install-smoke gates (feature publish-sibling-drift-gate, ADR-001).
+export { detectSiblingDrift, parseNpmPackInventory } from './publish-sibling-drift.js';
+export type {
+  SiblingDriftStatus,
+  InventorySource,
+  SiblingDriftResult,
+  FetchedPublished,
+  FetchPublished,
+  DetectSiblingDriftOptions,
+  PackInventory,
+  PackInventoryUnavailable,
+  LocalInventoryResult,
+  PackedTree,
+  LocalInventory,
+} from './publish-sibling-drift.js';
+export { planPackedInstallSmoke, judgePackedInstallSmoke, packedTarballName } from './packed-install-smoke.js';
+export type {
+  PackedInstallStepKind,
+  PackedInstallStep,
+  PackedInstallPackageSpec,
+  PackedInstallBinSpec,
+  PlanPackedInstallSmokeOptions,
+  PackedInstallPlan,
+  PackedInstallExecution,
+  PackedInstallBinVerdict,
+  PackedInstallVerdict,
+} from './packed-install-smoke.js';
 export { computeRiskScore } from './risk-scoring.js';
 export type { RiskScore, RiskThresholds } from './risk-scoring.js';
 export {

package/src/operations.ts

@@ -1412,6 +1412,85 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
     // never ran `dz setup` gets no apply-leg opinion, same as every other doctor check here.
   } catch { /* doctor never throws on a diagnostic */ }
 
+  // MEMORY HOOKS MATCH CONFIG (feature `setup-backend-from-config`, FR-4). "Absence of a receipt
+  // is not success": a repeat `dz setup --target claude-code` (no `--memory`) used to silently drop
+  // `.dz/agentdb-writer.mjs` from SessionStart on an agentdb project without `doctor` ever noticing
+  // (AC-1, red-first) — `.dz/config.json`'s `memory.backend` and the ACTUAL SessionStart/
+  // SessionEnd/PreCompact hooks in `.claude/settings.json` are two independent truths, and this
+  // check compares them by fact rather than trusting either source alone.
+  try {
+    let configuredMemoryBackend: 'agentdb' | 'jsonl' | 'unknown' = 'unknown';
+    try {
+      const cfg = JSON.parse(readFileSync(join(root, '.dz', 'config.json'), 'utf-8')) as { memory?: { backend?: string } };
+      if (cfg.memory?.backend === 'agentdb') configuredMemoryBackend = 'agentdb';
+      else if (cfg.memory?.backend === 'jsonl') configuredMemoryBackend = 'jsonl';
+    } catch { /* no .dz/config.json yet — nothing to compare */ }
+
+    if (configuredMemoryBackend !== 'unknown') {
+      const { commandsOf } = await import('./setup.js');
+      // Lead edit after Codex review (findings 1/4): agentdb is "wired" only when EVERY session event
+      // invokes the writer (a writer on SessionStart alone loses the end-of-session row), and the writer
+      // is recognized by its PATH TOKEN, not a substring — `old-agentdb-writer.mjs` or the name inside an
+      // echo must not count.
+      const invokesWriter = (cmd: string): boolean =>
+        cmd.split(/\s+/).some((tok) => /^(?:\.\/)?(?:.*\/)?\.dz\/agentdb-writer\.mjs$/.test(tok.replace(/^["']|["']$/g, '')));
+      const WRITER_EVENTS = ['SessionStart', 'SessionEnd', 'PreCompact'];
+      let eventsWithWriter: string[] = [];
+      let settingsReadable = false;
+      // Lead edit after Codex review (finding 1, 2026-09-13): three states, not a boolean — an
+      // EXISTING settings.json that cannot be parsed is "unknowable", never "agrees".
+      const settingsPath = join(root, '.claude', 'settings.json');
+      const settingsPresent = existsSync(settingsPath);
+      try {
+        const settings = JSON.parse(readFileSync(settingsPath, 'utf-8')) as {
+          hooks?: Record<string, unknown[]>;
+        };
+        eventsWithWriter = WRITER_EVENTS.filter((ev) => (settings.hooks?.[ev] ?? []).some((h) => commandsOf(h).some(invokesWriter)));
+        // Lead edit after Codex round 2 (new finding 2): "readable" means the hooks were actually
+        // INSPECTED — a parseable but malformed shape (`null`, a non-array event) throws inside the
+        // traversal and must land in the "cannot be compared" row, never in the OK row.
+        settingsReadable = true;
+      } catch {
+      }
+      const settingsUnreadable = settingsPresent && !settingsReadable;
+      const allWired = eventsWithWriter.length === WRITER_EVENTS.length;
+      const hooksInvokeAgentdbWriter = eventsWithWriter.length > 0;
+
+      if (settingsUnreadable) {
+        // Lead edit after Codex round 2: precedence — an unparseable settings.json is diagnosed FIRST for
+        // both backends; the hooks are UNKNOWABLE, so neither "not wired" nor "in agreement" may be claimed.
+        checks.push({
+          name: 'memory hooks match config',
+          ok: false,
+          detail: `.dz/config.json says memory.backend=${configuredMemoryBackend} but .claude/settings.json exists and could not be parsed or inspected (invalid JSON or a malformed hooks shape) — the hooks cannot be compared; fix the file (or re-run dz setup)`,
+        });
+      } else if (configuredMemoryBackend === 'agentdb' && !allWired) {
+        checks.push({
+          name: 'memory hooks match config',
+          ok: false,
+          detail: `.dz/config.json says memory.backend=agentdb but ${WRITER_EVENTS.filter((ev) => !eventsWithWriter.includes(ev)).join('/')} hook(s) do not invoke .dz/agentdb-writer.mjs${settingsReadable ? '' : ' (.claude/settings.json unreadable or absent)'} — run: dz setup --target claude-code --memory agentdb`,
+        });
+      } else if (configuredMemoryBackend === 'jsonl' && hooksInvokeAgentdbWriter) {
+        checks.push({
+          name: 'memory hooks match config',
+          ok: false,
+          detail: '.dz/config.json says memory.backend=jsonl but SessionStart/SessionEnd/PreCompact hooks still invoke agentdb-writer.mjs — run: dz setup --target claude-code --memory jsonl (or --memory agentdb to keep agentdb and bring the config back in sync)',
+        });
+      } else {
+        // the OK receipt comes from the SAME comparison that produces the red rows (all three events observed)
+        checks.push({
+          name: 'memory hooks match config',
+          ok: true,
+          detail: configuredMemoryBackend === 'agentdb'
+            ? 'memory.backend=agentdb — SessionStart/SessionEnd/PreCompact all invoke .dz/agentdb-writer.mjs'
+            : `memory.backend=jsonl — SessionStart/SessionEnd/PreCompact do not invoke .dz/agentdb-writer.mjs${settingsPresent ? '' : ' (no .claude/settings.json — no hooks at all)'}`,
+        });
+      }
+    }
+    // configuredMemoryBackend === 'unknown': no .dz/config.json yet — nothing to compare, same
+    // silence as every other doctor check that needs it.
+  } catch { /* doctor never throws on a diagnostic */ }
+
   const writerPath = join(root, '.dz', 'agentdb-writer.mjs');
   if (existsSync(writerPath)) {
     const { writerVersionOf, AGENTDB_WRITER_VERSION } = await import('./setup.js');
@@ -1433,13 +1512,35 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
         const settingsText = readFileSync(settingsPath, 'utf-8');
         const applyLegWired = settingsText.includes('recall-hook.cjs') && settingsText.includes('dz-embed-daemon.mjs');
         if (applyLegWired) {
-          const sockAlive = existsSync(join(root, '.dz', 'embed.sock'));
+          // embed-socket-short-path (FR-5): name the ACTUAL path the resolver picked — a deeply
+          // nested project's daemon binds a short tmpdir path, not `<root>/.dz/embed.sock`, and a
+          // doctor that only ever checks the latter reports ABSENT for a daemon that is alive.
+          const { resolveEffectiveEmbedSocketPath, EMBED_SOCKET_PATH_BYTES_LIMIT } = await import('./embed-socket-path.js');
+          const resolved = resolveEffectiveEmbedSocketPath(root);
+          const sockAlive = existsSync(resolved.path);
+          const projectPathBytes = Buffer.byteLength(join(root, '.dz', 'embed.sock'), 'utf8');
+          const tmpdirNote =
+            resolved.reason === 'tmpdir-short'
+              ? ` (tmpdir-short: project path ${projectPathBytes} bytes > ${EMBED_SOCKET_PATH_BYTES_LIMIT})`
+              : '';
+          // FR-6 (hook-recall-hybrid-parity): a socket that merely EXISTS is not proof of what it
+          // answers with — probe it. A non-live fixture (a plain file, no listener) fails the probe
+          // near-instantly and this note stays empty, so every pre-existing detail string here is
+          // untouched.
+          // AM-8 (fix round 1): the socket-speaking probe itself now lives in apply-leg.ts (the
+          // module that already owns the daemon's wire protocol + socket-path resolution) rather
+          // than duplicating a `node:net` IO surface here — dynamic `import()`, same pattern as
+          // `embed-socket-path.js` two lines above, so operations.ts carries no new top-level IO
+          // import for this.
+          const { probeRecallEngine } = await import('./apply-leg.js');
+          const engine = sockAlive ? await probeRecallEngine(resolved.path) : undefined;
+          const engineNote = engine !== undefined ? ` (engine: ${engine})` : '';
           checks.push({
             name: 'apply-leg alive (embed daemon)',
             ok: sockAlive,
             detail: sockAlive
-              ? 'embed.sock present — recall injection can run'
-              : 'embed.sock ABSENT: the recall hook is wired but cannot inject (the hook self-heals on the next prompt; a persistent absence means the daemon cannot start)',
+              ? `embed socket present at ${resolved.path}${tmpdirNote}${engineNote} — recall injection can run`
+              : `embed socket ABSENT at ${resolved.path}: the recall hook is wired but cannot inject (the hook self-heals on the next prompt; a persistent absence means the daemon cannot start)`,
           });
         }
       }

package/src/packed-install-smoke.ts

@@ -0,0 +1,273 @@
+/**
+ * Packed-install smoke — feature `publish-sibling-drift-gate`, ADR-001 (Decision 2).
+ *
+ * `dz release`'s existing smoke gate boots a package's bin straight from the WORKSPACE — its
+ * sibling `workspace:*` deps resolve via pnpm's workspace links, never through a real install.
+ * That makes the whole class of "published tarball missing an export" incidents invisible by
+ * construction (Alternative Б1, rejected). This module plans and judges the alternative
+ * (Б2, accepted): pack every package in the batch, `npm install` the resulting tarballs together
+ * into a CLEAN directory — siblings OUTSIDE the batch resolve from the registry, exactly like a
+ * fresh user's install — then boot every bin with `--version` and require exit 0 AND non-empty
+ * stdout (the "publisher output is not a receipt" lesson: a bin that boots but prints nothing has
+ * not proven it works).
+ *
+ * Pure by construction (NFR-2): `planPackedInstallSmoke` only builds command STRINGS from
+ * injected package/bin facts and paths — it never spawns anything. `judgePackedInstallSmoke`
+ * only classifies injected execution records. The CLI (`cmdPublish`, `cmdRelease`) is the single
+ * executor, sharing this same plan/judge pair so both doors apply the identical rule.
+ *
+ * @packageDocumentation
+ */
+
+import { join } from 'node:path';
+
+export type PackedInstallStepKind = 'pack' | 'install' | 'bin-exists' | 'bin-version';
+
+/** One concrete step — data, not action (mirrors release.ts's GateStep idiom). */
+export interface PackedInstallStep {
+  readonly id: string;
+  readonly kind: PackedInstallStepKind;
+  readonly cmd: string;
+  readonly cwd: string;
+  readonly timeoutMs: number;
+  /** Present for 'pack' and 'bin-version' steps. */
+  readonly pkg?: string;
+  /** Present for 'bin-version' steps only. */
+  readonly binName?: string;
+}
+
+export interface PackedInstallPackageSpec {
+  readonly name: string;
+  /** Absolute source directory to `npm pack`. */
+  readonly dir: string;
+  readonly version: string;
+}
+
+export interface PackedInstallBinSpec {
+  readonly pkg: string;
+  readonly binName: string;
+  /** Path to the executable relative to the package's OWN directory (as it ships), e.g. "dist/bin.js". */
+  readonly relPath: string;
+}
+
+export interface PlanPackedInstallSmokeOptions {
+  /** Every package to pack — the full batch, since a bin-less sibling can still be a dependency. */
+  readonly packages: readonly PackedInstallPackageSpec[];
+  /** Bins to boot after install (typically the subset of `packages` that declare one). */
+  readonly bins: readonly PackedInstallBinSpec[];
+  /** Directory `npm pack --pack-destination` writes tarballs into. */
+  readonly packDir: string;
+  /** Fresh, empty directory `npm install` runs in — outside-batch siblings resolve from the registry here. */
+  readonly installDir: string;
+  readonly packTimeoutMs?: number;
+  readonly installTimeoutMs?: number;
+  readonly versionTimeoutMs?: number;
+  /**
+   * AM-1 (feature publish-sibling-drift-gate): the caller (`publishPackages`'s `packedTransport`)
+   * already packed each artifact ONCE, post-bump — a SECOND, different `npm pack` here would smoke
+   * bytes other than the ones about to be published, reintroducing the exact defect this amendment
+   * closes. `true` skips planning any 'pack' step; `tarballs` is still populated with the SAME
+   * deterministic `packedTarballName(name, version)` path under `packDir` — the caller is
+   * responsible for having written the tarball there already (`packages[].dir` is unused in this
+   * mode and may be any string).
+   */
+  readonly skipPack?: boolean;
+}
+
+export interface PackedInstallPlan {
+  readonly steps: readonly PackedInstallStep[];
+  /** Absolute tarball paths the install step references, in package order. */
+  readonly tarballs: readonly string[];
+}
+
+const DEFAULT_PACK_TIMEOUT_MS = 60_000;
+const DEFAULT_INSTALL_TIMEOUT_MS = 180_000;
+const DEFAULT_VERSION_TIMEOUT_MS = 30_000;
+
+/** Mirror npm's own tarball naming: `@scope/name@1.2.3` -> `scope-name-1.2.3.tgz`. */
+export function packedTarballName(name: string, version: string): string {
+  return `${name.replace(/^@/, '').replace(/\//g, '-')}-${version}.tgz`;
+}
+
+export function planPackedInstallSmoke(opts: PlanPackedInstallSmokeOptions): PackedInstallPlan {
+  const packTimeoutMs = opts.packTimeoutMs ?? DEFAULT_PACK_TIMEOUT_MS;
+  const installTimeoutMs = opts.installTimeoutMs ?? DEFAULT_INSTALL_TIMEOUT_MS;
+  const versionTimeoutMs = opts.versionTimeoutMs ?? DEFAULT_VERSION_TIMEOUT_MS;
+
+  const steps: PackedInstallStep[] = [];
+  const tarballs: string[] = [];
+
+  for (const pkg of opts.packages) {
+    const tgz = join(opts.packDir, packedTarballName(pkg.name, pkg.version));
+    tarballs.push(tgz);
+    if (opts.skipPack === true) continue; // AM-1: already packed by the caller — see skipPack's doc
+    steps.push({
+      id: `pack:${pkg.name}`,
+      kind: 'pack',
+      cmd: `npm pack ${JSON.stringify(pkg.dir)} --pack-destination ${JSON.stringify(opts.packDir)}`,
+      cwd: pkg.dir,
+      timeoutMs: packTimeoutMs,
+      pkg: pkg.name,
+    });
+  }
+
+  if (tarballs.length > 0) {
+    steps.push({
+      id: 'install',
+      kind: 'install',
+      cmd: `npm install ${tarballs.map((t) => JSON.stringify(t)).join(' ')} --no-audit --no-fund`,
+      cwd: opts.installDir,
+      timeoutMs: installTimeoutMs,
+    });
+  }
+
+  for (const bin of opts.bins) {
+    const absBinPath = join(opts.installDir, 'node_modules', bin.pkg, bin.relPath);
+    // AM-8: a manifest can declare a `bin` whose target file does not exist (never built, moved,
+    // typo'd) — the OLD `cli.ts` bin-collection step silently DROPPED such a bin before this
+    // amendment, which read as "n/a: nothing to smoke" (or even skipped the whole gate when it
+    // was the batch's only bin). `test -f` is a dedicated, portable existence probe RUN AFTER THE
+    // REAL INSTALL — pass/fail here is judged into a specific, honest message
+    // ("declared bin missing after packed install") instead of being folded into whatever
+    // `node <bin> --version` happens to print for a missing file (a generic MODULE_NOT_FOUND).
+    steps.push({
+      id: `bin-exists:${bin.pkg}:${bin.binName}`,
+      kind: 'bin-exists',
+      cmd: `test -f ${JSON.stringify(absBinPath)}`,
+      cwd: opts.installDir,
+      timeoutMs: versionTimeoutMs,
+      pkg: bin.pkg,
+      binName: bin.binName,
+    });
+    steps.push({
+      id: `bin:${bin.pkg}:${bin.binName}`,
+      kind: 'bin-version',
+      cmd: `node ${JSON.stringify(absBinPath)} --version`,
+      cwd: opts.installDir,
+      timeoutMs: versionTimeoutMs,
+      pkg: bin.pkg,
+      binName: bin.binName,
+    });
+  }
+
+  return { steps, tarballs };
+}
+
+export interface PackedInstallExecution {
+  readonly stepId: string;
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly timedOut?: boolean;
+}
+
+export interface PackedInstallBinVerdict {
+  readonly pkg: string;
+  readonly binName: string;
+  readonly ok: boolean;
+  readonly stdout: string;
+  /** First 3 non-empty lines of stderr (falling back to stdout), present only when !ok. */
+  readonly detail?: string;
+}
+
+export interface PackedInstallVerdict {
+  readonly ok: boolean;
+  readonly packOk: boolean;
+  readonly installOk: boolean;
+  /** First failure's detail, from whichever of pack/install failed first. */
+  readonly failureDetail?: string;
+  readonly bins: readonly PackedInstallBinVerdict[];
+}
+
+/**
+ * First 3 lines (FR-3), EXCEPT when they are pure source context. MEASURED 2026-09-13 reproducing
+ * the exact incident this gate targets — a bin whose `import` names a missing export — Node
+ * prints the location, the offending source line and a caret BEFORE the actual
+ * `SyntaxError: … does not provide an export named …` message (identically for a plain uncaught
+ * `throw`: file:line / code / `^` / blank / `Error: …`). A literal first-3-lines slice therefore
+ * shows three lines of code and caret marks and never the reason — useless for the incident it
+ * exists to surface. When stderr contains a line that LOOKS like an error header
+ * (`SomethingError: …` or bare `Error: …`), the snippet starts there instead.
+ */
+function firstLines(text: string, n: number): string {
+  const lines = text.split(/\r?\n/).map((l) => l.trim()).filter((l) => l.length > 0);
+  if (lines.length === 0) return '(no output)';
+  const errorHeaderAt = lines.findIndex((l) => /^[A-Za-z][A-Za-z0-9_]*Error:|^Error\b/.test(l));
+  const start = errorHeaderAt >= 0 ? errorHeaderAt : 0;
+  return lines.slice(start, start + n).join(' | ');
+}
+
+const NO_EXECUTION_RECORD = '(no execution record — under-executed plan)';
+
+function stepOk(exec: PackedInstallExecution | undefined): boolean {
+  return exec !== undefined && exec.timedOut !== true && exec.exitCode === 0;
+}
+
+function stepDetail(exec: PackedInstallExecution | undefined): string {
+  if (exec === undefined) return NO_EXECUTION_RECORD;
+  if (exec.timedOut === true) return 'timed out';
+  return firstLines(exec.stderr || exec.stdout, 3);
+}
+
+/**
+ * Classify a plan's executions. `plan` may be the `{ steps }` half of {@link PackedInstallPlan}.
+ * A missing execution for a planned step is a FAILURE (an under-executed plan cannot pass) —
+ * never treated as "nothing to judge, so it passed".
+ */
+export function judgePackedInstallSmoke(
+  plan: { readonly steps: readonly PackedInstallStep[] },
+  executions: readonly PackedInstallExecution[],
+): PackedInstallVerdict {
+  const byId = new Map(executions.map((e) => [e.stepId, e]));
+
+  let packOk = true;
+  let failureDetail: string | undefined;
+  for (const step of plan.steps.filter((s) => s.kind === 'pack')) {
+    const exec = byId.get(step.id);
+    if (!stepOk(exec)) {
+      packOk = false;
+      failureDetail ??= stepDetail(exec);
+    }
+  }
+
+  let installOk = true;
+  const installStep = plan.steps.find((s) => s.kind === 'install');
+  if (installStep !== undefined) {
+    const exec = byId.get(installStep.id);
+    if (!stepOk(exec)) {
+      installOk = false;
+      failureDetail ??= stepDetail(exec);
+    }
+  }
+
+  const bins: PackedInstallBinVerdict[] = plan.steps
+    .filter((s) => s.kind === 'bin-version')
+    .map((step) => {
+      const exec = byId.get(step.id);
+      if (!packOk || !installOk) {
+        // Pack/install already failed for the whole batch — the generic pack/install detail is
+        // more informative than a bin-specific message about a step that never had a chance to run.
+        return { pkg: step.pkg!, binName: step.binName!, ok: false, stdout: '', detail: stepDetail(exec) };
+      }
+      // AM-8: a declared bin missing from the REAL post-install tree is its own failure class —
+      // checked and reported BEFORE the generic stdout rule below, whose message ("empty stdout")
+      // would otherwise misdescribe a file that was never there to boot at all.
+      const existsStep = plan.steps.find((s) => s.kind === 'bin-exists' && s.pkg === step.pkg && s.binName === step.binName);
+      if (existsStep !== undefined && !stepOk(byId.get(existsStep.id))) {
+        return { pkg: step.pkg!, binName: step.binName!, ok: false, stdout: '', detail: 'declared bin missing after packed install' };
+      }
+      // FR-3 / lesson "publisher output is not a receipt": exit 0 alone is not enough — the
+      // version output must be non-empty, or a bin that silently no-ops would read as healthy.
+      const ok = stepOk(exec) && (exec?.stdout ?? '').trim() !== '';
+      return {
+        pkg: step.pkg!,
+        binName: step.binName!,
+        ok,
+        stdout: exec?.stdout ?? '',
+        ...(ok ? {} : { detail: exec !== undefined && stepOk(exec) ? '(exit 0 but empty stdout)' : stepDetail(exec) }),
+      };
+    });
+
+  const ok = packOk && installOk && bins.every((b) => b.ok);
+  return { ok, packOk, installOk, ...(failureDetail !== undefined ? { failureDetail } : {}), bins };
+}