failproofai 1.0.2-beta.8 → 1.0.2

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 { 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_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,
@@ -178,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));
@@ -698,20 +716,30 @@ function inferRepo(entryPath: string): string | null {
  * 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 {
+function inferCommit(
+  entryPath: string,
+  outDir?: string,
+  sources?: string[],
+): Provenance | null {
   const cwd = resolve(entryPath, "..");
-  const git = (args: string[]): string | null => {
+  // 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,
-      }).trim();
+      });
     } 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
@@ -726,7 +754,150 @@ function inferCommit(entryPath: string, outDir?: string): { sha: string; dirty:
   // 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 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 };
 }
 
 /**
@@ -780,20 +951,24 @@ function skipOutDir(
  * 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 {
+function inferTaggedVersion(entryPath: string, sources?: string[]): string | null {
   const cwd = resolve(entryPath, "..");
-  const git = (args: string[]): string | null => {
+  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
@@ -802,6 +977,13 @@ function inferTaggedVersion(entryPath: string): string | 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;
 }
@@ -853,6 +1035,78 @@ function findEntry(dir: string): string[] {
   return found.sort();
 }
 
+/**
+ * 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.
+ */
+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.
  *
@@ -984,7 +1238,7 @@ function settleGitState(
         "Commit by hand, or name the version yourself: --version <version>.",
       ] };
     }
-    const made = inferCommit(entryPath, outDir);
+    const made = inferCommit(entryPath, outDir, packFiles);
     if (!made) return null;
     const files = `${staged} file${staged === 1 ? "" : "s"}`;
     return {
@@ -1025,25 +1279,45 @@ function settleGitState(
   // 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 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));
+  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.`,
@@ -1056,14 +1330,14 @@ function settleGitState(
 
   const problem = identity();
   if (problem) return { error: problem };
-  git(["add", "--", ...dirty]);
+  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>.",
     ] };
   }
-  const made = inferCommit(entryPath, outDir);
+  const made = inferCommit(entryPath, outDir, packFiles);
   if (!made || made.dirty) return null;
   return {
     provenance: made,
@@ -1122,7 +1396,7 @@ export function versionFromCommit(sha: string): string {
  * `--version` overrides all of it, and every refusal names it for that reason.
  */
 export function versionForPublish(
-  provenance: { sha: string; dirty: boolean } | null,
+  provenance: Provenance | null,
 ): { version: string } | { error: string[] } {
   if (!provenance) {
     return {
@@ -1133,6 +1407,28 @@ export function versionForPublish(
       ],
     };
   }
+  // 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: [
@@ -1548,11 +1844,15 @@ 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
@@ -1656,11 +1956,24 @@ async function publish(rest: string[]): Promise<PackCliResult> {
   // 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;
+  // 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
@@ -1687,6 +2000,7 @@ 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.",
     ]);
@@ -1703,7 +2017,7 @@ async function publish(rest: string[]): Promise<PackCliResult> {
   // 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;
+  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
@@ -1762,6 +2076,27 @@ async function publish(rest: string[]): Promise<PackCliResult> {
     if ("error" in ensured) return fail(ensured.error);
     created = ensured.created;
     repoInfo = ensured.info;
+    // 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.",
+      ]);
+    }
   }
   const tag = flag("tag") ?? version;
 
@@ -1838,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
@@ -1924,18 +2260,24 @@ async function publish(rest: string[]): Promise<PackCliResult> {
       (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);
 }
 
@@ -2102,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})`
@@ -2155,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.`,
   ]);
 }