failproofai 1.0.2-beta.7 → 1.0.2-beta.8

package/src/hooks/pack-cli.ts

@@ -9,9 +9,9 @@ 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 { 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 {
@@ -22,6 +22,7 @@ import {
   checkPackArtifact,
   fetchPackPreview,
   packTagMatchesVersion,
+  parsePackSpec,
   removePack,
   setPackPolicyEnabled,
   slugifyCategory,
@@ -48,9 +49,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 {
@@ -195,6 +214,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 +229,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 +274,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 +284,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 +364,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 +401,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 +592,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())
@@ -599,12 +678,107 @@ function inferRepo(entryPath: string): string | null {
   }
 }
 
+/**
+ * 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.
+ *
+ * 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 inferCommit(entryPath: string, outDir?: string): { sha: string; dirty: boolean } | null {
+  const cwd = resolve(entryPath, "..");
+  const git = (args: string[]): string | null => {
+    try {
+      return execFileSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 5_000,
+      }).trim();
+    } catch {
+      return null;
+    }
+  };
+  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)]);
+  return { sha, dirty: status !== "" };
+}
+
+/**
+ * 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 counted
- * number cannot. Absent a tag there is nothing here to infer — the version is
- * counted from what the repository has already published instead.
+ * 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): string | null {
   const cwd = resolve(entryPath, "..");
@@ -625,9 +799,10 @@ function inferTaggedVersion(entryPath: string): string | 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.
+  if (git(["status", "--porcelain", "--", entryPath]) !== "") return null;
   return tag;
 }
 
@@ -679,45 +854,311 @@ 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.
+ * 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.
  */
-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;
+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);
+    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.
+  const status = raw([
+    "status",
+    "--porcelain",
+    "--untracked-files=all",
+    ...skipOutDir(git, entryPath, outDir),
+  ]);
+  if (root === null || status === null) return null;
+  const dirty = status
+    .split("\n")
+    .map((line) => line.slice(3).trim())
+    // A rename reads `old -> new`; the new path is the one that exists.
+    .map((path) => (path.includes(" -> ") ? path.split(" -> ")[1] : path))
+    .map((path) => path.replace(/^"|"$/g, ""))
+    .filter(Boolean)
+    .map((path) => resolve(root, path));
+  if (dirty.length === 0) return null;
+
+  const mine = new Set(packFiles.map((f) => resolve(f)));
+  const foreign = dirty.filter((path) => !mine.has(path));
+  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", "--", ...dirty]);
+  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);
+  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: { sha: string; dirty: boolean } | 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>.",
+      ],
+    };
+  }
+  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 +1431,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 +1443,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 +1489,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",
@@ -1097,11 +1559,10 @@ function ghError(res: { status: number; json: Record<string, unknown> | null; te
  * 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 +1573,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,11 +1653,11 @@ 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.
+  // 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.
   let version = flag("version") ?? (entry ? inferTaggedVersion(entry) : null) ?? undefined;
-  let versionCounted = false;
+  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;
@@ -1227,10 +1692,47 @@ async function publish(rest: string[]): Promise<PackCliResult> {
     ]);
   }
 
-  // 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) : 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 +1743,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 +1762,13 @@ 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 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 +1782,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 +1805,8 @@ async function publish(rest: string[]): Promise<PackCliResult> {
       : [];
   if (dryRun) {
     return ok([
+      ...gitLines,
+      ...(gitLines.length ? [""] : []),
       ...bundleNote,
       ...built.lines.slice(0, 4),
       "",
@@ -1315,10 +1816,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>",
           ]),
     ]);
@@ -1356,7 +1856,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 +1878,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,10 +1913,15 @@ 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:",
@@ -1575,6 +2088,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.
@@ -1599,6 +2116,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
@@ -1649,6 +2170,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 +2555,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: