@dzhechkov/harness-core 0.8.45 → 0.8.46

package/src/pack-inventory.ts

@@ -36,6 +36,26 @@ export interface PublishSecretSeams {
   readonly tgzPathFor?: (dir: string) => string | undefined;
 }
 
+/**
+ * Share of NUL bytes above which a sample is binary. MEASURED 2026-09-21 (backlog d3841a3b): one NUL in
+ * 19 628 bytes of TypeScript made the old `includes(0)` sniff skip a packed TEXT file from the no-secrets scan.
+ */
+export const NUL_RATIO = 0.01;
+
+/**
+ * PURE binary sniff over the first bytes of a file: `true` iff NUL bytes exceed `NUL_RATIO` of the sample length.
+ * Empty ⇒ text. ONLY NULs count (fix round 1, F1): the rule this replaces skipped on a NUL and nothing else, so a
+ * criterion over other control bytes or UTF-8 validity would SKIP files the old rule SCANNED — a latin-1 source with
+ * a secret, a text with \x01 separators — and that is a fail-open regression. One NUL in 8 KiB is text and gets
+ * scanned; UTF-16 (about half NULs) is binary as before; a PNG with few NULs is scanned — harmless, the scan is read-only.
+ */
+export function looksBinarySample(sample: Buffer): boolean {
+  if (sample.length === 0) return false;
+  let nuls = 0;
+  for (const byte of sample) if (byte === 0) nuls++;
+  return nuls > NUL_RATIO * sample.length;
+}
+
 /** Scan the publish inventory as streams, retaining every coverage gap by name. */
 export function gatherPublishSecretFacts(root: string, packageDirs: readonly string[], seams: PublishSecretSeams = {}):
   { readonly secretFindings: readonly { label: string; name: string }[];
@@ -74,7 +94,7 @@ export function gatherPublishSecretFacts(root: string, packageDirs: readonly str
           let first = true;
           try {
             for (const chunk of reader(absolute, 1024 * 1024)) {
-              if (first && chunk.subarray(0, 8 * 1024).includes(0)) { binary = true; return; }
+              if (first && looksBinarySample(chunk.subarray(0, 8 * 1024))) { binary = true; return; }
               first = false;
               yield chunk;
             }

package/src/round-exec-claim.ts

@@ -0,0 +1,43 @@
+/**
+ * round-exec-claim-takeover (FR-1): the pure verdict behind `dz round exec`'s claim transaction.
+ *
+ * A round claimed by an `exec` whose process died (SIGTERM, OOM, reboot) used to refuse every later
+ * `exec` forever (backlog 280e914607397474). This decides — from facts the caller measured under the
+ * state lock — whether the standing claim is held, provably stale-dead, or unknowable:
+ *
+ * - `pidAlive === true`  ⇒ `held`, regardless of age (a live owner is never taken over);
+ * - `pidAlive === null`  ⇒ `unknown` (the probe was inconclusive — refusal is the safe side);
+ * - `pid` not a positive safe integer ⇒ `unknown` («no pid recorded») — nothing to probe;
+ * - `execClaimedAt` unparsable ⇒ `unknown` («claim time unreadable») — no age to debounce on;
+ * - `pidAlive === false` and age ≥ `staleMinutes` ⇒ `stale-dead` with the floored age;
+ * - `pidAlive === false` but younger ⇒ `held` — a just-died claim may be a restart in flight, and
+ *   the threshold is the debounce.
+ *
+ * Pure: no clock, no process table — `now` and `pidAlive` are inputs so the caller keeps the
+ * critical section short (`process.kill(pid, 0)`, NFR-1) and tests need no real processes.
+ */
+export type ExecClaimVerdict =
+  | { kind: 'held' }
+  | { kind: 'stale-dead'; ageMinutes: number }
+  | { kind: 'unknown'; reason: string };
+
+export type ExecClaimTakeoverInput = {
+  readonly execClaimedAt?: string | undefined;
+  readonly pid?: number | undefined;
+  readonly pidAlive: boolean | null;
+  readonly now: number;
+  readonly staleMinutes: number;
+};
+
+export function decideExecClaimTakeover(input: ExecClaimTakeoverInput): ExecClaimVerdict {
+  if (input.pidAlive === true) return { kind: 'held' };
+  if (input.pid === undefined || !Number.isSafeInteger(input.pid) || input.pid <= 0) {
+    return { kind: 'unknown', reason: 'no pid recorded' };
+  }
+  if (input.pidAlive === null) return { kind: 'unknown', reason: 'PID probe inconclusive' };
+  const claimedMs = input.execClaimedAt === undefined ? Number.NaN : Date.parse(input.execClaimedAt);
+  if (!Number.isFinite(claimedMs)) return { kind: 'unknown', reason: 'claim time unreadable' };
+  const ageMinutes = Math.floor((input.now - claimedMs) / 60_000);
+  if (ageMinutes >= input.staleMinutes) return { kind: 'stale-dead', ageMinutes };
+  return { kind: 'held' };
+}

package/src/session-retro.ts

@@ -14,9 +14,10 @@
  * is taught silently but NOT drilled — no nagging on a one-off. Drills are for recurrent patterns only.
  */
 
-import { existsSync, readFileSync, readdirSync, statSync, openSync, readSync, closeSync, writeFileSync, renameSync, unlinkSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync, openSync, readSync, closeSync, writeFileSync, renameSync, unlinkSync, mkdirSync, rmSync } from 'node:fs';
 import { join, basename, dirname } from 'node:path';
 import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
 
 import { withProjectLockSync, NamedLockTimeoutError } from './named-lock.js';
 
@@ -538,11 +539,62 @@ export function findLatestTranscript(repoRoot: string): string | null {
 // ── Per-turn admission-debt scan (feature narrated-error-must-be-taught, ADR-001 D2/D4) ────────────
 // The Stop hook runs `dz retro --scan-tail` after EVERY assistant turn, so this half is built around
 // one budget: O(new bytes) — a persisted byte offset, no full re-read, no store open, no subprocess.
-// The sentinel `.dz/retro-pending.json` is the debt; the recall hook turns it into a next-prompt
-// directive; a REAL teach invocation (a TOOL event — prose promises never pay, ADR-001 D4) clears it.
+// The sentinel `.dz/retro/<session>/pending.json` is the debt; the recall hook turns it into a
+// next-prompt directive; a REAL teach invocation (a TOOL event — prose promises never pay, ADR-001 D4)
+// clears it.
 
+/** LEGACY flat names (pre retro-debt-sentinel-per-session): the ONE pair every session in a worktree
+ * once shared under `.dz/`. A scan ADOPTS its own transcript's flat files once (FR-4) and never
+ * writes them again; a stranger's flat file is never touched. */
 export const RETRO_SCAN_STATE_FILE = 'retro-scan-state.json';
 export const RETRO_PENDING_FILE = 'retro-pending.json';
+
+// ── Per-session layout (feature retro-debt-sentinel-per-session, FR-1; backlog 58f3c56fbb9d6893) ──
+// Two sessions in one worktree shared the flat pair above, so a Stop scan of EITHER unlinked the
+// other's LIVE debt as "foreign", and the shared bookmark made each session's offset meaningless to
+// the other (foreign transcript ⇒ offset 0 ⇒ a bounded re-scan every turn; MEASURED 22.09 20:23, a
+// second session in this repo). The pair now lives in a directory named after the session.
+export const RETRO_SESSION_DIRNAME = 'retro';
+export const RETRO_SESSION_PENDING_BASENAME = 'pending.json';
+export const RETRO_SESSION_STATE_BASENAME = 'scan-state.json';
+/** A session dir whose scan-state is older than this belongs to a dead session: the next scan of
+ * any other session sweeps it (FR-5). A live session that ran no Stop for 7 days loses only a debt
+ * the hook would have called stale anyway (SENTINEL_FRESH_MS is 30 min) — accepted risk R2. */
+export const RETRO_SESSION_STALE_MS = 7 * 24 * 3600 * 1000;
+/** At most this many `.dz/retro/*` entries are examined per scan — the sweep's cost bound (NFR-1). */
+const RETRO_SWEEP_MAX_ENTRIES = 64;
+const SAFE_SESSION_ID_RE = /^[A-Za-z0-9._-]{1,128}$/;
+
+/**
+ * The directory name for a session id. PURE. A plain token is used as is; anything else — a
+ * path-like string, the empty string, an over-long id, and the two dot names the charset regex
+ * alone would let through (`.` ⇒ `<dzDir>/retro`, `..` ⇒ `<dzDir>` itself) — becomes the first
+ * 32 hex of its sha256, so a session id can never name a path outside `.dz/retro/` (AC-2).
+ * TWIN: the recall hook in `apply-leg.ts` carries a copy (the hook must stay dependency-free);
+ * `test/retro-sentinel-per-session.test.ts` pins the two to equal outputs.
+ */
+export function safeSessionDirName(sessionId: string): string {
+  if (SAFE_SESSION_ID_RE.test(sessionId) && sessionId !== '.' && sessionId !== '..') return sessionId;
+  return createHash('sha256').update(sessionId).digest('hex').slice(0, 32);
+}
+
+/** The session id the SCANNER derives: the transcript basename without `.jsonl`. Claude Code names
+ * the transcript after the session id, so this equals the `session_id` the hook payload carries. PURE. */
+export function sessionIdFromTranscript(transcriptPath: string): string {
+  return basename(transcriptPath).replace(/\.jsonl$/, '');
+}
+
+export interface RetroSessionPaths {
+  readonly dir: string;
+  readonly pendingPath: string;
+  readonly statePath: string;
+}
+
+/** Where ONE session's debt and bookmark live: `<dzDir>/retro/<safeId>/{pending,scan-state}.json`. PURE, no fs. */
+export function retroSessionPaths(dzDir: string, sessionId: string): RetroSessionPaths {
+  const dir = join(dzDir, RETRO_SESSION_DIRNAME, safeSessionDirName(sessionId));
+  return { dir, pendingPath: join(dir, RETRO_SESSION_PENDING_BASENAME), statePath: join(dir, RETRO_SESSION_STATE_BASENAME) };
+}
 /** Bound the very FIRST scan of an already-huge transcript; later scans read only the new bytes. */
 const MAX_TAIL_SCAN_BYTES = 8 * 1024 * 1024;
 /** Without a session id to compare, a sentinel older than this is stale (fallback freshness only). */
@@ -628,6 +680,10 @@ export interface TailScanOutcome {
   readonly snippet?: string;
   readonly scannedBytes: number;
   readonly offset: number;
+  /** The session the scan was scoped to (FR-6) — absent only when no transcript was named. */
+  readonly sessionId?: string;
+  /** The per-session sentinel path the scan wrote, cleared, or left absent (FR-6). */
+  readonly pendingPath?: string;
 }
 
 /** The scan-state + sentinel pair is a read-modify-write store; per the repo concurrency rule
@@ -728,6 +784,8 @@ const writeJsonAtomic = (path: string, value: unknown): void => {
  */
 export function runRetroTailScan(dzDir: string, transcriptPath: string | null, nowIso?: string): TailScanOutcome {
   if (transcriptPath === null || transcriptPath === '') return { status: 'no-transcript', scannedBytes: 0, offset: 0 };
+  const sessionId = sessionIdFromTranscript(transcriptPath);
+  const ids = { sessionId, pendingPath: retroSessionPaths(dzDir, sessionId).pendingPath };
   try {
     return withProjectLockSync(
       dirname(dzDir),
@@ -736,43 +794,71 @@ export function runRetroTailScan(dzDir: string, transcriptPath: string | null, n
       { timeoutMs: RETRO_SCAN_LOCK_TIMEOUT_MS },
     );
   } catch (e) {
-    if (e instanceof NamedLockTimeoutError) return { status: 'contended', scannedBytes: 0, offset: 0 };
+    if (e instanceof NamedLockTimeoutError) return { status: 'contended', scannedBytes: 0, offset: 0, ...ids };
     // Compromised lock or any unexpected failure: report nothing, advance nothing (never-block).
-    return { status: 'none', scannedBytes: 0, offset: 0 };
+    return { status: 'none', scannedBytes: 0, offset: 0, ...ids };
   }
 }
 
 /** The transaction body — call ONLY under the named lock. Never throws for ordinary fs failures. */
 function scanTailUnderLock(dzDir: string, transcriptPath: string, nowIso?: string): TailScanOutcome {
+  // FR-2: every path this scan writes or removes is inside ITS OWN session dir; the only files it
+  // ever touches outside are the legacy flat pair, and only to adopt its own (FR-4).
+  const sessionId = sessionIdFromTranscript(transcriptPath);
+  const { dir, pendingPath, statePath } = retroSessionPaths(dzDir, sessionId);
+  const ids = { sessionId, pendingPath };
   try {
-    const statePath = join(dzDir, RETRO_SCAN_STATE_FILE);
-    const pendingPath = join(dzDir, RETRO_PENDING_FILE);
+    const legacyStatePath = join(dzDir, RETRO_SCAN_STATE_FILE);
+    const legacyPendingPath = join(dzDir, RETRO_PENDING_FILE);
 
+    const readOffset = (p: string): number | null => {
+      try {
+        const st = JSON.parse(readFileSync(p, 'utf8')) as { transcript?: string; offset?: number };
+        if (st.transcript === transcriptPath && typeof st.offset === 'number' && Number.isFinite(st.offset) && st.offset >= 0) return Math.floor(st.offset);
+      } catch { /* absent or unreadable */ }
+      return null;
+    };
     let offset = 0;
-    try {
-      const st = JSON.parse(readFileSync(statePath, 'utf8')) as { transcript?: string; offset?: number };
-      if (st.transcript === transcriptPath && typeof st.offset === 'number' && Number.isFinite(st.offset) && st.offset >= 0) offset = Math.floor(st.offset);
-    } catch { /* first scan of this transcript */ }
-
-    // Prior debt carries over ONLY for the same session; a stale sentinel (another session's debt)
-    // is dropped — the PreCompact/SessionEnd retro of THAT session was its collector, and injecting
-    // an old session's debt into a new one is noise (acid A9).
-    let prior: AdmissionDebt | null = null;
-    let hadSentinel = false;
-    try {
-      const s = JSON.parse(readFileSync(pendingPath, 'utf8')) as Partial<RetroPendingSentinel>;
-      if (s.transcript === transcriptPath && typeof s.snippet === 'string') {
-        prior = { snippet: s.snippet, ...(s.awaiting !== undefined ? { awaiting: s.awaiting } : {}) };
-        hadSentinel = true;
-      }
-      else { try { unlinkSync(pendingPath); } catch { /* already gone */ } }
-    } catch { /* no sentinel */ }
+    let adoptLegacyState = false;
+    const ownOffset = readOffset(statePath);
+    if (ownOffset !== null) offset = ownOffset;
+    else if (!existsSync(statePath)) {
+      // FR-4: the flat bookmark is adopted ONCE — only while this session has no bookmark of its own,
+      // and only when it names THIS transcript. Another session's stays where it is.
+      const legacyOffset = readOffset(legacyStatePath);
+      if (legacyOffset !== null) { offset = legacyOffset; adoptLegacyState = true; }
+    }
+
+    const readSentinel = (p: string): { prior: AdmissionDebt | null; present: boolean } => {
+      try {
+        const s = JSON.parse(readFileSync(p, 'utf8')) as Partial<RetroPendingSentinel>;
+        if (s.transcript === transcriptPath && typeof s.snippet === 'string') {
+          return { prior: { snippet: s.snippet, ...(s.awaiting !== undefined ? { awaiting: s.awaiting } : {}) }, present: true };
+        }
+        return { prior: null, present: true };
+      } catch { return { prior: null, present: false }; }
+    };
+    // Prior debt: this session's own sentinel. One naming ANOTHER transcript can only mean the
+    // transcript was moved or renamed under the same basename — it is IGNORED and overwritten (or
+    // removed below when nothing is armed), never deleted as "foreign": the pre-feature branch that
+    // unlinked a sentinel of another transcript deleted the NEIGHBOUR session's live debt (FR-2).
+    const own = readSentinel(pendingPath);
+    let prior = own.prior;
+    const staleOwn = own.present && own.prior === null;
+    let adoptLegacyPending = false;
+    if (!own.present) {
+      // FR-4: the flat sentinel is adopted only when it is THIS transcript's and this session has no
+      // per-session copy yet; a stranger's, or a nobody's (no transcript field), is left untouched.
+      const legacy = readSentinel(legacyPendingPath);
+      if (legacy.prior !== null) { prior = legacy.prior; adoptLegacyPending = true; }
+    }
+    const hadSentinel = prior !== null;
 
     let size = 0;
     try { size = statSync(transcriptPath).size; } catch {
       return prior !== null
-        ? { status: 'pending', snippet: prior.snippet, scannedBytes: 0, offset }
-        : { status: 'none', scannedBytes: 0, offset };
+        ? { status: 'pending', snippet: prior.snippet, scannedBytes: 0, offset, ...ids }
+        : { status: 'none', scannedBytes: 0, offset, ...ids };
     }
     if (size < offset) offset = 0;                                        // truncated/rotated transcript
     let jumped = offset === 0 && size > MAX_TAIL_SCAN_BYTES;              // bound the first scan of a huge file
@@ -802,12 +888,12 @@ function scanTailUnderLock(dzDir: string, transcriptPath: string, nowIso?: strin
 
     const next = foldAdmissionDebt(events, prior);
     const newOffset = offset + consumed;
-    mkdirSync(dzDir, { recursive: true });
+    mkdirSync(dir, { recursive: true });
     let outcome: TailScanOutcome;
     if (next !== null) {
       const sentinel: RetroPendingSentinel = {
         schema: 1,
-        sessionId: basename(transcriptPath).replace(/\.jsonl$/, ''),
+        sessionId,
         transcript: transcriptPath,
         snippet: next.snippet.replace(/\s+/g, ' ').trim().slice(0, 200),
         ts: nowIso ?? new Date().toISOString(),
@@ -826,13 +912,45 @@ function scanTailUnderLock(dzDir: string, transcriptPath: string, nowIso?: strin
       catch (e) { if ((e as NodeJS.ErrnoException).code !== 'ENOENT') throw e; }
       outcome = { status: 'cleared', scannedBytes: consumed, offset: newOffset };
     } else {
+      // Our own stale sentinel (moved transcript, see above) with nothing armed: removed, so the hook
+      // never confronts a debt this transcript no longer carries. Same ENOENT-only tolerance.
+      if (staleOwn) {
+        try { unlinkSync(pendingPath); }
+        catch (e) { if ((e as NodeJS.ErrnoException).code !== 'ENOENT') throw e; }
+      }
       outcome = { status: 'none', scannedBytes: consumed, offset: newOffset };
     }
     // Commit the debt BEFORE its offset: an interruption must leave these bytes replayable.
     writeJsonAtomic(statePath, { schema: 1, transcript: transcriptPath, offset: newOffset });
-    return outcome;
+    // FR-4: the adopted flat files go only AFTER the per-session copies are committed — a failure
+    // above leaves them in place for the next scan to adopt again. Best-effort: leftover debris
+    // is harmless (a present per-session file blocks re-adoption), a thrown error here would
+    // misreport an already-committed scan.
+    if (adoptLegacyPending) { try { unlinkSync(legacyPendingPath); } catch { /* debris */ } }
+    if (adoptLegacyState) { try { unlinkSync(legacyStatePath); } catch { /* debris */ } }
+    sweepStaleSessionDirs(dzDir, dir, nowIso === undefined ? Date.now() : Date.parse(nowIso));
+    return { ...outcome, ...ids };
   } catch {
-    return { status: 'none', scannedBytes: 0, offset: 0 };
+    return { status: 'none', scannedBytes: 0, offset: 0, ...ids };
+  }
+}
+
+/**
+ * FR-5: remove dead sessions' dirs — `<dzDir>/retro/<x>/` whose `scan-state.json` mtime is older
+ * than {@link RETRO_SESSION_STALE_MS}. The scanning session's own dir is excluded; a dir with no
+ * readable scan-state cannot be dated and is left alone; every error is swallowed; at most
+ * {@link RETRO_SWEEP_MAX_ENTRIES} entries are examined (one readdir + ≤64 stats — NFR-1).
+ */
+function sweepStaleSessionDirs(dzDir: string, ownDir: string, nowMs: number): void {
+  let names: string[];
+  try { names = readdirSync(join(dzDir, RETRO_SESSION_DIRNAME)).slice(0, RETRO_SWEEP_MAX_ENTRIES); } catch { return; }
+  for (const name of names) {
+    const d = join(dzDir, RETRO_SESSION_DIRNAME, name);
+    if (d === ownDir) continue;
+    try {
+      const age = nowMs - statSync(join(d, RETRO_SESSION_STATE_BASENAME)).mtimeMs;
+      if (age > RETRO_SESSION_STALE_MS) rmSync(d, { recursive: true, force: true });
+    } catch { /* undatable or vanished: leave it */ }
   }
 }
 
@@ -851,6 +969,10 @@ export function retroSentinelIsFresh(
   ctx: { sessionId?: string; transcriptPath?: string; nowMs: number },
 ): boolean {
   if (typeof sentinel.snippet !== 'string' || sentinel.snippet === '') return false;
+  // AM-1 (retro-debt-sentinel-per-session): an EMPTY session id carries no identity — a sentinel that
+  // names no session never matches anyone, and an empty ctx id is the same as none (the hook side
+  // returns '' before any fs call for it; this is the core half of the same rule).
+  if (sentinel.sessionId === '') return false;
   if (typeof ctx.sessionId === 'string' && ctx.sessionId !== '') return sentinel.sessionId === ctx.sessionId;
   if (typeof ctx.transcriptPath === 'string' && ctx.transcriptPath !== '') return sentinel.transcript === ctx.transcriptPath;
   const ts = typeof sentinel.ts === 'string' ? Date.parse(sentinel.ts) : NaN;

package/src/sign.ts

@@ -46,6 +46,13 @@ export interface VerifyFailure {
 export interface VerifyResult {
   readonly ok: boolean;
   readonly failures: readonly VerifyFailure[];
+  /**
+   * Paths that failed the sweep with {@link OUTSIDE_FILES_REASON}: present in the DIRECTORY, not in
+   * the manifest, and outside `package.json.files` — the packer would never ship them. They are still
+   * failures (AM-1: nothing is skipped); this list only lets a caller say how many of the failures
+   * describe the directory rather than the pack. Absent when there are none.
+   */
+  readonly outsideFiles?: readonly string[];
 }
 
 
@@ -371,6 +378,121 @@ export function listSignablePackFiles(root: string): string[] {
   return out.sort();
 }
 
+/**
+ * The wording for a swept path that `package.json.files` would keep OUT of the tarball (feature
+ * verify-pack-sweep-respects-files, AM-1). MEASURED 2026-09-20 (backlog 338a3b59c878430c): right after
+ * `dz sign`, `dz verify-pack` over harness-core's directory named `coverage/coverage-final.json` and
+ * `CHANGELOG.md` as «present in the pack but not signed», while `npm pack --dry-run` shipped 922 files,
+ * ZERO of them coverage and no CHANGELOG — `files` limits the tarball to six entries. The sweep walks the
+ * DIRECTORY (by decision — see `verifyManifest`), so the reason must say so instead of saying PACK.
+ */
+export const OUTSIDE_FILES_REASON =
+  'present in the directory but not signed — outside package.json.files, the packer would not ship it';
+
+/**
+ * npm's always-included ROOT files, MEASURED from npm's own packer rather than its docs
+ * (`/usr/lib/node_modules/npm/node_modules/npm-packlist/lib/index.js:283-286`, fix round 1, 2026-09-25):
+ *   `readme{,.*[^~$]}`, `copying{,.*[^~$]}`, `license{,.*[^~$]}`, `licence{,.*[^~$]}` — case-insensitive.
+ * That is the BARE name or `name.<ext>` where the extension does not end in `~` or `$` (editor backups and
+ * lock-style droppings). So `README.md`, `readme.txt`, `COPYING`, `LICENCE.md` are inside; `README-old`
+ * (no dot), `LICENSE.md~`, `README.` (empty extension) are NOT. Plus `package.json`, which npm always ships.
+ * NOT `CHANGELOG*`: MEASURED 2026-09-20, pnpm pack of harness-core omitted `CHANGELOG.md` while `files` did
+ * not name it — the npm docs list CHANGES/CHANGELOG/HISTORY, the packer does not; we follow the packer.
+ */
+export const NPM_ALWAYS_INCLUDED = /^(package\.json|(readme|copying|licen[cs]e)(\..*[^~$])?)$/i;
+
+/** What `package.json` says the tarball contains: normalised `files` entries plus `main` and the bin targets. */
+export interface PackAllowlist {
+  readonly entries: readonly string[];
+  readonly main: string | null;
+  readonly bins: readonly string[];
+}
+
+/**
+ * POSIX separators, no leading `./`, no trailing `/`. Every trailing slash goes — MEASURED fix round 1:
+ * `'.//'` used to survive as `'/'` (a phantom entry) because the strip kept one character; an entry that is
+ * nothing but slashes is empty after normalisation and must be dropped (AM-2).
+ */
+function normalisePackPath(p: string): string {
+  let s = p.replace(/\\/g, '/');
+  while (s.startsWith('./')) s = s.slice(2);
+  while (s.endsWith('/')) s = s.slice(0, -1);
+  return s;
+}
+
+/**
+ * `null` unless `pkg.files` is a non-empty array of strings — and `null` means «no allowlist, behaviour
+ * unchanged», never «everything is outside». Pure: the caller reads and parses `package.json`.
+ */
+export function packAllowlistFromPackageJson(pkg: unknown): PackAllowlist | null {
+  if (!pkg || typeof pkg !== 'object') return null;
+  const { files, main, bin } = pkg as { files?: unknown; main?: unknown; bin?: unknown };
+  if (!Array.isArray(files) || files.length === 0 || !files.every((f) => typeof f === 'string')) return null;
+  const entries = (files as string[]).map(normalisePackPath).filter((e) => e.length > 0);
+  if (entries.length === 0) return null;
+  const binValues: string[] =
+    typeof bin === 'string' ? [bin]
+    : bin && typeof bin === 'object' ? Object.values(bin as Record<string, unknown>).filter((v): v is string => typeof v === 'string')
+    : [];
+  return {
+    entries,
+    main: typeof main === 'string' ? normalisePackPath(main) : null,
+    bins: binValues.map(normalisePackPath),
+  };
+}
+
+const GLOB_CHARS = /[*?[]/;
+
+/**
+ * Minimal `*`-only matcher over the WHOLE relative path: `*` matches any run of characters, `/` included
+ * (so `types/**` and `types/*` both cover `types/deep/x.d.ts`). `?`, `[…]` and `{a,b}` are NOT interpreted —
+ * an entry carrying them falls back to a literal comparison, which can only UNDER-match (⇒ the plain pack
+ * wording, never a false «outside»). Kept deliberately small (NFR-2): this is a wording aid, not a packer.
+ */
+function globStarMatch(pattern: string, rel: string): boolean {
+  const parts = pattern.split('*');
+  if (parts.length === 1) return pattern === rel;
+  if (!rel.startsWith(parts[0]!)) return false;
+  let pos = parts[0]!.length;
+  for (let i = 1; i < parts.length - 1; i += 1) {
+    const at = rel.indexOf(parts[i]!, pos);
+    if (at < 0) return false;
+    pos = at + parts[i]!.length;
+  }
+  const last = parts[parts.length - 1]!;
+  return last === '' || (rel.endsWith(last) && rel.length - last.length >= pos);
+}
+
+/**
+ * Would the packer ship `rel`? True when `rel` equals an entry, sits under an entry directory, matches a
+ * `*` glob entry, equals `main` or a bin target, or is a ROOT-level always-included file. `docs/README.md`
+ * is not root-level and is therefore outside unless `docs` is an entry.
+ */
+export function isInsidePackAllowlist(rel: string, allow: PackAllowlist): boolean {
+  const p = normalisePackPath(rel);
+  if (!p.includes('/') && NPM_ALWAYS_INCLUDED.test(p)) return true;
+  if (allow.main === p || allow.bins.includes(p)) return true;
+  for (const entry of allow.entries) {
+    if (GLOB_CHARS.test(entry)) {
+      if (globStarMatch(entry, p)) return true;
+      continue;
+    }
+    if (p === entry || p.startsWith(entry + '/')) return true;
+  }
+  return false;
+}
+
+/** `<root>/package.json` → allowlist; absent, symlinked, unreadable or invalid JSON ⇒ `null` (unchanged behaviour). */
+function readPackAllowlist(root: string): PackAllowlist | null {
+  try {
+    const bytes = readRegularFileNoFollow(join(root, 'package.json'));
+    if (bytes === null) return null;
+    return packAllowlistFromPackageJson(JSON.parse(bytes.toString('utf8')));
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The bytes that get signed (FR-7). Sorted by path, LF endings, no trailing whitespace, and no
  * dependence on JSON key order — a signature must not depend on how a serialiser felt that day.
@@ -533,7 +655,20 @@ export function verifyManifest(
     if (!listed.has(p)) failures.push({ path: p, reason: 'present in the pack but not signed' });
   }
 
-  return { ok: failures.length === 0, failures };
+  // AM-1 (feature verify-pack-sweep-respects-files): the sweep above is the recorded decision and stays
+  // byte-identical — every visible path participates, nothing is skipped, the verdict is unchanged. This
+  // pass changes WORDING only: a swept path that `package.json.files` keeps out of the tarball is reported
+  // as «present in the directory …» (OUTSIDE_FILES_REASON) instead of «present in the pack …», because it
+  // never was going to be in the pack. No `files` (or an unreadable package.json) ⇒ nothing is relabelled.
+  const allow = readPackAllowlist(root);
+  const outside: string[] = [];
+  const reported: VerifyFailure[] = allow === null ? failures : failures.map((f) => {
+    if (f.reason !== 'present in the pack but not signed' || isInsidePackAllowlist(f.path, allow)) return f;
+    outside.push(f.path);
+    return { path: f.path, reason: OUTSIDE_FILES_REASON };
+  });
+
+  return { ok: reported.length === 0, failures: reported, ...(outside.length > 0 ? { outsideFiles: outside } : {}) };
 }
 
 /**