@dbx-tools/projen 0.9.167 → 0.9.174

package/README.md

@@ -626,9 +626,14 @@ and profile are not recorded in the annotated tag.
 
 After bump and configured validation, release writes
 `docs/releases/vX.Y.Z.md` with `dbx genie exec -C "$PWD" --sandbox read-only
---ephemeral -o`. The standard prompt cannot run validation commands. Failures
-fall back to a short git-log summary. Notes are committed with the version bump,
-not stored in the annotated tag, and are omitted for an existing committed bump.
+--ephemeral -o`. It first finds the newest tag whose GitHub Actions release
+workflow succeeded, then asks Genie for cumulative notes from that deployed
+baseline through HEAD. Newer failed-release tags and their notes remain source
+material instead of shortening the delta to a retry-only workflow fix. The
+standard prompt cannot run validation commands. Failures fall back to a short
+git-log summary from the same successful baseline. Notes are committed with the
+version bump, not stored in the annotated tag, and are omitted for an existing
+committed bump.
 
 Automatic installation retains Projen's manifest-based install trigger; the
 other install modes force installation or reuse the current dependency tree.
@@ -664,6 +669,24 @@ whole-tree operation driven by the root `.projenrc.ts`, so a member-level run
 re-synths the entire workspace from the member's directory. Run `bun run sync`
 from the root instead.
 
+## Commit a registry-neutral lockfile
+
+The root `bun.lock` is committed, and generated CI installs run
+`bun install --frozen-lockfile`. A private npm mirror would otherwise appear in
+every resolved tarball URL, so the generated `bun-lockfile` task runs after each
+root install and as the root `postinstall` script, which also covers `bun add`,
+`bun remove`, and `bun update`. It detects the active registry from the same
+environment, `.npmrc`, `bunfig.toml`, and pnpm configuration a package manager
+reads. When that registry is not public npm, it rewrites every tarball URL under
+it and leaves all other URLs unchanged. Bun 1.4.2 has no native setting that
+omits registry URLs from `bun.lock`.
+
+The default replacement is an empty tarball field, which Bun resolves through
+the installing machine's registry; integrity hashes still pin the content.
+Run `bun run bun-lockfile -- --check` to confirm a lockfile is clean without
+writing it. Options can also come from `PROJEN_BUN_LOCKFILE_*` environment
+variables or `.env`.
+
 ## Manage workspace versions
 
 `VERSION` is the language-neutral version seam. Real package manifests remain

package/index.ts

@@ -3,10 +3,11 @@
 // Hand edits are overwritten on the next watch; this file is read-only.
 
 export const PACKAGE_IDENTIFIER = "@dbx-tools/projen";
-export const PACKAGE_VERSION = "0.9.167";
+export const PACKAGE_VERSION = "0.9.174";
 export * as appkitWorkspace from "./src/appkit-workspace.ts";
 export * as barrels from "./src/barrels.ts";
 export * as bunApp from "./src/bun-app.ts";
+export * as bunLockfile from "./src/bun-lockfile.ts";
 export * as bunWorkflow from "./src/bun-workflow.ts";
 export * as clean from "./src/clean.ts";
 export * as codegen from "./src/codegen.ts";
@@ -48,6 +49,8 @@ export type { AppKitWorkspaceMode, AppKitBundleOptions, AppKitWorkspaceOptions }
 export { isGeneratedBarrel, folderBarrelFile, generateBarrels } from "./src/barrels.ts";
 export { BUN_DEV_OVERRIDE, BUN_BUILD_OVERRIDE, BUN_APP_OVERRIDES, RootBunfigFile, BunfigFile, BunDevServerFile, BunBuildFile } from "./src/bun-app.ts";
 export type { BunBuildFileOptions } from "./src/bun-app.ts";
+export { BUN_LOCKFILE, BunLockfileReplacementSchema, BunLockfileOptionsSchema, bunLockfileRegistries, normalizeBunLockfile, normalizeBunLockfileAt } from "./src/bun-lockfile.ts";
+export type { BunLockfileOptions, BunLockfileOptionsInput, NormalizedBunLockfile, BunLockfileNormalization } from "./src/bun-lockfile.ts";
 export { BUN_VERSION, MINIMUM_BUN_VERSION, BUN_VERSION_CHECK_SCRIPT } from "./src/bun-workflow.ts";
 export { listGeneratedFiles, listNodeModulesDirs, removePaths } from "./src/clean.ts";
 export { codegenModulePaths, generateCodegen } from "./src/codegen.ts";
@@ -68,7 +71,7 @@ export { resolveRepoRoot, repoRoot, DEFAULT_PACKAGE_ROOTS, projectName, toPosix,
 export type { RecordedPackage } from "./src/packages.ts";
 export { PnpmWorkspaceState } from "./src/pnpm-workspace.ts";
 export type { Catalog, AllowBuilds, DBXToolsPNPMWorkspaceOptions } from "./src/pnpm-workspace.ts";
-export { PackageIdentifier, identifier, applyCompilerOptions, applyIncludes, applyExports, addExports, addOptionalPeer, projectRepositoryUrl, projectReleaseBranch, addPackageFiles, srcFolderExports, LICENSE, DBXToolsNodeProject, ROOT_INSTALL_ONLY_MIXIN, DBXToolsTypeScriptProject, taskCommand } from "./src/project-js.ts";
+export { PackageIdentifier, identifier, applyCompilerOptions, applyIncludes, applyExports, addExports, addOptionalPeer, projectRepositoryUrl, projectReleaseBranch, addPackageFiles, srcFolderExports, LICENSE, BUN_LOCKFILE_TASK, DBXToolsNodeProject, ROOT_INSTALL_ONLY_MIXIN, DBXToolsTypeScriptProject, taskCommand } from "./src/project-js.ts";
 export type { DBXToolsJavaScriptProject, DBXToolsReleaseMode, DiscoveredTypeScriptPackageOptions, DBXToolsJavaScriptProjectOptions, DBXToolsTypeScriptProjectOptions } from "./src/project-js.ts";
 export { isProject, isDBXToolsProject, isDBXToolsJavaScriptProject, hasName, hasIdentifierPackageName, hasIdentifierName, hasIdentifierScope, hasTag, hasPath } from "./src/project-predicate.ts";
 export { pythonPackagePath, pythonModuleName, DBXToolsPythonProject, DBXToolsPythonWorkspace } from "./src/project-py.ts";

package/package.json

@@ -30,11 +30,11 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@dbx-tools/auth": "^0.9.167",
-    "@dbx-tools/cli-args": "^0.9.167",
-    "@dbx-tools/core": "^0.9.167",
-    "@dbx-tools/path": "^0.9.167",
-    "@dbx-tools/shared-core": "^0.9.167",
+    "@dbx-tools/auth": "^0.9.174",
+    "@dbx-tools/cli-args": "^0.9.174",
+    "@dbx-tools/core": "^0.9.174",
+    "@dbx-tools/path": "^0.9.174",
+    "@dbx-tools/shared-core": "^0.9.174",
     "commander": "^15.0.0",
     "concurrently": "^10.0.3",
     "constructs": "^10.6.0",
@@ -56,7 +56,7 @@
   },
   "main": "index.ts",
   "license": "Apache-2.0",
-  "version": "0.9.167",
+  "version": "0.9.174",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/bun-lockfile.ts

@@ -0,0 +1,161 @@
+/**
+ * Registry-neutral Bun text lockfiles.
+ *
+ * Bun records each package's resolved tarball URL in `bun.lock`. When the
+ * installing machine's npm registry is a private mirror, every URL names that
+ * mirror, so a committed lockfile would leak it and fail on machines that cannot
+ * reach it. Normalization detects the active registry the same way a package
+ * manager does and, when it is not public npm, rewrites every tarball URL under
+ * it in bulk. All other URLs are left as they are.
+ *
+ * Bun accepts both replacement forms under `--frozen-lockfile`: an empty tarball
+ * field resolves through whichever registry the installing machine configures,
+ * and a public npm URL pins npmjs explicitly. Integrity hashes are unchanged, so
+ * frozen installs still verify the exact tarball content.
+ *
+ * Bun has no native setting for this as of 1.4.2: `[install.lockfile]` only
+ * supports `save` and `print`, and Bun's own `BunLockFile` type marks the npm
+ * registry field "TODO: remove if default". Replace this rewrite with that
+ * native behavior once Bun ships it.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { npmRegistry } from "@dbx-tools/core";
+import { z } from "zod";
+
+/** Bun's text lockfile at a workspace root. */
+export const BUN_LOCKFILE = "bun.lock";
+
+/** Public npm registry used by the `npmjs` replacement. */
+const PUBLIC_NPM_REGISTRY = "https://registry.npmjs.org";
+
+/** Registry tarball entry: `"key": ["name@version", "<tarball>", ...`. */
+const TARBALL_ENTRY =
+  /^(\s+"[^"\n]+": \[")((?:@[^/"\n]+\/)?[^@"\n]+)@([^"\n]+)(", )"(https?:\/\/[^"\n]*)"/gm;
+
+/** How private registry tarball URLs are rewritten. */
+export const BunLockfileReplacementSchema = z
+  .enum(["empty", "npmjs"])
+  .describe(
+    "Replacement for private registry tarball URLs: empty resolves through the installing machine's registry; npmjs pins public npm",
+  );
+
+/** Options that control `bun.lock` normalization. */
+export const BunLockfileOptionsSchema = z
+  .object({
+    mode: z
+      .enum(["auto", "off"])
+      .default("auto")
+      .describe(
+        "auto rewrites tarball URLs under the detected npm registry when it is not public npm; off leaves the lockfile unchanged",
+      ),
+    replacement: BunLockfileReplacementSchema.default("empty"),
+    registries: z
+      .array(z.string().trim().url())
+      .default([])
+      .describe("Additional registry URLs whose tarball URLs are rewritten"),
+    check: z
+      .boolean()
+      .default(false)
+      .describe("Fail instead of writing when the lockfile is not normalized"),
+  })
+  .describe("Keep bun.lock free of private npm registry URLs");
+
+/** Parsed {@link BunLockfileOptionsSchema}. */
+export type BunLockfileOptions = z.output<typeof BunLockfileOptionsSchema>;
+
+/** Accepted input for {@link BunLockfileOptionsSchema}. */
+export type BunLockfileOptionsInput = z.input<typeof BunLockfileOptionsSchema>;
+
+/** Result of normalizing one lockfile body. */
+export interface NormalizedBunLockfile {
+  /** Lockfile text with private registry tarball URLs rewritten. */
+  readonly content: string;
+  /** Number of tarball URLs rewritten. */
+  readonly rewritten: number;
+  /** Registry prefixes that were rewritten. */
+  readonly registries: readonly string[];
+}
+
+/** URL origin plus path prefix of a registry, without a trailing slash. */
+function registryPrefix(url: string): string | undefined {
+  try {
+    const parsed = new URL(url);
+    return `${parsed.origin}${parsed.pathname.replace(/\/+$/, "")}`;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Registry URLs to rewrite for `cwd`.
+ *
+ * `auto` adds the active npm registry only when it is not public npm, so a
+ * machine on npmjs leaves the lockfile untouched.
+ */
+export function bunLockfileRegistries(
+  cwd: string,
+  options: Pick<BunLockfileOptions, "mode" | "registries">,
+): string[] {
+  if (options.mode === "off") return [];
+  const detected = npmRegistry(cwd, { overrideOnly: true })?.href;
+  return [...(detected ? [detected] : []), ...options.registries];
+}
+
+/** Public npm tarball URL for one package version. */
+function npmjsTarball(name: string, version: string): string {
+  const base = name.slice(name.lastIndexOf("/") + 1);
+  return `${PUBLIC_NPM_REGISTRY}/${name}/-/${base}-${version}.tgz`;
+}
+
+/** Rewrite tarball URLs under any of `registries`; leave every other URL as is. */
+export function normalizeBunLockfile(
+  content: string,
+  registries: readonly string[],
+  replacement: z.output<typeof BunLockfileReplacementSchema> = "empty",
+): NormalizedBunLockfile {
+  const prefixes = [...new Set(registries.flatMap((registry) => registryPrefix(registry) ?? []))];
+  if (prefixes.length === 0) return { content, rewritten: 0, registries: prefixes };
+  let rewritten = 0;
+  const normalized = content.replace(
+    TARBALL_ENTRY,
+    (entry, head: string, name: string, version: string, separator: string, url: string) => {
+      if (!prefixes.some((prefix) => url.startsWith(`${prefix}/`))) return entry;
+      rewritten += 1;
+      const tarball = replacement === "npmjs" ? npmjsTarball(name, version) : "";
+      return `${head}${name}@${version}${separator}"${tarball}"`;
+    },
+  );
+  return { content: normalized, rewritten, registries: prefixes };
+}
+
+/** Outcome of {@link normalizeBunLockfileAt}. */
+export interface BunLockfileNormalization extends NormalizedBunLockfile {
+  /** Absolute lockfile path. */
+  readonly path: string;
+  /** Whether the lockfile exists. */
+  readonly exists: boolean;
+  /** Whether the file content differs from its normalized form. */
+  readonly changed: boolean;
+}
+
+/** Normalize `bun.lock` in `root`, writing it unless `check` is set. */
+export function normalizeBunLockfileAt(
+  root: string,
+  input: BunLockfileOptionsInput = {},
+): BunLockfileNormalization {
+  const options = BunLockfileOptionsSchema.parse(input);
+  const path = join(root, BUN_LOCKFILE);
+  if (!existsSync(path)) {
+    return { path, exists: false, changed: false, content: "", rewritten: 0, registries: [] };
+  }
+  const original = readFileSync(path, "utf8");
+  const result = normalizeBunLockfile(
+    original,
+    bunLockfileRegistries(root, options),
+    options.replacement,
+  );
+  const changed = result.content !== original;
+  if (changed && !options.check) writeFileSync(path, result.content);
+  return { ...result, path, exists: true, changed };
+}

package/src/project-js.ts

@@ -32,6 +32,7 @@ import {
 import { folderBarrelFile, generateBarrels } from "./barrels.ts";
 
 import { BUN_APP_OVERRIDES, RootBunfigFile } from "./bun-app.ts";
+import { BUN_LOCKFILE } from "./bun-lockfile.ts";
 import { BUN_VERSION, BUN_VERSION_CHECK_SCRIPT, MINIMUM_BUN_VERSION } from "./bun-workflow.ts";
 import { codegenModulePaths, generateCodegen } from "./codegen.ts";
 import { DBXToolsConfig, type DBXToolsConfigOptions } from "./dbx-tools-config.ts";
@@ -527,6 +528,33 @@ const DEV_DEPS_ROOT: string[] = [
   "@types/node@^24.6.0",
 ];
 
+/** Root task that clears registry tarball URLs from `bun.lock`. */
+export const BUN_LOCKFILE_TASK = "bun-lockfile";
+
+/**
+ * Commit `bun.lock` without leaking the installing machine's registry.
+ *
+ * Bun writes each resolved tarball URL into the lockfile. The generated
+ * `bun-lockfile` task detects the active npm registry (resolved like a package
+ * manager does, never hard-coded) and, when it is not public npm, rewrites every
+ * tarball URL under it; all other URLs stay as they are. It runs after every
+ * root install and as the root `postinstall` script, so `bun add`, `bun remove`,
+ * and `bun update` normalize too. CI installs with `--frozen-lockfile`.
+ */
+function configureRootLockfile(project: DBXToolsJavaScriptProject): void {
+  const normalize = taskCommand(`${BUN_LOCKFILE_TASK}.ts`);
+  const task = project.addTask(BUN_LOCKFILE_TASK, {
+    description: "Rewrite private npm registry tarball URLs in bun.lock",
+    execArgs: normalize,
+    receiveArgs: true,
+  });
+  project.package.installTask.reset("bun install");
+  project.package.installTask.spawn(task);
+  project.package.installCiTask.reset(project.package.installCommand);
+  project.package.setScript("postinstall", normalize.join(" "));
+  project.annotateGenerated(`/${BUN_LOCKFILE}`);
+}
+
 function configureRootBunRuntime(project: DBXToolsJavaScriptProject): void {
   new TextFile(project, BUN_VERSION_CHECK_SCRIPT, {
     lines: dedent(// ============================================================================
@@ -1330,9 +1358,7 @@ function initProject(
   if (selfDep) project.addDevDeps(selfDep);
   project.addDevDeps(...DEV_DEPS_ROOT);
   configureRootPackage(project);
-  // Workspaces generated by this engine intentionally do not track local-registry
-  // lockfiles, so the CI-named install task must resolve from manifests as well.
-  project.package.installCiTask.reset("bun install");
+  configureRootLockfile(project);
   configureRootBunRuntime(project);
   const roots =
     options.packageRoots ??
@@ -1367,6 +1393,9 @@ function initProject(
   project.gitignore.addPatterns(
     ...[...ignore.ignorePatterns({ test: false, dot: false, lock: true })],
   );
+  // The root Bun text lockfile is committed in registry-neutral form; see
+  // configureRootLockfile. Other lockfiles stay ignored.
+  project.gitignore.include(`/${BUN_LOCKFILE}`);
   // The generic compiled-output pattern `**/lib/**` must not hide authored
   // modules beneath a package's `src/lib/`.
   project.gitignore.include("**/src/lib/**");

package/src/release.ts

@@ -276,7 +276,7 @@ function releaseBuildJob(
           fetchDepth: 0,
         },
       }),
-      ...project.renderWorkflowSetup({ mutable: true }),
+      ...project.renderWorkflowSetup({ mutable: false }),
       {
         name: "Verify release context",
         id: "release",

package/tasks/bun-lockfile.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env -S bun
+/**
+ * Keep `bun.lock` free of private npm registry URLs.
+ *
+ * Detects the active npm registry and, when it is not public npm, rewrites
+ * every tarball URL under it. Options also read `PROJEN_BUN_LOCKFILE_*`
+ * environment variables and `.env`.
+ */
+import { relative } from "node:path";
+import { log } from "@dbx-tools/shared-core";
+import { runTaskMain, taskCommand, taskOptions, taskRoot } from "./cli.ts";
+import { TaskRootOptionSchema } from "./options.ts";
+import { BunLockfileOptionsSchema, normalizeBunLockfileAt } from "../src/bun-lockfile.ts";
+
+const logger = log.logger("projen:bun-lockfile");
+
+const TaskSchema = BunLockfileOptionsSchema.extend({ root: TaskRootOptionSchema });
+
+export async function main(args: string[] = process.argv.slice(2)): Promise<void> {
+  const { root, ...options } = await taskOptions(
+    taskCommand(import.meta.url, "Keep bun.lock free of private npm registry URLs", TaskSchema),
+    TaskSchema,
+    args,
+  );
+  const result = normalizeBunLockfileAt(taskRoot(root), options);
+  if (!result.exists || !result.changed) return;
+  const file = relative(process.cwd(), result.path) || result.path;
+  if (options.check) {
+    throw new Error(
+      `${file} contains ${result.rewritten} private registry tarball URLs; run \`bun run bun-lockfile\``,
+    );
+  }
+  logger.info(`rewrote ${result.rewritten} private registry tarball URLs`, { file });
+}
+
+await runTaskMain(import.meta, main);

package/tasks/publish.ts

@@ -50,6 +50,7 @@ import { delimiter, dirname, isAbsolute, join, relative, resolve } from "node:pa
 import { log, mapConcurrent, sequence } from "@dbx-tools/shared-core";
 import { z } from "zod";
 import { runTaskMain, taskCommand, taskOptions, taskPositionals, taskRoot } from "./cli.ts";
+import { publishNpmArchives } from "./publish-npm.ts";
 import {
   TaskConcurrencyOptionSchema,
   TaskDirectoriesOptionSchema,
@@ -59,7 +60,7 @@ import {
 } from "./options.ts";
 import { runTaskCommand } from "../src/_task-command.ts";
 import { applyPublishConfig, packNpmPackage } from "../src/npm-packaging.ts";
-import { publishNpmArchive, readNpmArchiveIdentity } from "../src/npm-release.ts";
+import { readNpmArchiveIdentity } from "../src/npm-release.ts";
 import { recordedPackages } from "../src/packages.ts";
 
 const logger = log.logger("projen:publish");
@@ -212,58 +213,52 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<void
     }
   }
 
-  logger.info(
-    `${output ? "packing" : dryRun ? "dry-run packing" : "publishing"} ${publishable.length} packages with concurrency ${concurrency}`,
-  );
-  if (output) {
-    rmSync(output, { recursive: true, force: true });
-    mkdirSync(output, { recursive: true });
-  }
-  await mapConcurrent(
-    publishable,
-    async ({ dir, name, version: packageVersion, access }) => {
-      const packed = mkdtempSync(join(tmpdir(), "projen-npm-release-"));
-      try {
-        const archive = packNpmPackage(dir, packed, path, applyPublishConfig);
-        const local = readNpmArchiveIdentity(archive);
-        if (local.name !== name || local.version !== packageVersion) {
-          throw new Error(
-            `Packed npm identity ${local.name}@${local.version} does not match ${name}@${packageVersion}`,
-          );
-        }
-        if (local.access !== access) {
-          throw new Error(
-            `Packed npm access ${String(local.access)} does not match ${String(access)} for ${name}`,
-          );
-        }
-        if (output) {
-          const destination = join(output, archive.split(/[\\/]/).at(-1)!);
+  logger.info(`packing ${publishable.length} packages with concurrency ${concurrency}`);
+  const archiveDirectory = output ?? mkdtempSync(join(tmpdir(), "projen-npm-publish-"));
+  if (output) rmSync(archiveDirectory, { recursive: true, force: true });
+  mkdirSync(archiveDirectory, { recursive: true });
+  try {
+    await mapConcurrent(
+      publishable,
+      async ({ dir, name, version: packageVersion, access }) => {
+        const packed = mkdtempSync(join(tmpdir(), "projen-npm-release-"));
+        try {
+          const archive = packNpmPackage(dir, packed, path, applyPublishConfig);
+          const local = readNpmArchiveIdentity(archive);
+          if (local.name !== name || local.version !== packageVersion) {
+            throw new Error(
+              `Packed npm identity ${local.name}@${local.version} does not match ${name}@${packageVersion}`,
+            );
+          }
+          if (local.access !== access) {
+            throw new Error(
+              `Packed npm access ${String(local.access)} does not match ${String(access)} for ${name}`,
+            );
+          }
+          const destination = join(archiveDirectory, archive.split(/[\\/]/).at(-1)!);
           if (existsSync(destination)) {
             throw new Error(`Duplicate npm archive name: ${destination}`);
           }
           copyFileSync(archive, destination);
           logger.info(`packed ${name} @ ${packageVersion}`);
-          return;
+        } finally {
+          rmSync(packed, { recursive: true, force: true });
         }
-        const outcome = await publishNpmArchive({
-          archive,
-          identity: local,
-          cwd: dir,
-          dryRun,
-          env: { ...process.env, PATH: path },
-          registry,
-        });
-        if (outcome === "skipped") {
-          logger.info(`skip published ${name} @ ${packageVersion}`);
-          return;
-        }
-        logger.info(`${dryRun ? "dry-run published" : "published"} ${name} @ ${packageVersion}`);
-      } finally {
-        rmSync(packed, { recursive: true, force: true });
-      }
-    },
-    { concurrency, errorMode: "settle" },
-  );
+      },
+      { concurrency, errorMode: "settle" },
+    );
+    if (!output) {
+      await publishNpmArchives({
+        concurrency,
+        directory: archiveDirectory,
+        dryRun,
+        registry,
+        version,
+      });
+    }
+  } finally {
+    if (!output) rmSync(archiveDirectory, { recursive: true, force: true });
+  }
   logger.success(
     `${output || dryRun ? "packed" : "published"} ${publishable.length} packages${output ? ` to ${output}` : ""}`,
   );

package/tasks/release-notes.ts

@@ -16,7 +16,17 @@ import { captureTaskCommand, tryTaskCommand } from "../src/_task-command.ts";
 const logger = log.logger("projen:release-notes");
 
 const GENIE_PROMPT =
-  "Compare HEAD and the working tree against the latest v* tag. Produce concise user-facing release notes. Ignore generated-file churn and test-only changes. Include breaking changes, fixes, and validation results. The configured release validation phase has already completed, so do not run tests or other validation commands and do not invent validation counts. Do not modify files.";
+  "Produce concise user-facing release notes. Ignore generated-file churn and test-only changes. Include breaking changes, fixes, and validation results. The configured release validation phase has already completed, so do not run tests or other validation commands and do not invent validation counts. Do not modify files.";
+
+/** Inputs that define the release-note comparison and optional caller guidance. */
+export interface ReleaseNotesPromptOptions {
+  /** Release tag whose GitHub Actions release workflow most recently succeeded. */
+  readonly successfulTag?: string;
+  /** Extra agent instructions appended after the standard release-note requirements. */
+  readonly instructions?: string;
+  /** Release tag prefix used when no successful GitHub baseline exists. */
+  readonly prefix: string;
+}
 
 /** Inputs for one notes write. */
 export interface WriteReleaseNotesOptions {
@@ -28,15 +38,21 @@ export interface WriteReleaseNotesOptions {
   readonly instructions?: string;
   readonly prefix: string;
   readonly root: string;
+  /** Release tag whose GitHub Actions release workflow most recently succeeded. */
+  readonly successfulTag?: string;
   readonly version: string;
   /** Override Genie invocation; return false to force the git-log fallback. */
   readonly runGenie?: (args: readonly string[]) => boolean;
 }
 
-/** Compose the stable release-note prompt with optional caller guidance. */
-export function releaseNotesPrompt(instructions?: string): string {
-  const additional = instructions?.trim();
-  return additional ? `${GENIE_PROMPT}\n\nAdditional instructions:\n${additional}` : GENIE_PROMPT;
+/** Compose the stable release-note prompt with the deployed baseline and caller guidance. */
+export function releaseNotesPrompt(options: ReleaseNotesPromptOptions): string {
+  const baseline = options.successfulTag
+    ? `The latest GitHub release workflow that completed successfully is ${options.successfulTag}. Compare ${options.successfulTag}..HEAD plus the working tree. Treat any newer ${options.prefix}* tags and their release-note files as failed release attempts: combine their user-facing changes into this release, verify them against the cumulative code delta, and do not shorten the comparison to those failed tags. Do not reduce the notes to retry-only deployment or workflow fixes such as \"changed workflow X\" when unreleased product changes are part of the same cumulative delta.`
+    : `No successful GitHub release workflow baseline was found. Do not assume the latest ${options.prefix}* tag deployed successfully. Inspect the available release-note files, tags, git history, HEAD, and the working tree, then produce cumulative notes for the user-facing changes not known to have shipped successfully. Do not reduce the notes to retry-only deployment or workflow fixes when unreleased product changes are present.`;
+  const prompt = `${baseline}\n\n${GENIE_PROMPT}`;
+  const additional = options.instructions?.trim();
+  return additional ? `${prompt}\n\nAdditional instructions:\n${additional}` : prompt;
 }
 
 /** Path of the notes file for one workspace version. */
@@ -92,7 +108,11 @@ export function writeReleaseNotes(options: WriteReleaseNotesOptions): string {
     "--ephemeral",
     "-o",
     relative,
-    releaseNotesPrompt(options.instructions),
+    releaseNotesPrompt({
+      instructions: options.instructions,
+      prefix,
+      successfulTag: options.successfulTag,
+    }),
   ] as const;
   const ran =
     options.runGenie?.([...genieArgs]) ??
@@ -101,20 +121,14 @@ export function writeReleaseNotes(options: WriteReleaseNotesOptions): string {
     logger.info("wrote Genie release notes", { path: relative });
     return destination;
   }
-  const previousTag = captureTaskCommand(root, "git", [
-    "describe",
-    "--tags",
-    "--abbrev=0",
-    `--match=${prefix}*`,
-  ]);
-  const logArgs = previousTag
-    ? ["log", "--no-merges", "--pretty=format:%s", `${previousTag}..HEAD`]
+  const logArgs = options.successfulTag
+    ? ["log", "--no-merges", "--pretty=format:%s", `${options.successfulTag}..HEAD`]
     : ["log", "--no-merges", "--pretty=format:%s", "-15"];
   const commits = captureTaskCommand(root, "git", logArgs)
     .split("\n")
     .map((line) => line.trim())
     .filter(Boolean);
-  writeFileSync(destination, fallbackReleaseNotes(version, commits, previousTag || undefined));
+  writeFileSync(destination, fallbackReleaseNotes(version, commits, options.successfulTag));
   logger.warn("Genie release notes unavailable; wrote git-log summary", { path: relative });
   return destination;
 }

package/tasks/release.ts

@@ -81,6 +81,18 @@ export type ReleaseGithubActionsWatcher = (
   options: WatchReleaseGithubActionsOptions,
 ) => Promise<void>;
 
+/** Inputs required to find the newest successfully deployed release tag. */
+export interface ResolveSuccessfulReleaseTagOptions {
+  readonly account: ProjectGhAccount;
+  readonly prefix: string;
+  readonly root: string;
+}
+
+/** Successful release lookup boundary replaceable by release tests. */
+export type SuccessfulReleaseTagResolver = (
+  options: ResolveSuccessfulReleaseTagOptions,
+) => string | undefined;
+
 function githubRepository(account: ProjectGhAccount): string {
   return account.host === "github.com"
     ? account.remote.repository
@@ -146,6 +158,61 @@ function reportGithubProgress(
   }
 }
 
+/** Find the newest release tag whose GitHub Actions release workflow succeeded. */
+export function resolveSuccessfulReleaseTag(
+  options: ResolveSuccessfulReleaseTagOptions,
+): string | undefined {
+  const { account, prefix, root } = options;
+  const output = captureTaskCommand(
+    root,
+    "gh",
+    [
+      "run",
+      "list",
+      "--repo",
+      githubRepository(account),
+      "--workflow",
+      RELEASE_WORKFLOW_FILE,
+      "--event",
+      "push",
+      "--status",
+      "success",
+      "--limit",
+      "100",
+      "--json",
+      "databaseId,headBranch,headSha,status,url",
+    ],
+    { env: account.env, stderr: "inherit" },
+  );
+  const parsed = z.array(GithubReleaseRunSchema).safeParse(parse(output, []));
+  if (!parsed.success) {
+    logger.warn("GitHub returned invalid successful release workflow metadata", {
+      error: parsed.error,
+      repository: account.remote.repository,
+    });
+    return undefined;
+  }
+  for (const run of parsed.data) {
+    if (!run.headBranch.startsWith(prefix)) continue;
+    const tagHead = gitHead(root, `refs/tags/${run.headBranch}^{}`);
+    if (tagHead !== run.headSha) continue;
+    if (!taskCommandSucceeds(root, "git", ["merge-base", "--is-ancestor", tagHead, "HEAD"])) {
+      continue;
+    }
+    logger.info("using successful GitHub release as the release-note baseline", {
+      repository: account.remote.repository,
+      runId: run.databaseId,
+      tag: run.headBranch,
+      url: run.url,
+    });
+    return run.headBranch;
+  }
+  logger.info("no successful GitHub release baseline was found", {
+    repository: account.remote.repository,
+  });
+  return undefined;
+}
+
 /** Whether this release selection has remote work worth watching. */
 export function shouldWatchReleaseGithubActions(
   options: Pick<ReleaseSelectionOptions, "publish"> & { readonly watchGithubActions?: boolean },
@@ -247,7 +314,8 @@ export async function watchReleaseGithubActions(
         root,
         "gh",
         ["run", "view", String(run.databaseId), "--repo", repository, "--log-failed"],
-        { env: account.env },
+        // gh pipes TTY log output through its pager; release logs must stream inline.
+        { env: { ...account.env, GH_PAGER: "cat" } },
       );
     }
   } catch (error) {
@@ -482,11 +550,21 @@ export async function runRelease(
     readonly watchGithubActions?: boolean;
     readonly githubActionsWatcher?: ReleaseGithubActionsWatcher;
     readonly resolveGithubAccount?: typeof resolveProjectGhAccount;
+    readonly resolveSuccessfulReleaseTag?: SuccessfulReleaseTagResolver;
   },
 ): Promise<string> {
   const { branch, prefix, remote, root } = options;
   const selection = releaseStepSelection(options);
   const install = options.install ?? "auto";
+  let githubAccount: ProjectGhAccount | undefined;
+  let githubAccountResolved = false;
+  const getGithubAccount = (): ProjectGhAccount | undefined => {
+    if (!githubAccountResolved) {
+      githubAccount = (options.resolveGithubAccount ?? resolveProjectGhAccount)(root, { remote });
+      githubAccountResolved = true;
+    }
+    return githubAccount;
+  };
 
   if (options.releaseNotesText !== undefined && options.releaseNotesFile !== undefined) {
     throw new Error("--release-notes-text and --release-notes-file are mutually exclusive");
@@ -539,9 +617,25 @@ export async function runRelease(
     runTaskCommand(root, "bun", ["run", task]);
   }
   if ((options.releaseNotes ?? true) && (options.bump ?? true)) {
+    let successfulTag: string | undefined;
+    if (options.releaseNotesText === undefined && options.releaseNotesFile === undefined) {
+      const account = getGithubAccount();
+      if (account) {
+        successfulTag = (options.resolveSuccessfulReleaseTag ?? resolveSuccessfulReleaseTag)({
+          account,
+          prefix,
+          root,
+        });
+      } else {
+        logger.info("successful GitHub release baseline is unavailable: no authenticated account", {
+          remote,
+        });
+      }
+    }
     (options.writeReleaseNotes ?? writeReleaseNotes)({
       prefix,
       root,
+      successfulTag,
       version,
       content: options.releaseNotesText,
       file: options.releaseNotesFile,
@@ -619,9 +713,7 @@ export async function runRelease(
   }
 
   if (shouldWatchReleaseGithubActions(options, selection)) {
-    const account = (options.resolveGithubAccount ?? resolveProjectGhAccount)(root, {
-      remote,
-    });
+    const account = getGithubAccount();
     if (account) {
       await (options.githubActionsWatcher ?? watchReleaseGithubActions)({
         account,