failproofai 1.0.2-beta.7 → 1.0.2-beta.9

package/src/hooks/pack-cli.ts

@@ -8,13 +8,14 @@
 import { execFileSync } from "node:child_process";
 import { homedir, tmpdir } from "node:os";
 import { createHash } from "node:crypto";
-import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { INTEGRATION_TYPES } from "./types";
-import { PACK_VERSION_RE } from "./pack-manifest";
+import { PACK_COMMIT_RE, PACK_VERSION_RE } from "./pack-manifest";
 import { detectInstalledClis } from "./integrations";
 import { parsePackIdentity, parsePackPolicy, readInstalledPacks } from "./pack-manifest";
 import {
+  AmbiguousPackId,
   PACK_CHECKSUMS_ASSET,
   PACK_ENTRY_ASSET,
   PACK_MANIFEST_ASSET,
@@ -22,6 +23,7 @@ import {
   checkPackArtifact,
   fetchPackPreview,
   packTagMatchesVersion,
+  parsePackSpec,
   removePack,
   setPackPolicyEnabled,
   slugifyCategory,
@@ -48,9 +50,27 @@ import {
 export interface PackCliResult {
   lines: string[];
   exitCode: number;
+  /**
+   * What a successful `build` produced, for a caller that has to describe it
+   * somewhere other than the terminal — today only `publish`, writing the
+   * release body. Carried on the RESULT rather than recomputed by the caller,
+   * because recomputing means re-deriving `defaultEnabled` from a second copy
+   * of the same rule, and the two copies drift.
+   */
+  meta?: PackBuildMeta;
 }
 
-const ok = (lines: string[]): PackCliResult => ({ lines, exitCode: 0 });
+export interface PackBuildMeta {
+  policies: number;
+  defaultOn: number;
+  commit?: string;
+}
+
+const ok = (lines: string[], meta?: PackBuildMeta): PackCliResult => ({
+  lines,
+  exitCode: 0,
+  ...(meta ? { meta } : {}),
+});
 const fail = (lines: string[]): PackCliResult => ({ lines, exitCode: 1 });
 
 function parseList(rest: string[], flag: string): string[] | undefined {
@@ -159,7 +179,24 @@ function parseCliList(rest: string[]): { clis?: string[] } | { error: string[] }
     }
   }
   const names = values.map((v) => v.trim()).filter(Boolean);
-  if (names.length === 0) return { clis: [] };
+  // `--cli` with nothing after it is a typo, not a scope.
+  //
+  // It used to become `clis: []`, which `installed.json` stores verbatim and
+  // `handler.ts` reads as "guard NO agent" (`pack.clis && !includes(cli)`) —
+  // so `policies add <pack> --cli` exited 0, printed "enabled (1/3, the pack's
+  // defaults)", and installed a pack that enforced nowhere. `--cli` is last on
+  // the line, or followed by the source or another flag, more easily than any
+  // other flag: `looksLikeCliName` stops at anything with a `-` or a `/`.
+  // Refused the same way `--policy` and `--category` refuse an empty list, and
+  // before anything is fetched.
+  if (names.length === 0) {
+    return {
+      error: [
+        "--cli needs at least one agent name, comma-separated",
+        `--cli takes any of: ${INTEGRATION_TYPES.join(", ")}`,
+      ],
+    };
+  }
 
   const known = new Set<string>(INTEGRATION_TYPES);
   const unknown = names.filter((n) => !known.has(n));
@@ -195,6 +232,7 @@ function selectionFrom(rest: string[]): {
   categories?: string[];
   all?: boolean;
   clis?: string[];
+  merge?: boolean;
   /** Present when the selection itself is unusable — see `parseCliList`. */
   error?: string[];
 } {
@@ -209,6 +247,11 @@ function selectionFrom(rest: string[]): {
     ...(categories ? { categories } : {}),
     ...(parsedClis.clis ? { clis: parsedClis.clis } : {}),
     ...(rest.includes("--all") ? { all: true } : {}),
+    // A FLAG adds. The command's first word is `add`, and on an
+    // already-installed pack `--category Git` means "also turn Git on" rather
+    // than "make Git the only thing on". The interactive picker overrides this
+    // back to false, because its list is the complete answer.
+    merge: true,
   };
 }
 
@@ -249,6 +292,7 @@ async function build(rest: string[]): Promise<PackCliResult> {
   const entry = packAddSource(rest) ?? flag("entry");
   const id = flag("id");
   const version = flag("version");
+  const commit = flag("commit");
   const effect = flag("effect") ?? "enforce";
   const outDir = resolve(flag("out") ?? "dist-pack");
 
@@ -258,9 +302,9 @@ async function build(rest: string[]): Promise<PackCliResult> {
       "       [--out <dir>] [--effect enforce|observe]",
     ]);
   }
-  let identity: { id: string; version: string; effect: PolicyEffect };
+  let identity: { id: string; version: string; effect: PolicyEffect; commit?: string };
   try {
-    identity = parsePackIdentity({ id, version, effect });
+    identity = parsePackIdentity({ id, version, effect, commit });
   } catch (err) {
     return fail([err instanceof Error ? err.message : String(err)]);
   }
@@ -338,9 +382,19 @@ async function build(rest: string[]): Promise<PackCliResult> {
     }
   }
 
+  // `commit` is omitted entirely rather than written as null when there is none.
+  // The manifest is hashed and the hash is the pin, so every byte in here is
+  // part of what a machine verifies — a field carrying "there was nothing to
+  // say" earns none of that cost. Readers already treat absence as ordinary.
   const manifest =
     JSON.stringify(
-      { id: identity.id, version: identity.version, effect: identity.effect, policies },
+      {
+        id: identity.id,
+        version: identity.version,
+        effect: identity.effect,
+        ...(identity.commit ? { commit: identity.commit } : {}),
+        policies,
+      },
       null,
       2,
     ) + "\n";
@@ -365,7 +419,50 @@ async function build(rest: string[]): Promise<PackCliResult> {
     "",
     `Publish: attach all three to a GitHub release tagged ${identity.version}, then anyone runs:`,
     `  failproofai policies add <owner>/<repo>`,
-  ]);
+  ], { policies: policies.length, defaultOn: on, ...(identity.commit ? { commit: identity.commit } : {}) });
+}
+
+/**
+ * The release body, and the format `--releases` reads back out of it.
+ *
+ * Two audiences, one string. A person opening the releases page sees what the
+ * release contains; `policies show --releases` parses the same lines rather
+ * than downloading a manifest per release. Keep them parseable — the reader is
+ * `parseReleaseBody` directly below, and the two have to move together.
+ *
+ * Nothing here is TRUSTED. It is publisher-controlled text on somebody else's
+ * repository, so it decides what a listing displays and never what a machine
+ * installs: the manifest inside the digest-pinned assets remains the only
+ * source for that.
+ */
+export function releaseBody(id: string, version: string, meta?: PackBuildMeta): string {
+  const lines = [`${id}@${version}`];
+  if (meta) {
+    lines.push("", `${meta.policies} policies, ${meta.defaultOn} on by default`);
+    if (meta.commit) lines.push(`commit ${meta.commit}`);
+  }
+  return lines.join("\n") + "\n";
+}
+
+export interface ReleaseBodyFacts {
+  policies?: number;
+  defaultOn?: number;
+  commit?: string;
+}
+
+/** Read back what {@link releaseBody} wrote. Absent facts stay absent — a
+ *  release published before this format, or by hand, simply says less. */
+export function parseReleaseBody(body: string | null | undefined): ReleaseBodyFacts {
+  const text = typeof body === "string" ? body : "";
+  const facts: ReleaseBodyFacts = {};
+  const counts = /(\d+)\s+policies,\s*(\d+)\s+on by default/.exec(text);
+  if (counts) {
+    facts.policies = Number(counts[1]);
+    facts.defaultOn = Number(counts[2]);
+  }
+  const commit = /(?:^|\n)\s*commit\s+([0-9a-f]{7,40})\b/i.exec(text);
+  if (commit) facts.commit = commit[1].toLowerCase();
+  return facts;
 }
 
 /**
@@ -513,7 +610,7 @@ async function scaffold(target: string | null): Promise<PackCliResult> {
   if (!chosen && process.stdin.isTTY && process.stdout.isTTY) {
     const answer = await promptText({
       message: "What is this pack called?",
-      hint: "used for the filename — letters, numbers, dashes",
+      hint: "used for the filename",
       defaultValue: "my-policies",
       validate: (v) =>
         /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(v.trim())
@@ -600,34 +697,294 @@ function inferRepo(entryPath: string): string | null {
 }
 
 /**
- * A tag on HEAD, when there is one and the file is clean.
+ * The commit the policies being published are sitting at.
+ *
+ * This DECIDES the version and gates the publish — `versionForPublish` reads
+ * both fields. It used to be a label that did neither, which is why the reads
+ * below are stricter than they look. A pack published from a directory that is
+ * not a git checkout has no commit; absence is ordinary and returns null the
+ * same way `inferRepo` does, and the refusal is spelled out one caller up.
  *
- * Somebody who tagged `v1.2.0` has SAID what this release is, which a counted
- * number cannot. Absent a tag there is nothing here to infer — the version is
- * counted from what the repository has already published instead.
+ * Read from the ENTRY FILE's directory rather than the process cwd, for the
+ * reason `inferRepo` gives: a policy that lives in another checkout is normal,
+ * and the answer has to describe the file rather than wherever the shell is.
+ *
+ * `dirty` still travels beyond the version: with `--version` given, a dirty
+ * tree publishes anyway and the recorded `commit` is then an approximation.
+ *
+ * `outDir` is the directory the build is about to write into, and everything
+ * under it is left OUT of the dirty read — see {@link skipOutDir} for the
+ * self-inflicted refusal that costs.
  */
-function inferTaggedVersion(entryPath: string): string | null {
+function inferCommit(
+  entryPath: string,
+  outDir?: string,
+  sources?: string[],
+): Provenance | null {
   const cwd = resolve(entryPath, "..");
+  // Two readers over one runner: `raw` for output whose LEADING bytes carry
+  // meaning (a porcelain status column is a space), `git` for the rest.
+  const raw = (args: string[]): string | null => {
+    try {
+      return execFileSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 5_000,
+      });
+    } catch {
+      return null;
+    }
+  };
   const git = (args: string[]): string | null => {
+    const out = raw(args);
+    return out === null ? null : out.trim();
+  };
+  const sha = git(["rev-parse", "HEAD"]);
+  if (!sha || !/^[0-9a-f]{40}$/.test(sha)) return null;
+  // `git()` answers "" for a clean tree and null when it could not run the
+  // command at all, and the `Boolean()` this used to be read BOTH as clean.
+  // Harmless while `dirty` was a label; now that it decides the version, an
+  // unreadable status minted a commit-named version for bytes nobody had
+  // checked against that commit — the one claim this scheme exists to refuse.
+  // Reachable, not theoretical: `rev-parse` never touches the index, so a repo
+  // whose index is unreadable answers the first question and fails the second,
+  // and `status` walks the whole worktree so it is also the one that hits the
+  // 5s timeout. Unknown therefore falls on the dirty side: refusing a tree we
+  // cannot vouch for costs one `--version`, and the alternative is publishing
+  // one we could not read.
+  const status = git(["status", "--porcelain", ...skipOutDir(git, entryPath, outDir)]);
+  // The sources are checked BY NAME as well as the tree as a whole. A clean
+  // tree does not mean the bytes being bundled are in HEAD: `.gitignore` hides
+  // a source from the tree read entirely, and the artifact would then carry a
+  // commit that does not contain it.
+  const sourceState = sources ? sourcesInHead(git, raw, sources) : ({ ok: true } as const);
+  return {
+    sha,
+    dirty: status !== "" || !sourceState.ok,
+    ...(sourceState.ok ? {} : { unpublishable: sourceState }),
+  };
+}
+
+/**
+ * `git status --porcelain -z`, parsed.
+ *
+ * The format is NOT one record per NUL field. Each entry is `XY <path>`, and a
+ * rename or copy is followed by its ORIGINAL path as a separate NUL field
+ * carrying NO status prefix:
+ *
+ *     R  b.mjs\0a.mjs\0
+ *
+ * Splitting on NUL and slicing three characters off every field therefore turns
+ * `a.mjs` into `js` — a path that resolves to nothing, is in nobody's file set,
+ * and made `publish` refuse a policy file its author had simply renamed. The
+ * original has to be CONSUMED by the entry that produced it.
+ */
+function porcelainEntries(status: string): Array<{ code: string; path: string; from?: string }> {
+  const fields = status.split("\0");
+  const out: Array<{ code: string; path: string; from?: string }> = [];
+  for (let i = 0; i < fields.length; i += 1) {
+    const entry = fields[i];
+    if (!entry || entry.length < 4) continue;
+    const code = entry.slice(0, 2);
+    const path = entry.slice(3);
+    if (code.startsWith("R") || code.startsWith("C")) {
+      const from = fields[i + 1];
+      i += 1;
+      out.push({ code, path, ...(from ? { from } : {}) });
+      continue;
+    }
+    out.push({ code, path });
+  }
+  return out;
+}
+
+/** What a checkout says about the bytes being published. `unpublishable` names
+ *  the sources that are not in HEAD, so the refusal can list them. */
+export interface Provenance {
+  sha: string;
+  dirty: boolean;
+  unpublishable?: { offending: string[]; why: "missing" | "modified" };
+}
+
+/**
+ * Whether every file about to be BUNDLED is in HEAD and unmodified.
+ *
+ * The whole-tree read above answers "is this checkout clean", which is a
+ * different question and misses three ways a source reaches the artifact
+ * without reaching the commit:
+ *
+ * - **Ignored files.** `git status --porcelain` omits anything `.gitignore`
+ *   matches, even with `--untracked-files=all`. A policy file the author
+ *   ignored therefore read as clean, got bundled, and the manifest recorded
+ *   HEAD as the commit it came from — bytes that commit does not contain.
+ * - **Untracked files in an otherwise clean tree**, for the same reason once
+ *   the ignore rules are wide.
+ * - **A tag.** `inferTaggedVersion` checked only the ENTRY, while `publish`
+ *   bundles every discovered policy file. A tagged commit, a clean entry and a
+ *   modified sibling published that sibling under a tag naming a commit
+ *   without it.
+ *
+ * One check for all of them, run against the actual source LIST, because that
+ * is the set whose bytes end up in the artifact — and provenance is a claim
+ * about those bytes and nothing else.
+ *
+ * `-z` rather than line splitting: git C-quotes a path containing a newline or
+ * a quote, so the parsed path is escape sequences that resolve to no file, and
+ * a legal filename containing ` -> ` is truncated by the rename split. NUL
+ * separation has neither problem — and a rename arrives as two NUL-separated
+ * fields rather than one arrow-joined line — which is what
+ * {@link porcelainEntries} reads.
+ */
+/**
+ * A path spelled the way git spells it: symlinks resolved.
+ *
+ * `rev-parse --show-toplevel` answers with the RESOLVED root, so a source named
+ * through a symlinked directory — `publish ~/policies/guards.mjs`, where
+ * `~/policies` links into a checkout — measures as outside the repository
+ * against it, and a committed, untouched file was reported as never committed
+ * with `git add -f` as the advice, which does nothing for it.
+ *
+ * It cuts the other way too, which is why this resolves the SOURCES rather than
+ * only un-resolving the root: a policy file that is itself a symlink out of the
+ * repository has a blob in HEAD holding the link's TARGET NAME, while the bytes
+ * bundled are the target's. Asking about the link's own path called that
+ * publishable and recorded a commit containing none of those bytes.
+ *
+ * Falls back to the path as given when it cannot be resolved, so a source that
+ * has since been deleted is still reported rather than throwing here.
+ */
+function realOrSelf(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+function sourcesInHead(
+  git: (args: string[]) => string | null,
+  raw: (args: string[]) => string | null,
+  sources: string[],
+): { ok: true } | { ok: false; offending: string[]; why: "missing" | "modified" } {
+  const paths = sources.map((f) => realOrSelf(resolve(f)));
+  // Present in the commit at all. `cat-file -e HEAD:<path>` is the cheapest
+  // question that distinguishes "tracked and committed" from "tracked but
+  // added only to the index", which `ls-files` would answer yes to.
+  const shown = git(["rev-parse", "--show-toplevel"]);
+  const top = shown === null ? null : realOrSelf(resolve(shown));
+  const missing: string[] = [];
+  for (const path of paths) {
+    const rel = top ? relative(top, path) : null;
+    if (!rel || rel.startsWith("..") || isAbsolute(rel)) {
+      missing.push(path);
+      continue;
+    }
+    if (git(["cat-file", "-e", `HEAD:${rel}`]) === null) missing.push(path);
+  }
+  if (missing.length > 0) return { ok: false, offending: missing, why: "missing" };
+
+  // `--ignored=matching` so an ignored source is REPORTED rather than omitted,
+  // which is the whole point of asking about the sources by name.
+  const status = raw([
+    "status", "--porcelain", "-z", "--untracked-files=all", "--ignored=matching",
+    "--", ...paths,
+  ]);
+  if (status === null) return { ok: false, offending: paths, why: "modified" };
+  // Both halves of a rename count: either one being listed means the set on
+  // disk is not the set HEAD holds.
+  const dirty = porcelainEntries(status).flatMap((entry) =>
+    [entry.path, entry.from].filter(Boolean).map((path) => resolve(top ?? ".", path as string)),
+  );
+  if (dirty.length > 0) return { ok: false, offending: dirty, why: "modified" };
+  return { ok: true };
+}
+
+/**
+ * The build output directory, spelled as a pathspec `git status` skips.
+ *
+ * `publish` writes its three assets to `dist-pack` under the cwd unless told
+ * otherwise, so the documented `cd my-policies && failproofai publish` leaves
+ * untracked build output INSIDE the checkout it just read. Without this, the
+ * next publish of an unchanged, fully committed tree reads that output as
+ * uncommitted changes and refuses — the command breaking its own second run,
+ * over a directory it wrote itself, with a remedy (`git add -A`) that commits
+ * build output into the pack repository.
+ *
+ * Narrow on purpose, because hiding a change from this read is hiding the one
+ * thing the commit version claims. Nothing is skipped when the output lands
+ * outside the repository, which cannot dirty it anyway, and nothing is skipped
+ * when the output directory CONTAINS the entry file — `--out .` in a folder of
+ * policies is a directory full of source, where skipping it would conceal
+ * exactly what the check exists to catch.
+ */
+function skipOutDir(
+  git: (args: string[]) => string | null,
+  entryPath: string,
+  outDir: string | undefined,
+): string[] {
+  if (!outDir) return [];
+  const out = resolve(outDir);
+  if (resolve(entryPath).startsWith(out + sep)) return [];
+  const top = git(["rev-parse", "--show-toplevel"]);
+  if (!top) return [];
+  const rel = relative(resolve(top), out);
+  if (!rel || rel.startsWith("..") || isAbsolute(rel)) return [];
+  // `top` on the exclusion is what makes it mean the directory it names: `rel`
+  // is measured from the repository root, while a pathspec is read relative to
+  // the directory git runs in — the ENTRY's folder. Without it, publishing
+  // `guards/policies.mjs` would exclude `guards/dist-pack` and leave the real
+  // `dist-pack/` in the read, so the self-inflicted refusal comes straight
+  // back for anyone whose policies sit in a subdirectory.
+  //
+  // The leading `:(top)` states the whole-repository scope rather than leaning
+  // on git's rule that a list of exclusions alone applies to all paths, and
+  // `literal` stops a directory named with a glob character from taking its
+  // neighbours out of the read with it.
+  return ["--", ":(top)", `:(exclude,literal,top)${rel.split(sep).join("/")}`];
+}
+
+/**
+ * A tag on HEAD, when there is one and the file is clean.
+ *
+ * Somebody who tagged `v1.2.0` has SAID what this release is, which a derived
+ * name cannot — so this wins over the commit version. Absent a tag there is
+ * nothing here to infer, and the commit the tree sits at is used instead.
+ */
+function inferTaggedVersion(entryPath: string, sources?: string[]): string | null {
+  const cwd = resolve(entryPath, "..");
+  const raw = (args: string[]): string | null => {
     try {
       return execFileSync("git", args, {
         cwd,
         encoding: "utf8",
         stdio: ["ignore", "pipe", "ignore"],
         timeout: 5_000,
-      }).trim();
+      });
     } catch {
       return null;
     }
   };
+  const git = (args: string[]): string | null => {
+    const out = raw(args);
+    return out === null ? null : out.trim();
+  };
   const tag = git(["describe", "--tags", "--exact-match", "HEAD"]);
   if (!tag || !PACK_VERSION_RE.test(tag)) return null;
   // A tag NAMES a commit, so shipping edited bytes under it publishes something
   // that commit does not contain — and two artifacts would claim one version,
   // which `id|version|sha256` compares in both the audit key and the pack
-  // upsert. A counted version names no commit and has no such problem, so this
-  // refusal belongs to the tagged path alone.
-  if (git(["status", "--porcelain", "--", entryPath])) return null;
+  // upsert. Compared against "" rather than tested for truthiness for the reason
+  // `inferCommit` gives: null is "could not read the tree", and reading that as
+  // clean is how a dirty tree slips out under a tag that does not describe it.
+  // Every source that will be BUNDLED, not just the entry. `publish` discovers
+  // and bundles each policy file in the directory, so a tagged commit with a
+  // clean entry and a modified sibling published that sibling under a tag
+  // naming a commit without it. Same check the sha path uses, so the two
+  // cannot disagree about what "this commit contains these bytes" means.
+  const covered = sourcesInHead(git, raw, sources ?? [entryPath]);
+  if (!covered.ok) return null;
+  if (git(["status", "--porcelain", "--", entryPath]) !== "") return null;
   return tag;
 }
 
@@ -679,45 +1036,425 @@ function findEntry(dir: string): string[] {
 }
 
 /**
- * The version after whatever this repository has already published.
- *
- * A commit SHA names exactly where bytes came from and tells a reader nothing
- * else: it does not order, so `a1b2c3d` and `f9e8d7c` give no clue which came
- * first, and nobody can say "I am on the older one". Counting instead — 1.0.0,
- * then 1.0.1 — costs one API call and answers both.
- *
- * Reads the repository's own releases rather than anything local, because the
- * releases ARE the published record: a machine that has never published from
- * this checkout still computes the right next number, and two people publishing
- * from different clones cannot both mint 1.0.1 without one of them seeing the
- * other's release first.
- *
- * Non-semver tags are ignored rather than parsed heroically — a repo whose
- * releases are named `nightly` has no sequence to continue, and starting a
- * fresh count is more honest than inventing one.
+ * Every relative specifier a source file names, in the four spellings a bundler
+ * follows. Anchored to a line start for the two import FORMS, because that is
+ * where a real one is: a `"./x.mjs"` inside a policy's own deny message is a
+ * string, not an edge of the module graph, and the file it happens to spell
+ * should not be dragged into a provenance check it has nothing to do with.
  */
-async function nextVersion(owner: string, name: string, token: string): Promise<string> {
-  const res = await gh(`${GITHUB_API}/repos/${owner}/${name}/releases?per_page=100`, token);
-  const tags = Array.isArray(res.json)
-    ? (res.json as unknown as Array<{ tag_name?: unknown }>)
-        .map((r) => (typeof r.tag_name === "string" ? r.tag_name : ""))
-        .filter(Boolean)
-    : [];
-  let best: [number, number, number] | null = null;
-  for (const tag of tags) {
-    const m = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(tag.trim());
-    if (!m) continue;
-    const parsed: [number, number, number] = [Number(m[1]), Number(m[2]), Number(m[3])];
-    if (
-      !best ||
-      parsed[0] > best[0] ||
-      (parsed[0] === best[0] && parsed[1] > best[1]) ||
-      (parsed[0] === best[0] && parsed[1] === best[1] && parsed[2] > best[2])
-    ) {
-      best = parsed;
+const LOCAL_IMPORT_RES: readonly RegExp[] = [
+  /(?:^|\n)\s*(?:import|export)[^;\n]*?from\s*["'](\.[^"'\n]*)["']/g,
+  /(?:^|\n)\s*import\s*["'](\.[^"'\n]*)["']/g,
+  /\bimport\s*\(\s*["'](\.[^"'\n]*)["']\s*\)/g,
+  /\brequire\s*\(\s*["'](\.[^"'\n]*)["']\s*\)/g,
+];
+
+/** What a specifier without an extension can name on disk, in resolution order. */
+const LOCAL_IMPORT_EXTENSIONS: readonly string[] = [
+  "", ".mjs", ".js", ".ts", ".mts", ".cts", ".cjs", ".jsx", ".tsx", ".json",
+  "/index.mjs", "/index.js", "/index.ts",
+];
+
+/**
+ * The policy files plus everything they IMPORT.
+ *
+ * A file reaches the artifact by being imported, not only by being discovered.
+ * `findEntry` recognises policy files — ones that import failproofai and call
+ * `customPolicies.add` — while `bundleEntry` inlines whatever those files pull
+ * in, so a plain `./patterns.mjs` of shared matchers is in nobody's source list
+ * and in every byte of the bundle. Ignored, it is the exact bug
+ * {@link sourcesInHead} exists to close with a different file on the end of it:
+ * `git status` reports a clean tree, the policy file itself is committed, and
+ * the pack ships bytes HEAD does not contain under a version naming HEAD.
+ *
+ * Only files that EXIST are added, so a specifier this resolves differently
+ * from the bundler adds nothing rather than inventing a path to refuse over.
+ * Static and CommonJS spellings only — a computed `import(name)` is not
+ * followed here, and is not bundled either.
+ */
+function withLocalImports(sources: string[]): string[] {
+  const seen = new Set(sources.map((f) => resolve(f)));
+  const queue = [...seen];
+  // A pack is a handful of files; the cap is there so a cycle or a vendored
+  // tree cannot turn a publish into a filesystem walk.
+  while (queue.length > 0 && seen.size < 500) {
+    const file = queue.shift() as string;
+    let text: string;
+    try {
+      if (statSync(file).size > 512 * 1024) continue;
+      text = readFileSync(file, "utf8");
+    } catch {
+      continue;
     }
+    for (const re of LOCAL_IMPORT_RES) {
+      for (const match of text.matchAll(re)) {
+        const base = resolve(dirname(file), match[1]);
+        for (const ext of LOCAL_IMPORT_EXTENSIONS) {
+          const candidate = base + ext;
+          if (seen.has(candidate)) break;
+          try {
+            if (!statSync(candidate).isFile()) continue;
+          } catch {
+            continue;
+          }
+          seen.add(candidate);
+          queue.push(candidate);
+          break;
+        }
+      }
+    }
+  }
+  return [...seen];
+}
+
+/**
+ * Make the git claim TRUE instead of refusing it, where doing that is safe.
+ *
+ * The version names a commit, so publishing needs one — and the first version
+ * of this simply refused when there was not one, handing the user two commands
+ * to run and asking them to start again. That is a burden the tool can carry:
+ * it already knows the directory, and it already knows which files it is about
+ * to bundle.
+ *
+ * Two situations, and they are NOT the same risk, which is why only one of them
+ * is fully automatic:
+ *
+ * - **No checkout at all.** `git init` + commit everything. There is no history
+ *   to disturb, no branch to confuse and no unrelated work to sweep up: the
+ *   directory is inert until this runs. Safe. An initialised checkout that has
+ *   never been committed to reaches this case too — `rev-parse HEAD` answers
+ *   nothing for an unborn HEAD — and it is safe on the SAME terms only at that
+ *   checkout's root. Below the root the directory is not inert at all, so that
+ *   is refused rather than settled; see the branch itself for what it cost.
+ *
+ *
+ * - **A checkout with uncommitted changes.** `git add -A` here is NOT safe. It
+ *   sweeps up whatever else is in the tree — a half-finished edit in a sibling
+ *   file, a scratch `.env`, a debugging change nobody had decided on — and
+ *   "publish committed my unrelated work" is a far worse surprise than being
+ *   asked to commit. So only the POLICY FILES are committed, the ones publish
+ *   found and is about to bundle, and anything else dirty stops the run with
+ *   those files named. Committing the artifact's own inputs is defensible;
+ *   committing the rest of somebody's desk is not.
+ *
+ * TTY only. In CI a commit made here exists on the runner and nowhere else, so
+ * the version would name provenance nobody can resolve — `--version` is the
+ * answer there, and the refusal says so.
+ *
+ * Returns null when there is nothing to do or nothing safe to do, leaving
+ * {@link versionForPublish} to refuse with its own message.
+ */
+function settleGitState(
+  entryPath: string,
+  provenance: { sha: string; dirty: boolean } | null,
+  packFiles: string[],
+  id: string,
+  outDir: string | undefined,
+): { provenance: { sha: string; dirty: boolean }; lines: string[] } | { error: string[] } | null {
+  const cwd = resolve(entryPath, "..");
+  const raw = (args: string[]): string | null => {
+    try {
+      return execFileSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 30_000,
+      });
+    } catch {
+      return null;
+    }
+  };
+  const git = (args: string[]): string | null => {
+    const out = raw(args);
+    return out === null ? null : out.trim();
+  };
+  // A commit needs an identity, and a machine that has never configured one
+  // fails INSIDE `git commit` with a wall of advice about --global. Checked
+  // first so the refusal names the two commands rather than quoting git at
+  // somebody who did not run git.
+  const identity = (): string[] | null => {
+    if (git(["config", "user.email"]) && git(["config", "user.name"])) return null;
+    return [
+      "git has no name and email configured on this machine, so nothing can be committed.",
+      '  git config --global user.name "You"',
+      '  git config --global user.email "you@example.com"',
+      "Then publish again, or name the version yourself: --version <version>.",
+    ];
+  };
+
+  if (provenance === null) {
+    const problem = identity();
+    if (problem) return { error: problem };
+    // No commit is not the same fact as no repository. `inferCommit` reads
+    // `rev-parse HEAD`, and a checkout that has been initialised but never
+    // committed to answers nothing — so this branch is also where an UNBORN
+    // HEAD lands, and `git init` there is being run inside somebody's existing
+    // work tree.
+    //
+    // `--show-prefix` is git's own answer to "where am I in this work tree":
+    // null outside one, "" at its root, `policies/` below it. Asked of git
+    // rather than compared as paths because `cwd` is built from the entry
+    // argument and can carry symlinks that `--show-toplevel` resolves away,
+    // and a spelling difference would refuse a publish that is perfectly fine.
+    const prefix = git(["rev-parse", "--show-prefix"]);
+    if (prefix !== null && prefix !== "") {
+      // `git init` here created a NESTED repository inside the parent's work
+      // tree and committed into that. The pack was then versioned by a commit
+      // living in a repository the author will never push — the parent shows
+      // only an untracked `policies/` — so the version named provenance nobody
+      // could resolve, which is the one thing this whole path exists to avoid.
+      // Not settled automatically either: everything in an unborn checkout is
+      // untracked, so the only add that would work is one sweeping the parent's
+      // whole work tree, which is exactly the surprise the dirty branch below
+      // refuses to hand anyone.
+      return { error: [
+        "The version names a commit, and this folder is inside a git checkout that has no commits yet.",
+        `  ${prefix.replace(/\/$/, "")} — inside a repository whose first commit has not been made`,
+        "Make that first commit yourself, then publish again —",
+        "or name the version yourself: --version <version>.",
+      ] };
+    }
+    // Only when there is genuinely no repository. Re-initialising one that
+    // exists is a no-op git tolerates, but the line reported below would then
+    // claim to have started something that was already there.
+    if (prefix === null && git(["init", "-q"]) === null) return null;
+    // `-A` minus the build output. A first commit that swept in `dist-pack/`
+    // would put the artifact inside the very commit it is supposed to name.
+    //
+    // No `--` of its own: `skipOutDir` returns one ALREADY, along with the
+    // `:(top)` scope it needs. Adding a second separator made git read it as a
+    // literal filename, the add failed, and the commit then failed on an empty
+    // index — reported as "could not make the first commit", which is true and
+    // says nothing about why.
+    git(["add", "-A", ...skipOutDir(git, entryPath, outDir)]);
+    // Counted from the INDEX, not from the policy files. The first commit takes
+    // everything here — a README, a .gitignore, whatever else the author has
+    // beside their policies — and reporting the number of policy files instead
+    // understated what had just been committed on their behalf.
+    const staged = (git(["diff", "--cached", "--name-only"]) ?? "").split("\n").filter(Boolean).length;
+    if (git(["commit", "-q", "-m", `publish ${id}`]) === null) {
+      return { error: [
+        `Could not make the first commit in ${cwd}.`,
+        "Commit by hand, or name the version yourself: --version <version>.",
+      ] };
+    }
+    const made = inferCommit(entryPath, outDir, packFiles);
+    if (!made) return null;
+    const files = `${staged} file${staged === 1 ? "" : "s"}`;
+    return {
+      provenance: made,
+      lines: [
+        prefix === null
+          ? `Started a git repository here and committed ${files}.`
+          : `Made this repository's first commit — ${files}.`,
+      ],
+    };
+  }
+
+  if (!provenance.dirty) return null;
+
+  // Which paths are actually dirty, as git sees them — relative to the REPO
+  // ROOT, not to the entry's directory, which are different whenever the
+  // policies live in a subdirectory.
+  const root = git(["rev-parse", "--show-toplevel"]);
+  // The SAME exclusion `inferCommit` applied when it decided the tree was
+  // dirty. Without it this would try to commit the assets the last run wrote —
+  // which are gitignored in every pack this tool scaffolds, and are the build
+  // output either way.
+  // UNTRIMMED. A porcelain line is `XY <path>`, and for an unstaged edit the X
+  // column is a SPACE — so trimming the output eats the first line's leading
+  // space, and `slice(3)` then eats the first character of its path too. It
+  // reported `ests.mjs`, decided that was not one of the policy files, and
+  // refused the publish over a file that did not exist. Only the first line is
+  // affected, which is exactly the kind of wrongness that survives a casual
+  // test with two dirty files in it.
+  //
+  // `--untracked-files=all` because the default COLLAPSES a wholly untracked
+  // directory into one line naming the directory: a new `policies/` folder
+  // inside an existing checkout reads as `?? policies/` and never mentions the
+  // files in it. That path matches no policy file, so it landed in `foreign`
+  // and publish refused a brand new folder of policies by naming the folder
+  // itself as somebody else's work — the bootstrap case this whole function
+  // exists for. Only reproducible below the repository root; an untracked file
+  // AT the root is reported individually, which is why every fixture that
+  // publishes from the root missed it. The exclusion still applies, so the
+  // expansion does not drag the build output back into the read.
+  // `-z`, not line splitting.
+  //
+  // The line parser this replaces was wrong twice over on paths git is entitled
+  // to hand back. Git C-QUOTES a path containing a newline or a quote, so the
+  // value parsed out was escape sequences resolving to no file on disk — and a
+  // legal policy file named `guards -> final.mjs` was truncated to `final.mjs`
+  // by the rename split. Either way the path matched none of the pack's files,
+  // landed in `foreign`, and publish refused to commit its OWN source over a
+  // filename it had mangled itself.
+  //
+  // NUL separation has neither problem: no quoting is applied, and a rename
+  // arrives as two separate entries rather than one arrow-joined line — so the
+  // old path is listed in its own right, which is correct here, since a rename
+  // leaves the tree differing from HEAD at both ends.
+  const status = raw([
+    "status",
+    "--porcelain",
+    "-z",
+    "--untracked-files=all",
+    ...skipOutDir(git, entryPath, outDir),
+  ]);
+  if (root === null || status === null) return null;
+  const entries = porcelainEntries(status);
+  // The path that EXISTS is the one to stage and the one to judge. A rename's
+  // original is staged too — otherwise the deletion half is left uncommitted
+  // and the tree is still dirty afterwards — but it is NOT judged foreign on
+  // its own: renaming one of the pack's own files is the pack's business, and
+  // treating the vacated name as somebody else's file made publish refuse a
+  // policy file its author had merely renamed.
+  const dirty = entries.map((entry) => resolve(root, entry.path));
+  const renamedFrom = entries
+    .filter((entry) => entry.from)
+    .map((entry) => resolve(root, entry.from as string));
+  if (dirty.length === 0) return null;
+
+  const mine = new Set(packFiles.map((f) => resolve(f)));
+  const foreign = dirty.filter((path) => !mine.has(path));
+  // Staged alongside, so a rename lands whole.
+  const toStage = [...dirty, ...renamedFrom];
+  if (foreign.length > 0) {
+    return { error: [
+      `The version names a commit, and this tree has uncommitted changes outside the policy files.`,
+      ...foreign.slice(0, 8).map((path) => `  ${relative(root, path)}`),
+      ...(foreign.length > 8 ? [`  …and ${foreign.length - 8} more`] : []),
+      "Those are not this command's to commit. Commit or stash them, then publish again —",
+      "or name the version yourself: --version <version>.",
+    ] };
+  }
+
+  const problem = identity();
+  if (problem) return { error: problem };
+  git(["add", "--", ...toStage]);
+  if (git(["commit", "-q", "-m", `publish ${id}`]) === null) {
+    return { error: [
+      "Could not commit the policy files.",
+      "Commit by hand, or name the version yourself: --version <version>.",
+    ] };
   }
-  return best ? `${best[0]}.${best[1]}.${best[2] + 1}` : "1.0.0";
+  const made = inferCommit(entryPath, outDir, packFiles);
+  if (!made || made.dirty) return null;
+  return {
+    provenance: made,
+    lines: [`Committed ${dirty.length} changed policy file${dirty.length === 1 ? "" : "s"}.`],
+  };
+}
+
+/**
+ * How many characters of a commit a version names.
+ *
+ * Twelve, not git's default seven. Seven collides in a repository with enough
+ * objects — git itself lengthens the abbreviation as a repo grows — and a
+ * version that stops being unique is worse than a long one, because two
+ * artifacts would claim the same name. Twelve is short enough to read in a
+ * listing and long enough that no real pack repository will reach it.
+ *
+ * The FULL sha is still recorded as `commit` in the manifest, so nothing is
+ * lost by abbreviating the version.
+ */
+export const VERSION_SHA_LENGTH = 12;
+
+/** The version a commit names. */
+export function versionFromCommit(sha: string): string {
+  return sha.trim().toLowerCase().slice(0, VERSION_SHA_LENGTH);
+}
+
+/**
+ * The version this publish should carry: the commit it was built from.
+ *
+ * A version answers ONE question here — which source produced these bytes —
+ * and the commit answers it exactly, with nothing to decide and nothing to
+ * count. Nothing is read from the repository's releases: the version is a
+ * property of the tree in front of you, so a fresh clone, an air-gapped
+ * machine and a second publisher all compute the same answer for the same
+ * source, and none of them has to ask GitHub what happened before.
+ *
+ * The costs are real and are the reason this is an explicit choice rather than
+ * a default. A sha does not ORDER — `a1b2c3d` and `f9e8d7c` give no clue which
+ * came first — so "am I on the newest?" is a question only the release list can
+ * answer. `policies show <source> --releases` is where it is answered, newest
+ * first, which is why that surface exists.
+ *
+ * What it REFUSES rather than approximates, all for the same reason: the
+ * version claims to name a commit, so it must not be minted where that claim
+ * would be false.
+ *
+ * - **No git.** There is no commit to name. Publishing from a directory that
+ *   is not a checkout used to work; under this scheme it cannot, and saying so
+ *   beats inventing a number that names nothing.
+ * - **A dirty tree.** The bytes being published are not the bytes in that
+ *   commit, so the version — and `commit` in the manifest beside it — would
+ *   both point at source that does not contain them.
+ * - **A sha that is not one.** No caller in the publish path produces one, so
+ *   this is a guard rather than a case; see the comment on it below.
+ *
+ * `--version` overrides all of it, and every refusal names it for that reason.
+ */
+export function versionForPublish(
+  provenance: Provenance | null,
+): { version: string } | { error: string[] } {
+  if (!provenance) {
+    return {
+      error: [
+        "This pack is versioned by the commit it is built from, and this directory is not a git checkout.",
+        "  git init && git add -A && git commit -m \"first policies\"",
+        "Then publish again. To publish without git, name the version yourself: --version <version>.",
+      ],
+    };
+  }
+  // A source that is not in HEAD at all — ignored by `.gitignore`, or never
+  // committed — gets its own refusal. The generic "this tree has uncommitted
+  // changes" is wrong for it and its remedy (`git add -A && git commit`) does
+  // not work: an ignored file stays ignored, so the advice would loop.
+  if (provenance.unpublishable) {
+    const { offending, why } = provenance.unpublishable;
+    return {
+      error: [
+        why === "missing"
+          ? "The version names a commit, and these policy files are not in it — ignored, or never committed:"
+          : "The version names a commit, and these policy files differ from it:",
+        ...offending.slice(0, 8).map((path) => `  ${path}`),
+        ...(offending.length > 8 ? [`  …and ${offending.length - 8} more`] : []),
+        why === "missing"
+          ? "They would be bundled into the artifact while the commit it names does not contain them."
+          : "They would be bundled as they are now, not as that commit holds them.",
+        why === "missing"
+          ? "Commit them — `git add -f` if they are ignored — or name the version yourself: --version <version>."
+          : "Commit them, or name the version yourself: --version <version>.",
+      ],
+    };
+  }
+  if (provenance.dirty) {
+    return {
+      error: [
+        `The version names commit ${versionFromCommit(provenance.sha)}, and this tree has uncommitted changes —`,
+        "so the bytes about to be published are not the bytes in that commit.",
+        "  git add -A && git commit -m \"...\"",
+        "Then publish again, or name the version yourself: --version <version>.",
+      ],
+    };
+  }
+  // Same refusal as the other two, from the other direction: a version that is
+  // not an abbreviated sha names no commit either. `inferCommit` only ever hands
+  // over forty lower-case hex, so nothing in the publish path reaches this —
+  // which is exactly why it is worth stating. Truncating a non-sha silently
+  // yields a `version` the manifest validator rejects much later, or an EMPTY
+  // one, and the publish then fails somewhere that says nothing about the sha.
+  const sha = provenance.sha.trim().toLowerCase();
+  if (!PACK_COMMIT_RE.test(sha)) {
+    return {
+      error: [
+        `The version names the commit it was built from, and ${JSON.stringify(provenance.sha.slice(0, 64))} is not one.`,
+        "Name the version yourself instead: --version <version>.",
+      ],
+    };
+  }
+  return { version: versionFromCommit(sha) };
 }
 
 /**
@@ -990,6 +1727,7 @@ function bundleEntry(
  */
 const PUBLISH_VALUE_FLAGS = new Set([
   "--repo", "--version", "--id", "--tag", "--notes", "--out", "--effect", "--entry", "--init",
+  "--commit",
 ]);
 function publishEntryArg(rest: string[]): string | undefined {
   const consumed = new Set<number>();
@@ -1001,6 +1739,19 @@ function publishEntryArg(rest: string[]): string | undefined {
 
 // ── publish ───────────────────────────────────────────────────────────────
 
+/**
+ * The three attachments a release needs before anybody can install it. One list,
+ * because `publish` uploads exactly these and `--releases` marks a release
+ * `incomplete` for missing any of them — two hand-written copies of the same
+ * three names would let the listing call a release installable that the
+ * installer then 404s on.
+ */
+const INSTALLABLE_PACK_ASSETS: readonly string[] = [
+  PACK_MANIFEST_ASSET,
+  PACK_ENTRY_ASSET,
+  PACK_CHECKSUMS_ASSET,
+];
+
 const GITHUB_API = process.env.FAILPROOFAI_GITHUB_API ?? "https://api.github.com";
 const GITHUB_UPLOADS = process.env.FAILPROOFAI_GITHUB_UPLOADS ?? "https://uploads.github.com";
 /** Where the git remote lives, so the push path can be tested against a real
@@ -1034,15 +1785,22 @@ function githubToken(): string | null {
   }
 }
 
+/**
+ * `token` is nullable because ONE caller has no credential to offer: listing a
+ * public repository's releases is a read anybody can do, and requiring
+ * `gh auth login` to look at what a pack has published would be a worse answer
+ * than the 60-per-hour anonymous rate limit. Every WRITE still passes a token —
+ * they are unreachable without one, since `publish` fails before it gets here.
+ */
 async function gh(
   url: string,
-  token: string,
+  token: string | null,
   init: { method?: string; body?: BodyInit; contentType?: string } = {},
 ): Promise<{ status: number; json: Record<string, unknown> | null; text: string }> {
   const response = await fetch(url, {
     method: init.method ?? "GET",
     headers: {
-      Authorization: `Bearer ${token}`,
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
       Accept: "application/vnd.github+json",
       "X-GitHub-Api-Version": "2022-11-28",
       "User-Agent": "failproofai",
@@ -1086,22 +1844,25 @@ function ghError(res: { status: number; json: Record<string, unknown> | null; te
  * and stop. That is what `pack build` now resolves to, so the old command keeps
  * working and means the same thing.
  *
- * Two failures the manual flow let through silently, both refused here:
+ * Two failures the manual flow let through silently, both refused BEFORE
+ * anything is created or uploaded:
  *   - a tag that does not describe the manifest version, which installs and then
  *     reports a version matching no URL;
- *   - a private repository, which publishes to nobody, because installs are
- *     anonymous HTTPS with no credential to offer.
+ *   - an existing private repository, which publishes to nobody, because
+ *     installs are anonymous HTTPS with no credential to offer. `--allow-private`
+ *     is for an author who genuinely wants that and will distribute the artifact
+ *     some other way; a repository publish CREATES is public by construction, so
+ *     the refusal only ever fires on reuse.
  */
 /**
  * The two things `publish` cannot work out on its own, asked instead of
  * demanded as flags.
  *
  * Everything else it already derives: the policy files by content, the version
- * by counting the repository's own releases, the id from the repository, the
- * credential from the environment. What is left is genuinely a question —
- * WHERE this should live, when the folder has no git remote naming somewhere —
- * and a confirmation, because publishing is public and a version number can
- * never be reused.
+ * from the commit the tree sits at, the id from the repository, the credential
+ * from the environment. What is left is genuinely a question — WHERE this
+ * should live, when the folder has no git remote naming somewhere — and a
+ * confirmation, because publishing is public and cannot be taken back.
  *
  * Only ever on a TTY. A pipe, a CI job or a test gets the old behaviour: flags
  * decide, and a missing `--repo` still means "build the assets and stop"
@@ -1112,12 +1873,16 @@ async function askWhereToPublish(
   io: { stdin: TTYIn; stdout: TTYOut },
 ): Promise<string | null> {
   const answer = await promptText({
-    // The suggestion goes in the HINT, not just in `defaultValue`: the hint is
-    // what renders as the placeholder, while `defaultValue` is only applied on
-    // an empty submit and is never shown. Passing it as the default alone left
-    // the one keystroke that finishes this prompt — return — invisible.
+    // The suggestion is NOT repeated in the hint. `promptText` renders a
+    // `defaultValue` as `↵ <value>` ahead of whatever hint it is given, so
+    // spelling it here too printed it twice — and the half that says which key
+    // takes it belongs to every prompt with a default, not to this one.
     message: "Where should this publish?",
-    hint: `${suggestion}  ·  created if it does not exist`,
+    // Kept short deliberately: `promptText` truncates to ONE physical row, and
+    // the whole line is the message plus `↵ <owner>/<repo>` plus this. At 80
+    // columns the longer spelling — "created if it does not exist" — pushed
+    // itself off the end, so the fact was written and never read.
+    hint: "created if missing",
     defaultValue: suggestion,
     validate: (v) => {
       const t = v.trim();
@@ -1188,14 +1953,27 @@ async function publish(rest: string[]): Promise<PackCliResult> {
     if (answered === null) return ok(["Nothing was published."]);
     repo = answered;
   }
-  // A tag on HEAD is somebody SAYING what this release is, so it wins over a
-  // counted one. Everything else is decided after the repository is known,
-  // because the count comes from what that repository has already published.
-  let version = flag("version") ?? (entry ? inferTaggedVersion(entry) : null) ?? undefined;
-  let versionCounted = false;
+  // A tag on HEAD is somebody SAYING what this release is, so it wins over the
+  // sha, which only reports one. Both are properties of the tree, so neither
+  // waits on the repository being known — see the block below the usage text.
+  // The set that will actually be BUNDLED — every discovered policy file, not
+  // just the entry, and everything those files IMPORT, which the bundler inlines
+  // and discovery never names. Both the tag path and the sha path are handed it,
+  // so neither can accept a version for bytes the commit does not hold.
+  const bundledSources = withLocalImports(
+    discovered.length > 0 ? discovered : entry ? [entry] : [],
+  );
+  let version =
+    flag("version") ?? (entry ? inferTaggedVersion(entry, bundledSources) : null) ?? undefined;
+  let versionFromSha = false;
   // The id and the repo are usually the same words, and requiring both is asking
   // the same question twice. Either one alone answers for the other.
   const dryRun = rest.includes("--dry-run") || !repo;
+  // The way past the private-repository refusal below, for somebody who really
+  // does want a pack nobody can `policies add` and will distribute the assets
+  // another way. It buys a publish, never a working install, so the success
+  // message still says so.
+  const allowPrivate = rest.includes("--allow-private");
   // A dry run publishes nothing, so the id only has to name the artifact it
   // writes — and refusing to build one because the folder has no git remote
   // yet blocked the exact thing a dry run is for: looking at the pack BEFORE
@@ -1222,15 +2000,53 @@ async function publish(rest: string[]): Promise<PackCliResult> {
       "Outside one, name them:",
       "       [--id <publisher/name>] [--tag <tag>] [--notes <text>]",
       "       [--out <dir>] [--effect enforce|observe] [--dry-run]",
+      "       [--allow-private]  (a private repo installs for nobody; this says so)",
       "",
       "With no --repo it writes the three release assets and stops.",
     ]);
   }
 
-  // Check an EXPLICIT tag against an explicit version before anything reaches
-  // the network. When the version is counted the tag simply follows it and can
-  // never disagree — but a tag the user typed can, and refusing it here is what
-  // stops a doomed publish from first creating a repository for itself.
+  // The version is a property of the TREE, not of the repository's history, so
+  // it is settled here — before the credential, before the repo, and identically
+  // for a dry run. Nothing is counted and nothing is asked of GitHub.
+  //
+  // Provenance is read ONCE, because it decides the version AND is recorded in
+  // the manifest beside it. Reading it twice is how the two come to disagree.
+  //
+  // The output directory is settled first only so the dirty read can skip it:
+  // it is where the LAST run's assets are sitting, and inside the checkout by
+  // default. See `skipOutDir`.
+  const outDirEarly = resolve(flag("out") ?? "dist-pack");
+  let provenance = entry ? inferCommit(entry, outDirEarly, bundledSources) : null;
+  const gitLines: string[] = [];
+  if (!version && entry && interactive) {
+    // Carry the git work rather than handing it back. TTY only: a commit made
+    // in CI exists on the runner and nowhere else, so the version would name
+    // provenance nobody can resolve, and `--version` is the answer there.
+    const settled = settleGitState(
+      entry,
+      provenance,
+      discovered.length > 0 ? discovered : [entry],
+      id,
+      outDirEarly,
+    );
+    if (settled && "error" in settled) return fail(settled.error);
+    if (settled) {
+      provenance = settled.provenance;
+      gitLines.push(...settled.lines);
+    }
+  }
+  if (!version) {
+    const resolved = versionForPublish(provenance);
+    if ("error" in resolved) return fail(resolved.error);
+    version = resolved.version;
+    versionFromSha = true;
+  }
+
+  // Check an EXPLICIT tag against the version before anything reaches the
+  // network. A tag the user typed can disagree with the version, and refusing
+  // it here is what stops a doomed publish from first creating a repository
+  // for itself.
   const explicitTag = flag("tag");
   if (explicitTag && version && !packTagMatchesVersion(explicitTag, version)) {
     return fail([
@@ -1241,12 +2057,9 @@ async function publish(rest: string[]): Promise<PackCliResult> {
     ]);
   }
 
-  // The version may still be unknown here: with nothing explicit and no tag, it
-  // is one past whatever the repository has already published, which cannot be
-  // known without asking it. So the credential and the repository come first —
-  // the reverse of the old order, where building first avoided authenticating
-  // for a pack that does not load. That trade is still paid: the build runs
-  // immediately after, before anything is created or uploaded.
+  // The version is already known, so the credential and the repository are
+  // needed only to publish. The build still runs immediately after, before
+  // anything is created or uploaded.
   let token: string | null = null;
   let created = false;
   let repoInfo: Awaited<ReturnType<typeof gh>> | null = null;
@@ -1263,25 +2076,34 @@ async function publish(rest: string[]): Promise<PackCliResult> {
     if ("error" in ensured) return fail(ensured.error);
     created = ensured.created;
     repoInfo = ensured.info;
-    if (!version) {
-      version = await nextVersion(owner, name, token);
-      versionCounted = true;
+    // A private repository is not a smaller audience, it is no audience:
+    // `fetchBytes` in pack-store.ts sends no Authorization header at all, by
+    // design, so every install 404s. This used to upload all three assets, exit
+    // 0, print `policies add <repo>` and merely append a warning underneath —
+    // reporting success for a release nobody could install and leaving assets
+    // behind that advertise that dead route. Refuse HERE, before the release
+    // exists and before anything is built, so there is nothing to clean up.
+    // A repository this command creates is made public, so this only ever
+    // fires on reuse of one that was already private.
+    if (repoInfo.json?.private === true && !allowPrivate) {
+      return fail([
+        `${repo} is PRIVATE, so nothing was published.`,
+        "Installing a pack fetches its release assets over anonymous HTTPS with no",
+        "credential to offer, so every install would 404 — including your own from",
+        "another machine. Publishing would only have attached three assets",
+        "advertising a route nobody can take.",
+        `Make it public and re-run:  gh repo edit ${repo} --visibility public`,
+        "Or, to keep it private and hand the pack over some other way, publish it",
+        "with --allow-private.",
+      ]);
     }
   }
-  // A dry run has nothing to count against, so it reports the first version. It
-  // says so rather than implying the number is settled.
-  if (!version) {
-    version = "1.0.0";
-    versionCounted = true;
-  }
-
   const tag = flag("tag") ?? version;
 
   // One artifact, however many files it was written across. `build` refuses an
   // entry with relative imports because only the entry is digest-pinned — so
   // the fix is to make it ONE file here, not to send the author away to set up
   // a bundler for a step this tool already performs for its own pack.
-  const outDirEarly = resolve(flag("out") ?? "dist-pack");
   let entryToBuild = entry;
   const needsBundle =
     discovered.length > 1 ||
@@ -1295,7 +2117,19 @@ async function publish(rest: string[]): Promise<PackCliResult> {
     entryToBuild = bundled.path;
   }
 
-  const built = await build([entryToBuild, "--id", id, "--version", version, ...outFlagFrom(rest), ...effectFlagFrom(rest)]);
+  const built = await build([
+    entryToBuild,
+    "--id", id,
+    "--version", version,
+    // NOT when the tree is dirty, even though `--version` let the publish
+    // through. `commit` claims these bytes came from that commit, and on a
+    // dirty tree they did not — recording it anyway put the exact false claim
+    // the dirty refusal exists to prevent through the door right next to it,
+    // reachable by taking the escape hatch that refusal recommends.
+    ...(provenance && !provenance.dirty ? ["--commit", provenance.sha] : []),
+    ...outFlagFrom(rest),
+    ...effectFlagFrom(rest),
+  ]);
   if (built.exitCode !== 0) return built;
 
   const outDir = outDirEarly;
@@ -1306,6 +2140,8 @@ async function publish(rest: string[]): Promise<PackCliResult> {
       : [];
   if (dryRun) {
     return ok([
+      ...gitLines,
+      ...(gitLines.length ? [""] : []),
       ...bundleNote,
       ...built.lines.slice(0, 4),
       "",
@@ -1315,10 +2151,9 @@ async function publish(rest: string[]): Promise<PackCliResult> {
             "Nothing was published: name a repository to release it on.",
             // Just the repository. It used to spell out the entry file and the
             // version too — naming ONE of the files it had that moment finished
-            // bundling, and pinning a version it works out by counting the
-            // repository's own releases. Both were wrong the moment they were
-            // printed, and both taught the reader that publishing needs flags
-            // it does not need.
+            // bundling, and pinning a version it works out for itself. Both
+            // were wrong the moment they were printed, and both taught the
+            // reader that publishing needs flags it does not need.
             "  failproofai publish --repo <owner>/<repo>",
           ]),
     ]);
@@ -1338,8 +2173,9 @@ async function publish(rest: string[]): Promise<PackCliResult> {
   }
 
 
-  // A private repo is not a smaller audience, it is no audience: `pack add`
-  // sends no Authorization header at all, by design, so every install 404s.
+  // Only ever true when --allow-private was passed — the refusal above returns
+  // otherwise — so this is the warning that goes with a publish the author
+  // asked for anyway, not a discovery made too late to act on.
   const isPrivate = repoInfo?.json?.private === true;
 
   // Reuse a release on this tag rather than failing on it. Re-publishing a
@@ -1356,7 +2192,15 @@ async function publish(rest: string[]): Promise<PackCliResult> {
       body: JSON.stringify({
         tag_name: tag,
         name: `${id} ${version}`,
-        body: flag("notes") ?? `${id}@${version}`,
+        // The body is what `policies show --releases` reads. Putting the counts
+        // and the commit HERE rather than in the manifest is what makes that
+        // command ONE request: the release list returns bodies inline, while
+        // the counts otherwise cost a manifest download per release and scale
+        // with history. It doubles as what a human sees on the releases page,
+        // which is the second reason to write it rather than a marker nobody
+        // reads. `--notes` still wins outright — an author who wrote release
+        // notes gets their release notes.
+        body: flag("notes") ?? releaseBody(id, version, built.meta),
         // A prerelease is invisible to `releases/latest`, which is how a tagless
         // `policies add owner/repo` resolves a version — so publishing one would
         // make the pack installable only by people who already knew its tag.
@@ -1370,7 +2214,7 @@ async function publish(rest: string[]): Promise<PackCliResult> {
     releaseId = created.json.id;
   }
 
-  const assets = [PACK_MANIFEST_ASSET, PACK_ENTRY_ASSET, PACK_CHECKSUMS_ASSET];
+  const assets = INSTALLABLE_PACK_ASSETS;
   const uploaded: string[] = [];
   const listed = await gh(`${GITHUB_API}/repos/${owner}/${name}/releases/${releaseId}/assets?per_page=100`, auth);
   const already = Array.isArray(listed.json)
@@ -1405,24 +2249,35 @@ async function publish(rest: string[]): Promise<PackCliResult> {
   }
 
   const lines = [
+    // What was done to the user's own directory, before what was done to
+    // GitHub. A side effect on somebody's working tree is never silent, even
+    // when it is the side effect they wanted.
+    ...gitLines,
+    ...(gitLines.length ? [""] : []),
     ...bundleNote,
     ...(created ? [`Created ${repo} (public).`] : []),
     `Published ${id}@${version} to ${repo} at tag ${tag}.` +
-      (versionCounted ? " Next publish will be one past it." : ""),
+      (versionFromSha ? " That names the commit it was built from." : ""),
     `  ${assets.length} assets attached`,
     "",
-    "Anyone can now install it:",
-    `  failproofai policies add ${repo}`,
-    `  failproofai policies show ${repo}      (look first, without running it)`,
+    // The install lines are the whole point of the success message, and on a
+    // private repository they are a lie — `policies add` 404s there. Print the
+    // warning INSTEAD of them, never underneath them: a reader who copies the
+    // first command they see must not be copying one that cannot work.
+    ...(isPrivate
+      ? [
+          `WARNING: ${repo} is PRIVATE, so nobody can install this — you asked for`,
+          "that with --allow-private. Installs are anonymous HTTPS with no credential",
+          "to offer, so every `failproofai policies add` will 404. Distribute the",
+          "three assets yourself, or make it public:",
+          `  gh repo edit ${repo} --visibility public`,
+        ]
+      : [
+          "Anyone can now install it:",
+          `  failproofai policies add ${repo}`,
+          `  failproofai policies show ${repo}      (look first, without running it)`,
+        ]),
   ];
-  if (isPrivate) {
-    lines.push(
-      "",
-      `WARNING: ${repo} is PRIVATE, so nobody can install this.`,
-      "Installs are anonymous HTTPS with no credential to offer — every one will 404.",
-      `Make it public:  gh repo edit ${repo} --visibility public`,
-    );
-  }
   return ok(lines);
 }
 
@@ -1575,6 +2430,10 @@ async function add(rest: string[]): Promise<PackCliResult> {
     const picked = await pickFromSource(resolvedSource!, io);
     if (picked === null) return ok(["Nothing installed."]);
     selection.only = picked;
+    // The picker REPLACES. What is ticked is what should be on, so a flag's
+    // additive reading must not leak into it — otherwise unticking something
+    // here could never turn it off.
+    selection.merge = false;
     // An empty pick is a real answer — install the pack, enable none of it —
     // but `{only: []}` is indistinguishable from "no selection" downstream, so
     // it is carried as an explicit empty list the resolver can see.
@@ -1585,7 +2444,18 @@ async function add(rest: string[]): Promise<PackCliResult> {
     const result = await addPack(resolvedSource!, selection);
     const lines = [
       ...(result.replaced?.length
-        ? [`Replaced ${result.replaced.join(", ")} — same policies under a new name; your selection was kept.`]
+        ? [
+            // What was OBSERVED, and then the inference — not the inference
+            // stated as fact. Identical artifact bytes are the only evidence
+            // there is, and they cannot tell a renamed pack from a second pack
+            // one repository builds from the same source. Absorbing is the
+            // right default (a publisher renaming a set must not reset everyone
+            // who narrowed it), but the record that goes away is one the user
+            // installed on purpose, so the line has to say what to do when the
+            // guess was wrong instead of asserting it was right.
+            `Replaced ${result.replaced.join(", ")} — same artifact, so it was taken as this pack renamed, and your selection was carried over.`,
+            `If ${result.replaced.length > 1 ? "those are separate packs" : "that is a separate pack"}, re-add ${result.replaced.join(", ")} to restore ${result.replaced.length > 1 ? "them" : "it"}.`,
+          ]
         : []),
       result.resolvedFromLatest
         ? `Installed ${result.id}@${result.version} from ${result.source} (newest release; pinned to ${result.tag})`
@@ -1599,6 +2469,10 @@ async function add(rest: string[]): Promise<PackCliResult> {
       defaults: "the pack's defaults",
       selected: "your selection",
       carried: "your existing selection",
+      // Named differently from `selected` on purpose: it is the one outcome
+      // where the set is LARGER than what was asked for, and a reader who does
+      // not see that said out loud will read the number as their whole answer.
+      added: "what you added, plus what was already on",
       all: "everything in the pack",
     }[result.selection];
     // `summarise([])` is the empty string, which would print a line ending in a
@@ -1634,9 +2508,29 @@ async function add(rest: string[]): Promise<PackCliResult> {
 function remove(rest: string[]): PackCliResult {
   const id = rest[0];
   if (!id) return fail(["Usage: failproofai policies remove <publisher/name>"]);
-  if (!removePack(id)) return fail([`No installed pack with id ${id}`]);
+  // Reported with the id the MACHINE holds, not the spelling that was typed:
+  // `remove FAILPROOFAI/POLICIES` succeeding and echoing that back teaches a
+  // name nothing else in the product uses.
+  let removedId: string | null;
+  try {
+    removedId = removePack(id);
+  } catch (err) {
+    // Two installed packs answer to one loosely-typed name. Refused rather
+    // than guessed at — the loose match exists so a remembered name works, and
+    // uninstalling something the user did not name is a worse outcome than
+    // asking them to be exact.
+    if (err instanceof AmbiguousPackId) {
+      return fail([
+        `${id} matches ${err.candidates.length} installed packs:`,
+        ...err.candidates.map((candidate) => `  ${candidate}`),
+        "Name one of them exactly.",
+      ]);
+    }
+    throw err;
+  }
+  if (!removedId) return fail([`No installed pack with id ${id}`]);
   return ok([
-    `Removed ${id}. Its policies stop enforcing now; re-add it any time with the same command.`,
+    `Removed ${removedId}. Its policies stop enforcing now; re-add it any time with the same command.`,
   ]);
 }
 
@@ -1649,6 +2543,204 @@ function remove(rest: string[]): PackCliResult {
  * downloading or importing the entry artifact, so looking at a stranger's pack
  * cannot run a stranger's code.
  */
+/**
+ * `failproofai policies show <owner>/<repo> --releases` — every release a pack
+ * has published, and which one is on this machine.
+ *
+ * ONE request. The obvious implementation downloads each release's manifest to
+ * count its policies, which costs a request per release and gets slower the
+ * longer a pack has existed; instead `publish` writes those counts into the
+ * release BODY, and `GET /releases` returns bodies inline. See `releaseBody`.
+ *
+ * A LISTING, and never an install path. Installs construct their URLs from
+ * owner/repo/tag and discover nothing, which is what leaves no index to poison
+ * — this reads the API because "what else is there?" is a question that has no
+ * answer without one, and the worst a wrong answer here can do is print a row.
+ * Nothing on this screen is trusted: the counts and the commit are
+ * publisher-controlled text, shown as claims, while what a machine actually
+ * installs still comes from the digest-pinned manifest.
+ */
+async function listReleases(source: string): Promise<PackCliResult> {
+  const opts = optsFor(process.stdout);
+  let spec;
+  try {
+    spec = parsePackSpec(source);
+  } catch (err) {
+    return fail([err instanceof Error ? err.message : String(err)]);
+  }
+
+  // Best-effort: a token raises the rate limit from 60/hour to 5000 and lets a
+  // private repo answer at all. Its absence is not an error.
+  const res = await gh(
+    `${GITHUB_API}/repos/${spec.owner}/${spec.repo}/releases?per_page=100`,
+    githubToken(),
+  );
+  if (res.status === 404) {
+    return fail([
+      `No repository at ${spec.owner}/${spec.repo}, or it is private and this machine has no credential for it.`,
+      "A pack has to be public to install anyway — installs are anonymous HTTPS with no credential to offer.",
+    ]);
+  }
+  if (res.status === 403 && /rate limit/i.test(res.text)) {
+    return fail([
+      "GitHub rate-limited this listing.",
+      "Sign in once with `gh auth login` (or set GITHUB_TOKEN) to raise the limit from 60 requests an hour to 5000.",
+    ]);
+  }
+  if (res.status >= 400 || !Array.isArray(res.json)) {
+    return fail([`Could not list releases for ${spec.owner}/${spec.repo}: ${ghError(res)}`]);
+  }
+
+  const raw = res.json as unknown as Array<{
+    tag_name?: unknown; body?: unknown; published_at?: unknown; created_at?: unknown;
+    prerelease?: unknown; draft?: unknown; assets?: unknown;
+  }>;
+  // Sorted HERE, by when each was PUBLISHED, rather than trusting the order the
+  // API returned.
+  //
+  // GitHub orders this endpoint by `created_at`, and `created_at` on a release
+  // is the date of the COMMIT its tag points at — not the moment the release
+  // was made. Two releases cut from one commit therefore tie, and the tie broke
+  // backwards: the pack repository's own listing put a release from 14:38 above
+  // the one from 15:27, and the install hint below offered the older of the
+  // two as the thing to install.
+  //
+  // That was survivable while versions sorted by themselves and is not now. A
+  // sha carries no order, so this list is the ONLY place the question "which of
+  // these is newest?" gets answered, and `publish --help` sends people here to
+  // ask it.
+  const when = (r: { published_at?: unknown; created_at?: unknown }): number => {
+    for (const value of [r.published_at, r.created_at]) {
+      if (typeof value !== "string") continue;
+      const parsed = Date.parse(value);
+      if (Number.isFinite(parsed)) return parsed;
+    }
+    // A release carrying no usable date sinks rather than floats: it cannot be
+    // shown as the newest thing on a claim it has not made.
+    return Number.NEGATIVE_INFINITY;
+  };
+  const releases = [...raw].sort((a, b) => when(b) - when(a));
+  if (releases.length === 0) {
+    return ok(
+      stack(
+        title(`${spec.owner}/${spec.repo}`, "no releases", opts),
+        emptyState(
+          {
+            what: "This repository has published no releases, so there is nothing to install.",
+            hint: "Its author publishes one with:",
+            cmd: "failproofai publish",
+          },
+          opts,
+        ),
+      ),
+    );
+  }
+
+  // Which of them is on THIS machine — the question somebody runs this to
+  // answer. Read by pack id rather than by source string: a pack installed as
+  // `github:o/r@v1` and one installed from the URL are the same pack, and
+  // comparing the spellings would say they are not.
+  const installedVersions = new Map<string, string>();
+  try {
+    for (const pack of readInstalledPacks().packs) installedVersions.set(pack.id.toLowerCase(), pack.version);
+  } catch {
+    /* an unreadable manifest costs the marker, not the listing */
+  }
+  const here = installedVersions.get(`${spec.owner}/${spec.repo}`.toLowerCase());
+
+  const rows: Array<string[] | { section: string }> = [];
+  // The newest INSTALLABLE tag for the hint below, picked in this same pass —
+  // GitHub returns releases newest-first. It used to be a second `find` over the
+  // raw list, which disagreed with the loop twice: a release whose `tag_name`
+  // was an empty string is skipped below but passed that `typeof === "string"`
+  // test, so the hint read `policies add owner/repo@`, and a release carrying
+  // none of the three assets was offered as the thing to install.
+  let newest: string | undefined;
+  for (const release of releases) {
+    const tag = typeof release.tag_name === "string" ? release.tag_name : "";
+    if (!tag) continue;
+    const facts = parseReleaseBody(typeof release.body === "string" ? release.body : "");
+    const when = typeof release.published_at === "string" ? release.published_at
+      : typeof release.created_at === "string" ? release.created_at
+        : "";
+    // By NAME, not by count. Counting said "three attachments" where the claim
+    // is "these three attachments", so any repository that ships three binaries
+    // per release — most of them — read as installable, and one that attaches
+    // nothing at all read as fine. Both then sent somebody to an install that
+    // 404s on an asset that was never there.
+    const attached = Array.isArray(release.assets)
+      ? new Set(
+        (release.assets as Array<{ name?: unknown }>)
+          .map((a) => (a && typeof a.name === "string" ? a.name : ""))
+          .filter(Boolean),
+      )
+      : new Set<string>();
+    const installable = INSTALLABLE_PACK_ASSETS.every((name) => attached.has(name));
+    const flags = [
+      release.draft === true ? "draft" : "",
+      release.prerelease === true ? "prerelease" : "",
+      installable ? "" : "incomplete",
+      here && packTagMatchesVersion(tag, here) ? "installed" : "",
+    ].filter(Boolean).join(" · ");
+    if (newest === undefined && installable && release.draft !== true) newest = tag;
+    rows.push([
+      tag,
+      when ? relativeAge(when) : "—",
+      facts.commit ? facts.commit.slice(0, 7) : "—",
+      facts.policies === undefined ? "—" : String(facts.policies),
+      facts.defaultOn === undefined ? "—" : String(facts.defaultOn),
+      flags,
+    ]);
+  }
+  return ok(
+    stack(
+      title(`${spec.owner}/${spec.repo}`, `${rows.length} release${rows.length === 1 ? "" : "s"}`, opts),
+      table(
+        { head: ["version", "published", "commit", "policies", "default", ""], rows },
+        opts,
+      ),
+      // `—` is load-bearing: it means "this release did not say", which is what
+      // a release published before this format did, and what anybody else's
+      // hand-made release does. Filling those in would cost a manifest download
+      // each, and a listing that silently costs a hundred downloads is worse
+      // than one with gaps in it.
+      note("— means the release did not record it.", opts),
+      nextStep(
+        `failproofai policies add ${spec.owner}/${spec.repo}@${newest ?? "<tag>"}`,
+        "Install a particular one with:",
+        opts,
+      ),
+    ),
+  );
+}
+
+/** `2 hours ago`, `6 days ago`. Coarse on purpose — the question is "how stale",
+ *  and a timestamp to the second answers a question nobody asked. */
+function relativeAge(iso: string): string {
+  const then = Date.parse(iso);
+  if (!Number.isFinite(then)) return "—";
+  const seconds = Math.max(0, Math.round((Date.now() - then) / 1000));
+  // Each pair is "divide by this, and the result is measured in THAT" — so the
+  // label belongs to the unit arrived at, never the one left behind. Written
+  // the other way round it was off by a whole unit across the entire range: a
+  // release from yesterday read `1 hour ago`, one from six months ago read
+  // `5 weeks ago`, and 90 seconds read `just now`. The column exists to answer
+  // "how stale is this pack", so an answer two units too fresh is worse than no
+  // column at all.
+  const units: Array<[number, string]> = [
+    [60, "minute"], [60, "hour"], [24, "day"], [7, "week"], [4.35, "month"], [12, "year"],
+  ];
+  let value = seconds;
+  let label = "second";
+  for (const [size, next] of units) {
+    if (value < size) break;
+    value = Math.floor(value / size);
+    label = next;
+  }
+  if (label === "second" && value < 60) return value < 10 ? "just now" : `${value} seconds ago`;
+  return `${value} ${label}${value === 1 ? "" : "s"} ago`;
+}
+
 async function listRemote(source: string): Promise<PackCliResult> {
   const opts = optsFor(process.stdout);
   let preview;
@@ -1836,8 +2928,19 @@ export async function runPackCommand(argv: string[]): Promise<PackCliResult> {
     case "list":
     case undefined: {
       // `pack list` is what is installed here; `pack list <source>` is what a
-      // pack out there contains.
+      // pack out there contains; `--releases` is what it has published over
+      // time. All three are "show me", which is why they are one word with a
+      // flag rather than a third subcommand nobody would find.
       const source = packAddSource(rest);
+      if (rest.includes("--releases")) {
+        if (!source) {
+          return fail([
+            "Usage: failproofai policies show <owner>/<repo> --releases",
+            "`--releases` reports what a pack out there has published; run `failproofai policies` for what is installed here.",
+          ]);
+        }
+        return listReleases(source);
+      }
       return source ? listRemote(source) : list();
     }
     default: