mirror-mind 0.33.0 → 0.33.1

package/ts/src/runtime/releaseNotes.ts

@@ -1,20 +1,36 @@
 // Release-note reading for the runtime surface (CV22.DS7.TS3, plateau 2).
 // Port of the release-note half of `src/memory/cli/runtime.py`.
 //
-// Two sources, one document shape. The working tree answers "what does this
-// checkout contain"; a git ref answers "what does the channel contain that I
-// have not merged", which is the question `release-notes pending` exists for
-// and the reason this path shells out to `ls-tree`/`show` instead of reading
-// files. Ordering is by semantic version everywhere: `v0.10.0` follows
-// `v0.9.0`, which a lexical sort gets backwards.
+// Three sources, one document shape. A tree answers "what does this tree
+// contain": `docs/releases` under the root the caller names, read as files
+// with no git call -- the caller passes the running tree, which for a package
+// may sit inside a git work tree it does not own, such as Homebrew's prefix
+// (CR133). The other two answer `release-notes pending`, "what does my channel
+// hold that I do not", for the install that is running and never for the cwd
+// (CR134): a clone's git ref, read in the clone's own repository -- the only
+// path here that shells out to git -- and a package's channel version,
+// resolved by the registry and read from that version's tarball in memory.
+// Ordering is by semantic version everywhere: `v0.10.0` follows `v0.9.0`,
+// which a lexical sort gets backwards.
 //
-// `fetch` is the one command here that writes anything — remote-tracking refs,
-// never the worktree — and only when `release-notes pending` is allowed to
-// refresh. Everything else reads.
+// When no source answers, the bundle says so -- `unknown`, with a reason --
+// rather than `none`, which means a source answered and held nothing newer.
+//
+// `fetch` writes remote-tracking refs in the clone, never its worktree, and
+// `npm pack` one tarball into a private directory removed after the read.
+// Everything else reads.
 
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
+import {
+  channelDirection,
+  type NpmRunner,
+  type PackageInstall,
+  packTarball,
+} from "#runtime/strategies/package.ts";
 import { compareSemver } from "#util/semver.ts";
+import { MAX_INFLATED_BYTES, readTarGzEntries } from "#util/tarEntries.ts";
 import { GIT_NETWORK_TIMEOUT_MS, runGit } from "./git.ts";
 
 export interface ReleaseNote {
@@ -29,6 +45,8 @@ export interface ReleaseNotesBundle {
   notes: ReleaseNote[];
   current_version: string | null;
   source: string | null;
+  /** Why no source answered; null when one did, with notes or with none (CR134). */
+  unknown_reason: string | null;
 }
 
 const NOTE_NAME = /^v\d+\.\d+\.\d+\.md$/;
@@ -99,15 +117,13 @@ export function releaseNoteFromText(path: string, text: string): ReleaseNote {
   };
 }
 
-function repositoryFor(start: string): string {
-  const startPath = resolve(start);
-  const top = runGit(["rev-parse", "--show-toplevel"], startPath);
-  return top.code === 0 && top.stdout ? top.stdout : startPath;
-}
-
-/** Notes in the working tree, ordered by semantic version. */
-export function readReleaseNotes(start: string): ReleaseNote[] {
-  const dir = join(repositoryFor(start), "docs", "releases");
+/**
+ * Notes under `<root>/docs/releases`, ordered by semantic version. The root is
+ * read as given: asking git for its repository would climb out of a package
+ * installed under a prefix that is itself a work tree (CR133).
+ */
+export function readReleaseNotes(root: string): ReleaseNote[] {
+  const dir = join(resolve(root), "docs", "releases");
   if (!existsSync(dir)) return [];
   return readdirSync(dir)
     .filter((name) => NOTE_NAME.test(name))
@@ -118,58 +134,104 @@ export function readReleaseNotes(start: string): ReleaseNote[] {
     });
 }
 
-export function readReleaseNote(version: string, start: string): ReleaseNote | null {
-  const notes = readReleaseNotes(start);
+export function readReleaseNote(version: string, root: string): ReleaseNote | null {
+  const notes = readReleaseNotes(root);
   if (version === "latest")
     return notes.length > 0 ? (notes[notes.length - 1] as ReleaseNote) : null;
   const wanted = version.startsWith("v") ? version : `v${version}`;
   return notes.find((note) => note.version === wanted) ?? null;
 }
 
-function refNoteNames(ref: string, repository: string): string[] {
-  const listed = runGit(["ls-tree", "-r", "--name-only", ref, "docs/releases"], repository);
-  if (listed.code !== 0 || !listed.stdout) return [];
-  return listed.stdout
+/**
+ * A ref is user-supplied (`--ref`), and git takes an argument that begins with
+ * `-` as an option, `--upload-pack=<command>` among them (CR134). Such a ref is
+ * refused before git runs, and every verb below also puts `--end-of-options`
+ * before its operands, which covers the half of a ref after its first slash.
+ */
+function refusedRef(ref: string): string | null {
+  if (ref === "") return "no ref was named";
+  if (ref.startsWith("-")) return `ref ${JSON.stringify(ref)} begins with '-' and is refused`;
+  return null;
+}
+
+function firstLine(text: string): string {
+  return (
+    text
+      .split("\n")
+      .find((line) => line.trim() !== "")
+      ?.trim() ?? ""
+  );
+}
+
+type RefNames = { ok: true; names: string[] } | { ok: false; detail: string };
+
+/** The note paths at `ref`. A ref that does not resolve is said, not read as empty. */
+function refNoteNames(ref: string, repository: string): RefNames {
+  const refused = refusedRef(ref);
+  if (refused !== null) return { ok: false, detail: refused };
+  const listed = runGit(
+    ["ls-tree", "-r", "--name-only", "--end-of-options", ref, "docs/releases"],
+    repository,
+  );
+  if (listed.code !== 0) return { ok: false, detail: `ref ${ref} does not resolve` };
+  const names = listed.stdout
     .split("\n")
     .map((line) => line.trim())
     .filter((line) => REF_NOTE_PATH.test(line));
+  return { ok: true, names };
+}
+
+function showAtRef(ref: string, path: string, repository: string): string | null {
+  const shown = runGit(["show", "--end-of-options", `${ref}:${path}`], repository);
+  return shown.code === 0 && shown.stdout ? shown.stdout : null;
 }
 
-/** Notes as the ref has them — what a channel contains, merged or not. */
-export function readReleaseNotesFromRef(ref: string, start: string): ReleaseNote[] {
-  const repository = repositoryFor(start);
-  const names = refNoteNames(ref, repository).sort((a, b) =>
+type RefNotes = { ok: true; notes: ReleaseNote[] } | { ok: false; detail: string };
+
+function readRefNotes(ref: string, repository: string): RefNotes {
+  const listed = refNoteNames(ref, repository);
+  if (!listed.ok) return listed;
+  const names = listed.names.sort((a, b) =>
     compareSemver(basename(a).replace(/\.md$/, ""), basename(b).replace(/\.md$/, "")),
   );
   const notes: ReleaseNote[] = [];
   for (const selected of names) {
-    const shown = runGit(["show", `${ref}:${selected}`], repository);
-    if (shown.code !== 0 || !shown.stdout) continue;
-    notes.push(releaseNoteFromText(selected, shown.stdout));
+    const text = showAtRef(ref, selected, repository);
+    if (text !== null) notes.push(releaseNoteFromText(selected, text));
   }
-  return notes;
+  return { ok: true, notes };
+}
+
+/**
+ * Notes as the ref has them — what a channel contains, merged or not — in the
+ * repository given, never one discovered from a cwd (CR134). A ref that does
+ * not resolve yields none here; `buildPendingReleaseNotes` says why.
+ */
+export function readReleaseNotesFromRef(ref: string, repository: string): ReleaseNote[] {
+  const read = readRefNotes(ref, resolve(repository));
+  return read.ok ? read.notes : [];
 }
 
 export function readReleaseNoteFromRef(
   ref: string,
   version: string,
-  start: string,
+  repository: string,
 ): ReleaseNote | null {
-  const repository = repositoryFor(start);
+  const root = resolve(repository);
   let selected: string;
   if (version === "latest") {
-    const names = refNoteNames(ref, repository);
-    if (names.length === 0) return null;
-    selected = names.sort((a, b) =>
+    const listed = refNoteNames(ref, root);
+    if (!listed.ok || listed.names.length === 0) return null;
+    selected = listed.names.sort((a, b) =>
       compareSemver(basename(b).replace(/\.md$/, ""), basename(a).replace(/\.md$/, "")),
     )[0] as string;
   } else {
+    if (refusedRef(ref) !== null) return null;
     const wanted = version.startsWith("v") ? version : `v${version}`;
     selected = `docs/releases/${wanted}.md`;
   }
-  const shown = runGit(["show", `${ref}:${selected}`], repository);
-  if (shown.code !== 0 || !shown.stdout) return null;
-  return releaseNoteFromText(selected, shown.stdout);
+  const text = showAtRef(ref, selected, root);
+  return text === null ? null : releaseNoteFromText(selected, text);
 }
 
 /** Port of `_normalize_version`: drop a leading `v`, keep the rest. */
@@ -178,30 +240,141 @@ export function normalizeVersion(version: string): string {
   return trimmed.startsWith("v") ? trimmed.slice(1) : trimmed;
 }
 
-/** Refresh the channel ref before reading it. The only write in this module. */
-export function fetchReleaseNotesRef(ref: string, repository: string): void {
+export type RefFetch =
+  | { kind: "skipped" }
+  | { kind: "fetched" }
+  | { kind: "failed"; detail: string };
+
+/**
+ * Refresh the channel ref before reading it: `git fetch <remote> <branch>` for
+ * a ref shaped `<remote>/<branch>`, in the clone's own repository. A ref with
+ * no remote part, such as `HEAD`, has nothing to fetch, and a refused ref never
+ * reaches git.
+ */
+export function fetchReleaseNotesRef(ref: string, repository: string): RefFetch {
+  if (refusedRef(ref) !== null) return { kind: "skipped" };
   const slash = ref.indexOf("/");
-  if (slash <= 0 || slash === ref.length - 1) return;
+  if (slash <= 0 || slash === ref.length - 1) return { kind: "skipped" };
   const remote = ref.slice(0, slash);
   const branch = ref.slice(slash + 1);
-  runGit(["fetch", remote, branch], repository, GIT_NETWORK_TIMEOUT_MS);
+  const fetched = runGit(
+    ["fetch", "--end-of-options", remote, branch],
+    repository,
+    GIT_NETWORK_TIMEOUT_MS,
+  );
+  if (fetched.code === 0) return { kind: "fetched" };
+  return {
+    kind: "failed",
+    detail: firstLine(fetched.stderr) || `git fetch exited ${fetched.code}`,
+  };
+}
+
+/** A bundle no source answered: `Pending releases: unknown`, and why. */
+export function unknownReleaseNotes(
+  currentVersion: string,
+  source: string | null,
+  reason: string,
+): ReleaseNotesBundle {
+  return {
+    notes: [],
+    current_version: `v${normalizeVersion(currentVersion)}`,
+    source,
+    unknown_reason: reason,
+  };
 }
 
 export interface PendingOptions {
   currentVersion: string;
   ref: string;
-  start: string;
+  /** The install's own checkout, used as given: never discovered from a cwd (CR134). */
+  repository: string;
   fetch: boolean;
 }
 
+/**
+ * A clone's pending notes: the releases at `ref` newer than the installed
+ * version. A fetch that fails is `unknown`, not a quiet read of a stale ref;
+ * `--no-fetch` is how to ask for the ref as last fetched (CR134, decision 2).
+ */
 export function buildPendingReleaseNotes(options: PendingOptions): ReleaseNotesBundle {
-  const repository = repositoryFor(options.start);
+  const repository = resolve(options.repository);
   const current = normalizeVersion(options.currentVersion);
-  if (options.fetch) fetchReleaseNotesRef(options.ref, repository);
-  const notes = readReleaseNotesFromRef(options.ref, repository).filter((note) =>
-    isNewer(note.version, current),
-  );
-  return { notes, current_version: `v${current}`, source: options.ref };
+  const unknown = (reason: string) => unknownReleaseNotes(current, options.ref, reason);
+  const refused = refusedRef(options.ref);
+  if (refused !== null) return unknown(refused);
+  if (options.fetch) {
+    const fetched = fetchReleaseNotesRef(options.ref, repository);
+    if (fetched.kind === "failed") return unknown(`fetch failed: ${fetched.detail}`);
+  }
+  const read = readRefNotes(options.ref, repository);
+  if (!read.ok) return unknown(read.detail);
+  return {
+    notes: read.notes.filter((note) => isNewer(note.version, current)),
+    current_version: `v${current}`,
+    source: options.ref,
+    unknown_reason: null,
+  };
+}
+
+export interface RegistryPendingOptions {
+  currentVersion: string;
+  install: PackageInstall;
+  channel: string;
+  npm: NpmRunner;
+}
+
+const TARBALL_NOTE = /^package\/docs\/releases\/v\d+\.\d+\.\d+\.md$/;
+
+/**
+ * A package's pending notes (CR134). The registry resolves the channel's
+ * dist-tag to a version, as `runtime update` does at plan. When that version is
+ * ahead, its exact tarball is fetched into a private directory and the notes
+ * are read in memory, within the reader's bound; when it is current or behind,
+ * nothing is downloaded. Every npm call runs in the install's root (CR135).
+ */
+export function buildPendingReleaseNotesFromRegistry(
+  options: RegistryPendingOptions,
+): ReleaseNotesBundle {
+  const { install, channel, npm } = options;
+  const current = normalizeVersion(options.currentVersion);
+  const tag = `npm ${install.name}@${channel}`;
+  const direction = channelDirection({ ...install, version: current }, channel, npm);
+  if (direction.kind === "unresolved") return unknownReleaseNotes(current, tag, direction.detail);
+  const target = direction.version;
+  const source = `${tag} (${target})`;
+  if (direction.kind !== "ahead") {
+    return { notes: [], current_version: `v${current}`, source, unknown_reason: null };
+  }
+
+  const destination = mkdtempSync(join(tmpdir(), "mirror-release-notes-"));
+  try {
+    const packed = packTarball(install.name, target, install.root, destination, npm);
+    if (!packed.ok) return unknownReleaseNotes(current, source, packed.detail);
+    // The compressed file is read whole before it is inflated, so it is bounded too.
+    if (statSync(packed.path).size > MAX_INFLATED_BYTES) {
+      return unknownReleaseNotes(
+        current,
+        source,
+        `the tarball is larger than ${MAX_INFLATED_BYTES} bytes`,
+      );
+    }
+    const read = readTarGzEntries(readFileSync(packed.path), (name) => TARBALL_NOTE.test(name));
+    if (!read.ok) return unknownReleaseNotes(current, source, read.detail);
+    const notes = [...read.entries]
+      .sort(([a], [b]) =>
+        compareSemver(basename(a).replace(/\.md$/, ""), basename(b).replace(/\.md$/, "")),
+      )
+      .map(([name, bytes]) =>
+        releaseNoteFromText(
+          `${install.name}@${target}:${name.slice("package/".length)}`,
+          bytes.toString("utf8"),
+        ),
+      )
+      .filter((note) => isNewer(note.version, current));
+    return { notes, current_version: `v${current}`, source, unknown_reason: null };
+  } finally {
+    rmSync(destination, { recursive: true, force: true });
+  }
 }
 
 export function renderReleaseNote(note: ReleaseNote | null): string {
@@ -226,6 +399,11 @@ export function renderReleaseNotesBundle(bundle: ReleaseNotesBundle): string {
   const lines = ["Mirror runtime release notes", ""];
   if (bundle.current_version) lines.push(`Current version: ${bundle.current_version}`);
   if (bundle.source) lines.push(`Source: ${bundle.source}`);
+  if (bundle.unknown_reason !== null) {
+    lines.push("Pending releases: unknown");
+    lines.push(`Reason: ${bundle.unknown_reason}`);
+    return `${lines.join("\n")}\n`;
+  }
   if (bundle.notes.length === 0) {
     lines.push("Pending releases: none");
     return `${lines.join("\n")}\n`;

package/ts/src/runtime/strategies/clone.ts

@@ -9,15 +9,18 @@
 // decisions can be driven in tests without a remote, and so this module can be
 // read as "what we ask git for" rather than "how we spawn it".
 
-import { runGit } from "#runtime/git.ts";
+import { GIT_NETWORK_TIMEOUT_MS, runGit } from "#runtime/git.ts";
 import type { ApplyStrategy } from "#runtime/updatePipeline.ts";
 
+/** Without a timeout, a command gets `runGit`'s local budget. */
 export type GitRunner = (
   args: readonly string[],
   cwd: string,
+  timeoutMs?: number,
 ) => { code: number; stdout: string; stderr: string };
 
-export const defaultGitRunner: GitRunner = (args, cwd) => runGit([...args], cwd);
+export const defaultGitRunner: GitRunner = (args, cwd, timeoutMs) =>
+  runGit([...args], cwd, timeoutMs);
 
 /** `origin/main` -> `["origin", "main"]`; anything else is refused. */
 export function splitUpstream(upstream: string): [string, string] | null {
@@ -44,7 +47,11 @@ export function fetchUpstream(
   const split = splitUpstream(upstream);
   if (split === null) return { ok: false, detail: "unexpected upstream name" };
   const [remote, branch] = split;
-  const result = git(["fetch", remote, branch], repository);
+  // The one command here that crosses the network, so it gets the network
+  // budget (CR132). On the 2-second local budget a fetch still in flight was
+  // killed and reported failed. The oracle's `_git_fetch` had this since
+  // 521177f8, and the port lost it. Both update lanes run this fetch.
+  const result = git(["fetch", remote, branch], repository, GIT_NETWORK_TIMEOUT_MS);
   return result.code === 0
     ? { ok: true, detail: `${remote} ${branch}` }
     : { ok: false, detail: result.stderr.trim() || "fetch failed" };

package/ts/src/runtime/strategies/package.ts

@@ -11,29 +11,53 @@
 // the pipeline's decisions are testable without a registry.
 
 import { execFileSync } from "node:child_process";
+import { basename, join } from "node:path";
 import { type ApplyStrategy, KNOWN_CHANNELS } from "#runtime/updatePipeline.ts";
 import { compareSemver, isPlainSemver } from "#util/semver.ts";
 
-/** `cwd` matters to the one npm command that reads a tree, `publish`; the rest ignore it. */
+/**
+ * Where and how long one npm command runs.
+ *
+ * `cwd` is a trust decision, not a convenience (CR135). npm reads the project
+ * config of the directory it runs in -- the `.npmrc` beside the nearest
+ * `package.json` -- so a command started in the person's project takes its
+ * `registry=` and `prefix=` from whatever that project ships. Every call the
+ * product makes names its directory: the install's own root for the package's
+ * commands, the release's repository for `publish`.
+ */
+export interface NpmCall {
+  cwd?: string;
+  /** Kill npm after this long. Absent, npm runs until it answers. */
+  timeoutMs?: number;
+}
+
 export type NpmRunner = (
   args: readonly string[],
-  cwd?: string,
+  call?: NpmCall,
 ) => {
   code: number;
   stdout: string;
   stderr: string;
 };
 
-export const defaultNpmRunner: NpmRunner = (args, cwd) => {
+export const defaultNpmRunner: NpmRunner = (args, call = {}) => {
   try {
     const stdout = execFileSync("npm", [...args], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
-      ...(cwd === undefined ? {} : { cwd }),
+      ...(call.cwd === undefined ? {} : { cwd: call.cwd }),
+      ...(call.timeoutMs === undefined ? {} : { timeout: call.timeoutMs }),
     });
     return { code: 0, stdout, stderr: "" };
   } catch (error) {
-    const shaped = error as { status?: number; stdout?: string; stderr?: string };
+    const shaped = error as { status?: number; stdout?: string; stderr?: string; code?: string };
+    if (shaped.code === "ETIMEDOUT") {
+      return {
+        code: -1,
+        stdout: shaped.stdout ?? "",
+        stderr: `npm ${args[0] ?? ""} timed out after ${call.timeoutMs} ms`,
+      };
+    }
     return {
       code: shaped.status ?? -1,
       stdout: shaped.stdout ?? "",
@@ -42,9 +66,14 @@ export const defaultNpmRunner: NpmRunner = (args, cwd) => {
   }
 };
 
-/** `npm root -g`, or null when npm is not usable. Resolved once per run. */
-export function npmRootGlobal(npm: NpmRunner = defaultNpmRunner): string | null {
-  const result = npm(["root", "-g"]);
+/**
+ * `npm root -g`, or null when npm is not usable. Resolved once per run.
+ *
+ * It runs before the install is known, so its directory is the caller's: the
+ * tree the front door runs from, which for a package is the install's root.
+ */
+export function npmRootGlobal(cwd: string, npm: NpmRunner = defaultNpmRunner): string | null {
+  const result = npm(["root", "-g"], { cwd });
   const value = result.stdout.trim();
   return result.code === 0 && value ? value : null;
 }
@@ -54,9 +83,25 @@ export function npmRootGlobal(npm: NpmRunner = defaultNpmRunner): string | null
 
 export type DistTags = { ok: true; tags: Record<string, string> } | { ok: false; detail: string };
 
+/**
+ * How to read the dist-tags. `cwd` is the install's root. The welcome card
+ * bounds the read and drops npm's retries, which cost over a minute when the
+ * registry cannot be reached (CR135); `runtime update` asks for neither.
+ */
+export interface DistTagRead {
+  cwd: string;
+  timeoutMs?: number;
+  fetchRetries?: number;
+}
+
 /** `npm view <name> dist-tags --json`, read once per run. */
-export function readDistTags(name: string, npm: NpmRunner = defaultNpmRunner): DistTags {
-  const result = npm(["view", name, "dist-tags", "--json"]);
+export function readDistTags(name: string, npm: NpmRunner, read: DistTagRead): DistTags {
+  const args = ["view", name, "dist-tags", "--json"];
+  if (read.fetchRetries !== undefined) args.push(`--fetch-retries=${read.fetchRetries}`);
+  const result = npm(
+    args,
+    read.timeoutMs === undefined ? { cwd: read.cwd } : { cwd: read.cwd, timeoutMs: read.timeoutMs },
+  );
   if (result.code !== 0)
     return { ok: false, detail: firstLine(result.stderr) || "npm view failed" };
   let parsed: unknown;
@@ -117,12 +162,24 @@ export type ChannelDirection =
   | { kind: "behind"; version: string; detail: string; carriedBy: string | null }
   | { kind: "unresolved"; detail: string };
 
+/** What the package's npm commands need to know about the install. */
+export interface PackageInstall {
+  name: string;
+  version: string;
+  /** Where the package lives; its npm commands run here. */
+  root: string;
+}
+
+/** The bound and retries of one dist-tag read; where it runs is the install's. */
+export type DistTagLimits = Omit<DistTagRead, "cwd">;
+
 export function channelDirection(
-  install: { name: string; version: string },
+  install: PackageInstall,
   channel: string,
   npm: NpmRunner = defaultNpmRunner,
+  limits: DistTagLimits = {},
 ): ChannelDirection {
-  const read = readDistTags(install.name, npm);
+  const read = readDistTags(install.name, npm, { cwd: install.root, ...limits });
   if (!read.ok) return { kind: "unresolved", detail: read.detail };
   const resolved = resolveFrom(read.tags, install.name, channel);
   if (!resolved.ok) return { kind: "unresolved", detail: resolved.detail };
@@ -165,12 +222,13 @@ export interface PackageUpdateAvailability {
 }
 
 export function checkPackageUpdateAvailability(
-  install: { name: string; version: string },
+  install: PackageInstall,
   channel: { value: string; note: string | null },
   npm: NpmRunner = defaultNpmRunner,
+  limits: DistTagLimits = {},
 ): PackageUpdateAvailability {
   const base = { name: install.name, installed: install.version, channel, carriedBy: null };
-  const direction = channelDirection(install, channel.value, npm);
+  const direction = channelDirection(install, channel.value, npm, limits);
   switch (direction.kind) {
     case "current":
       return { ...base, resolved: direction.version, status: "up_to_date", note: null };
@@ -220,18 +278,53 @@ export function renderPackageUpdateAvailability(report: PackageUpdateAvailabilit
   return `${lines.join("\n")}\n`;
 }
 
-/** Install one exact version globally. Never a bare tag. */
+/** Install one exact version globally, from the install's own root. Never a bare tag. */
 export function installGlobal(
   name: string,
   version: string,
+  cwd: string,
   npm: NpmRunner = defaultNpmRunner,
 ): { ok: boolean; detail: string } {
-  const result = npm(["install", "-g", `${name}@${version}`]);
+  const result = npm(["install", "-g", `${name}@${version}`], { cwd });
   return result.code === 0
     ? { ok: true, detail: `${name}@${version}` }
     : { ok: false, detail: firstLine(result.stderr) || "npm install failed" };
 }
 
+/**
+ * `npm pack <name>@<version>` into `destination`: the exact tarball `runtime
+ * update` would install, fetched -- never unpacked here -- so `release-notes
+ * pending` can read what that version brings (CR134). It runs in the install's
+ * own root, as every npm call does (CR135). `--ignore-scripts`: a registry
+ * tarball runs no scripts when packed, and at a trust boundary that is said
+ * rather than assumed.
+ */
+export function packTarball(
+  name: string,
+  version: string,
+  cwd: string,
+  destination: string,
+  npm: NpmRunner = defaultNpmRunner,
+): { ok: true; path: string } | { ok: false; detail: string } {
+  const result = npm(
+    ["pack", `${name}@${version}`, "--pack-destination", destination, "--ignore-scripts", "--json"],
+    { cwd },
+  );
+  if (result.code !== 0)
+    return { ok: false, detail: firstLine(result.stderr) || "npm pack failed" };
+  let filename: unknown;
+  try {
+    filename = (JSON.parse(result.stdout) as Array<{ filename?: unknown }>)[0]?.filename;
+  } catch {
+    return { ok: false, detail: "npm pack returned unreadable JSON" };
+  }
+  // A bare file name, or nothing: the path is ours to build.
+  if (typeof filename !== "string" || filename === "" || basename(filename) !== filename) {
+    return { ok: false, detail: "npm pack named no tarball" };
+  }
+  return { ok: true, path: join(destination, filename) };
+}
+
 /** The pasteable route back, with the captured version in it. */
 export function packageRecoveryCommand(name: string, previousVersion: string | null): string {
   return previousVersion === null
@@ -249,7 +342,7 @@ export function packageRecoveryCommand(name: string, previousVersion: string | n
  * asked once, at plan.
  */
 export function packageStrategy(
-  install: { name: string; version: string },
+  install: PackageInstall,
   channel: string,
   npm: NpmRunner,
 ): ApplyStrategy {
@@ -268,11 +361,7 @@ export function packageStrategy(
     }),
 
     plan: (previousRef) => {
-      const direction = channelDirection(
-        { name: install.name, version: previousRef },
-        channel,
-        npm,
-      );
+      const direction = channelDirection({ ...install, version: previousRef }, channel, npm);
       switch (direction.kind) {
         case "unresolved":
           return {
@@ -308,7 +397,7 @@ export function packageStrategy(
     },
 
     apply: (_previousRef, target) => {
-      const applied = installGlobal(install.name, target, npm);
+      const applied = installGlobal(install.name, target, install.root, npm);
       return applied.ok
         ? { ok: true, newRef: target, detail: applied.detail, changes: [] }
         : {