@dbx-tools/projen 0.9.145 → 0.9.149

package/README.md

@@ -316,14 +316,14 @@ scripts, and generated files on top.
 Every workspace root exposes a generic development watcher:
 
 ```bash
-bun run dev:watch [--debounce-ms 15000] [--restart-key r] <command> [args...]
+bun run dev:watch <command> [args...]
 ```
 
-It restarts after watched writes have been quiet for 15 seconds. Command paths,
-`--cwd`, and `--filter` identify the owning package. Its transitive workspace
+It restarts after watched writes have been quiet for 15 seconds. Command paths
+and task selectors identify the owning package. Its transitive workspace
 dependencies are watched with the shared generated/dependency/test/temp ignores.
-Press the configured key for an immediate restart. The demo uses this task to
-run its concrete server entrypoint. The `server` tag does not assume one.
+The configured restart key triggers an immediate restart. The demo uses this
+task to run its concrete server entrypoint. The `server` tag does not assume one.
 
 AppKit 0.81's `appkitServerConfig()` is the preferred tsdown preset for a
 consumer app using conventional compiled `server/agents/*/agent.ts` entries. It
@@ -540,9 +540,15 @@ the current branch is pushed first. A non-`main` branch then fast-forwards
 diverged. From `main`, it calls the existing `bump` task, commits the generated
 version changes, pushes `main`, and pushes the matching annotated `vX.Y.Z` tag.
 Pass `--no-bump` only to release an existing synchronized local bump. The tag
-workflow verifies that the tag points at the exact `origin/main` commit. One
-`build-release` job installs workspace dependencies, runs validation, packs the
-npm archives, builds all Python distributions, and builds the documentation
+workflow verifies that the tag points at the exact `origin/main` commit. The
+local task completes local publication and demo deployment first, then waits for
+this workflow by default. It preserves the live checklist through a scroll-safe
+non-TTY stream and prints the final logs. Local-only releases and repositories
+without a resolved authenticated GitHub account skip the watcher. Stopping the
+local watcher does not cancel the remote run.
+
+One `build-release` job installs workspace dependencies, runs validation, packs
+the npm archives, builds all Python distributions, and builds the documentation
 site. Install validation prerequisites through `releaseSetupSteps`.
 `releaseDocs.prepareSteps` runs after validation.
 
@@ -551,58 +557,41 @@ workspace. Each Python package retains its own publishing environment and waits
 for its package dependencies to publish. The npm job uses the bundled archive
 publisher without a checkout or workspace install. Pages deploys the already
 built site after registry publication succeeds. Local npm and Python registry publication remains available
-through the direct local publication tooling.
+through the direct local publication tooling. Those local publishers run
+concurrently; a failure or release termination stops every live publisher before
+the command returns.
 
-The default release still publishes npm, Python, and docs, then publishes to
-configured local registries automatically. Select a scope or disable individual
-steps for one run without changing the Projen definition:
+The default release publishes npm, Python, and docs, then publishes to
+configured local registries. Use `bun run release --help` or the generated
+[command reference](#release) for the complete option set. Common workflows:
 
 ```bash
+bun run release
 bun run release --publish pypi --no-docs
-bun run release --no-npm --no-local-publish
 bun run release --publish local --install never
-bun run release --local-registry false --local-pypi auto
 bun run release --demo-deploy --profile <profile>
-bun run release --no-release-notes
-bun run release --release-notes-text "# Release 1.2.3"
-bun run release --release-notes-file ./notes.md
-bun run release --release-notes-instructions "Focus on operator-visible changes."
 ```
 
-`--demo-deploy` is off by default. After tagging and any local registry
-publication it runs `bun run demo:deploy`, which stages the AppKit demo from
-locally compiled Node packages and locally built Python wheels, resolves
-the default environment or configured credentials through
+Demo deployment is a local post-tag action. It stages locally compiled Node
+packages and Python wheels, resolves credentials through
 `@dbx-tools/auth`, including `DATABRICKS_CONFIG_PROFILE`, `DATABRICKS_HOST`,
 and the other auth options, force-refreshes its token with interactive login
 fallback, and deploys it. When auth selects a profile, the deploy passes that
-resolved profile explicitly to every bundle command. That step is local only
-and is not recorded in the annotated tag.
-
-Pass `--profile <name>` to set `DATABRICKS_CONFIG_PROFILE` only for that local
-demo deployment. The profile is not forwarded as a release subcommand
-argument or stored in the release tag.
+resolved profile explicitly to every bundle command. The deployment selection
+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 forbids running tests or other validation
-commands. If Genie fails or writes an empty file, the step keeps going with a
-short git-log summary. `--no-release-notes` skips the file.
-`--release-notes-text` writes supplied markdown directly, while
-`--release-notes-file` copies a prepared markdown file. Both bypass Genie.
-`--release-notes-instructions` appends run-specific guidance to the standard
-Genie prompt. Notes are committed with the version bump and are not recorded in
-the annotated tag. They are skipped on `--no-bump` because that path requires an
-already committed tree.
-
-`--install auto` keeps Projen's normal local dependency-install behavior.
-`always` performs a manifest-resolved install first, and `never` uses dependencies already
-installed while still regenerating versioned sources. Local release validation
-runs `eslint:fix` before branch preparation and bump, then runs the selected
-fail-closed tasks. CI remains check-only.
-CI rebuilds the selected release artifacts instead of checking generated-source fingerprints.
-`--no-validation` skips optional task checks locally and in CI, not workspace-version or immutable-source checks.
-`--no-docs` skips building and deploying the site, not package README validation.
+--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.
+
+Automatic installation retains Projen's manifest-based install trigger; the
+other install modes force installation or reuse the current dependency tree.
+Local release validation runs `eslint:fix` before branch preparation and bump,
+then runs the selected fail-closed tasks. CI remains check-only and rebuilds
+selected release artifacts instead of checking generated-source fingerprints.
+
 Scopes select artifacts, not the normal commit and tag-push transaction.
 The annotated tag records CI step selections, so publishing a selected scope does
 not change the next release's defaults. Local registry URLs stay local.
@@ -652,37 +641,39 @@ release [options]
 
 #### Options
 
-| Option                                 | Description                                                                                                                |
-| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `--root <value>`                       | Repository or workspace root (env: PROJEN_RELEASE_ROOT)                                                                    |
-| `--branch <value>`                     | Release branch (default: "main", env: PROJEN_RELEASE_BRANCH)                                                               |
-| `--prefix <value>`                     | Release tag prefix (default: "v", env: PROJEN_RELEASE_PREFIX)                                                              |
-| `--remote <value>`                     | Git remote (default: "origin", env: PROJEN_RELEASE_REMOTE)                                                                 |
-| `--python-root <value>`                | Python package root for local publish (default: "packages/py", env: PROJEN_RELEASE_PYTHON_ROOT)                            |
-| `--validate <value>`                   | Repeatable task to run before pushing (default: [], env: PROJEN_RELEASE_VALIDATE)                                          |
-| `--bump`                               | Create and synchronize a patch version bump (default: true, env: PROJEN_RELEASE_BUMP)                                      |
-| `--no-bump`                            | Disable create and synchronize a patch version bump                                                                        |
-| `--publish <value>`                    | Publication scope (choices: "auto", "npm", "pypi", "local", "none", default: "auto", env: PROJEN_RELEASE_PUBLISH)          |
-| `-i, --install <value>`                | Local workspace dependency installation (choices: "auto", "always", "never", default: "auto", env: PROJEN_RELEASE_INSTALL) |
-| `-n, --npm`                            | Build and publish npm packages (default: true, env: PROJEN_RELEASE_NPM)                                                    |
-| `--no-npm`                             | Disable build and publish npm packages                                                                                     |
-| `--pypi`                               | Build and publish Python packages (default: true, env: PROJEN_RELEASE_PYPI)                                                |
-| `--no-pypi`                            | Disable build and publish python packages                                                                                  |
-| `--docs`                               | Build and deploy documentation (env: PROJEN_RELEASE_DOCS)                                                                  |
-| `--no-docs`                            | Disable build and deploy documentation                                                                                     |
-| `--validation`                         | Run optional release validation tasks before publishing (default: true, env: PROJEN_RELEASE_VALIDATION)                    |
-| `--no-validation`                      | Disable run optional release validation tasks before publishing                                                            |
-| `--release-notes`                      | Write release notes before tagging (default: true, env: PROJEN_RELEASE_RELEASE_NOTES)                                      |
-| `--no-release-notes`                   | Disable write release notes before tagging                                                                                 |
-| `--release-notes-text <value>`         | Write supplied release-note Markdown without invoking Genie (env: PROJEN_RELEASE_RELEASE_NOTES_TEXT)                       |
-| `--release-notes-file <value>`         | Copy release-note Markdown from this file without invoking Genie (env: PROJEN_RELEASE_RELEASE_NOTES_FILE)                  |
-| `--release-notes-instructions <value>` | Append instructions to the Genie release-note prompt (env: PROJEN_RELEASE_RELEASE_NOTES_INSTRUCTIONS)                      |
-| `--demo-deploy`                        | Deploy the AppKit demo after tagging and local publication (env: PROJEN_RELEASE_DEMO_DEPLOY)                               |
-| `--no-demo-deploy`                     | Disable deploy the appkit demo after tagging and local publication                                                         |
-| `--profile <value>`                    | Optional Databricks CLI profile passed to the demo deployment (env: PROJEN_RELEASE_PROFILE)                                |
-| `--local-publish`                      | Publish to configured local registries (default: true, env: PROJEN_RELEASE_LOCAL_PUBLISH)                                  |
-| `--no-local-publish`                   | Disable publish to configured local registries                                                                             |
-| `--local-registry <value>`             | Local npm registry selection: auto, false, or URL (default: "auto", env: PROJEN_RELEASE_LOCAL_REGISTRY)                    |
-| `--local-pypi <value>`                 | Local devpi registry selection: auto, false, or URL (default: "auto", env: PROJEN_RELEASE_LOCAL_PYPI)                      |
+| Option                                 | Description                                                                                                                                                       |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--root <value>`                       | Repository or workspace root (env: PROJEN_RELEASE_ROOT)                                                                                                           |
+| `--branch <value>`                     | Release branch (default: "main", env: PROJEN_RELEASE_BRANCH)                                                                                                      |
+| `--prefix <value>`                     | Release tag prefix (default: "v", env: PROJEN_RELEASE_PREFIX)                                                                                                     |
+| `--remote <value>`                     | Git remote (default: "origin", env: PROJEN_RELEASE_REMOTE)                                                                                                        |
+| `--python-root <value>`                | Python package root for local publish (default: "packages/py", env: PROJEN_RELEASE_PYTHON_ROOT)                                                                   |
+| `--validate <value>`                   | Repeatable task to run before pushing (default: [], env: PROJEN_RELEASE_VALIDATE)                                                                                 |
+| `--bump`                               | Create and synchronize a patch bump; disable only for an existing committed bump (default: true, env: PROJEN_RELEASE_BUMP)                                        |
+| `--no-bump`                            | Disable create and synchronize a patch bump; disable only for an existing committed bump                                                                          |
+| `--publish <value>`                    | Publication scope (choices: "auto", "npm", "pypi", "local", "none", default: "auto", env: PROJEN_RELEASE_PUBLISH)                                                 |
+| `-i, --install <value>`                | Dependency install mode: auto follows manifests, always installs, never reuses (choices: "auto", "always", "never", default: "auto", env: PROJEN_RELEASE_INSTALL) |
+| `-n, --npm`                            | Build and publish npm packages (default: true, env: PROJEN_RELEASE_NPM)                                                                                           |
+| `--no-npm`                             | Disable build and publish npm packages                                                                                                                            |
+| `--pypi`                               | Build and publish Python packages (default: true, env: PROJEN_RELEASE_PYPI)                                                                                       |
+| `--no-pypi`                            | Disable build and publish python packages                                                                                                                         |
+| `--docs`                               | Build and deploy documentation (env: PROJEN_RELEASE_DOCS)                                                                                                         |
+| `--no-docs`                            | Disable build and deploy documentation                                                                                                                            |
+| `--validation`                         | Run optional release validation tasks before publishing (default: true, env: PROJEN_RELEASE_VALIDATION)                                                           |
+| `--no-validation`                      | Disable run optional release validation tasks before publishing                                                                                                   |
+| `-w, --watch-github-actions`           | Wait for and log the tag-triggered GitHub Actions release (default: true, env: PROJEN_RELEASE_WATCH_GITHUB_ACTIONS)                                               |
+| `--no-watch-github-actions`            | Disable wait for and log the tag-triggered github actions release                                                                                                 |
+| `--release-notes`                      | Generate and commit release notes for a new version bump (default: true, env: PROJEN_RELEASE_RELEASE_NOTES)                                                       |
+| `--no-release-notes`                   | Disable generate and commit release notes for a new version bump                                                                                                  |
+| `--release-notes-text <value>`         | Write supplied release-note Markdown without invoking Genie (env: PROJEN_RELEASE_RELEASE_NOTES_TEXT)                                                              |
+| `--release-notes-file <value>`         | Copy release-note Markdown from this file without invoking Genie (env: PROJEN_RELEASE_RELEASE_NOTES_FILE)                                                         |
+| `--release-notes-instructions <value>` | Append instructions to the Genie release-note prompt (env: PROJEN_RELEASE_RELEASE_NOTES_INSTRUCTIONS)                                                             |
+| `--demo-deploy`                        | Run the local-only AppKit demo deployment after tagging and publication (env: PROJEN_RELEASE_DEMO_DEPLOY)                                                         |
+| `--no-demo-deploy`                     | Disable run the local-only appkit demo deployment after tagging and publication                                                                                   |
+| `--profile <value>`                    | Optional Databricks CLI profile passed to the demo deployment (env: PROJEN_RELEASE_PROFILE)                                                                       |
+| `--local-publish`                      | Publish to configured local registries (default: true, env: PROJEN_RELEASE_LOCAL_PUBLISH)                                                                         |
+| `--no-local-publish`                   | Disable publish to configured local registries                                                                                                                    |
+| `--local-registry <value>`             | Local npm registry selection: auto, false, or URL (default: "auto", env: PROJEN_RELEASE_LOCAL_REGISTRY)                                                           |
+| `--local-pypi <value>`                 | Local devpi registry selection: auto, false, or URL (default: "auto", env: PROJEN_RELEASE_LOCAL_PYPI)                                                             |
 
 <!-- cli-reference:end -->

package/index.ts

@@ -3,7 +3,7 @@
 // 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.145";
+export const PACKAGE_VERSION = "0.9.149";
 export * as barrels from "./src/barrels.ts";
 export * as bunApp from "./src/bun-app.ts";
 export * as bunWorkflow from "./src/bun-workflow.ts";
@@ -65,7 +65,7 @@ export { PYTHON_NODE_RUNTIME_DISTRIBUTION, PYTHON_NODE_RUNTIME_MODULE, PYTHON_NO
 export type { PythonNodeRuntimeOptions } from "./src/python-node-runtime.ts";
 export { DBXToolsRelease } from "./src/release.ts";
 export type { ReleaseDocsOptions, DBXToolsReleaseOptions } from "./src/release.ts";
-export { RELEASE_VERSION } from "./src/release-context.ts";
+export { RELEASE_VERSION, RELEASE_WORKFLOW_FILE } from "./src/release-context.ts";
 export { RELEASE_PUBLISH_TARGETS, RELEASE_INSTALL_MODES, ReleaseStepSelectionSchema } from "./src/release-options.ts";
 export type { ReleasePublishTarget, ReleaseInstallMode, ReleaseStepSelection, ReleaseSelectionOptions } from "./src/release-options.ts";
 export { SHARED_CORE_BINDING_EXPORTS } from "./src/shared-core-usage.ts";

package/package.json

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

package/src/_task-command.ts

@@ -40,7 +40,17 @@ export async function runTaskCommandAsync(
   args: readonly string[],
   options: TaskCommandOptions & { readonly signal?: AbortSignal } = {},
 ): Promise<void> {
-  await exec.spawn(executable(command), [...args], {
+  await spawnTaskCommand(cwd, command, args, options);
+}
+
+/** Start one supervised task command and return its live process handle. */
+export function spawnTaskCommand(
+  cwd: string,
+  command: string,
+  args: readonly string[],
+  options: TaskCommandOptions & { readonly signal?: AbortSignal } = {},
+): exec.ChildProcessResult {
+  return exec.spawn(executable(command), [...args], {
     cwd,
     env: options.env,
     stdout: "inherit",
@@ -51,6 +61,31 @@ export async function runTaskCommandAsync(
   });
 }
 
+/**
+ * Run a command with piped stdout forwarded line-by-line.
+ *
+ * The child sees a non-TTY output stream, so interactive redraw commands fall
+ * back to append-only output while the parent still receives live progress.
+ */
+export async function streamTaskCommand(
+  cwd: string,
+  command: string,
+  args: readonly string[],
+  options: TaskCommandOptions = {},
+): Promise<void> {
+  await exec.spawn(executable(command), [...args], {
+    cwd,
+    env: options.env,
+    stdout: {
+      capture: false,
+      onLine: (line) => console.log(line),
+    },
+    stderr: options.stderr ?? "inherit",
+    stdin: "ignore",
+    check: true,
+  });
+}
+
 /** Capture trimmed stdout, optionally throwing when the command fails. */
 export function captureTaskCommand(
   cwd: string,

package/src/release-context.ts

@@ -1,3 +1,5 @@
 /** Verified release context shared by every job in the unified workflow. */
 /** Version verified by the shared build that produced every publication artifact. */
 export const RELEASE_VERSION = "${{ needs.build-release.outputs.release_version }}";
+/** Generated GitHub Actions workflow triggered by release tags. */
+export const RELEASE_WORKFLOW_FILE = "release.yml";

package/src/release.ts

@@ -16,7 +16,7 @@ import { GithubWorkflow } from "projen/lib/github";
 import { JobPermission, type Job, type JobStep } from "projen/lib/github/workflows-model";
 import { BUN_VERSION } from "./bun-workflow.ts";
 import { projectReleaseBranch, taskCommand, type DBXToolsJavaScriptProject } from "./project-js.ts";
-import { RELEASE_VERSION } from "./release-context.ts";
+import { RELEASE_VERSION, RELEASE_WORKFLOW_FILE } from "./release-context.ts";
 import type { ReleaseStepSelection } from "./release-options.ts";
 
 const NODE_VERSION = "24";
@@ -339,7 +339,7 @@ export class DBXToolsRelease extends Component {
     if (!project.github) return;
 
     const workflow = new GithubWorkflow(project.github, "release", {
-      fileName: "release.yml",
+      fileName: RELEASE_WORKFLOW_FILE,
       limitConcurrency: true,
       concurrencyOptions: {
         group: "release",

package/tasks/local-publish.ts

@@ -1,10 +1,11 @@
 /** Build and publish the current workspace to configured loopback registries. */
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import type { ChildProcessResult } from "@dbx-tools/core/exec";
 import * as projectUtils from "@dbx-tools/core/project-utils";
 import { log, net } from "@dbx-tools/shared-core";
 import { activePythonIndexes, resolveLocalPypi } from "./python-registry.ts";
-import { runTaskCommandAsync } from "../src/_task-command.ts";
+import { spawnTaskCommand } from "../src/_task-command.ts";
 
 const logger = log.logger("projen:local-publish");
 
@@ -38,6 +39,24 @@ export function localPublishTaskPath(task: "publish.ts" | "publish-python.ts"):
   return fileURLToPath(new URL(task, import.meta.url));
 }
 
+/** Await concurrent publishers and terminate every live sibling after one fails. */
+export async function awaitLocalPublishers(
+  publishes: readonly ChildProcessResult[],
+): Promise<void> {
+  try {
+    await Promise.all(publishes);
+  } catch (error) {
+    await Promise.all(
+      publishes.map((publish) =>
+        publish.exitCode === null && publish.signalCode === null
+          ? publish.shutdown()
+          : Promise.resolve(),
+      ),
+    );
+    throw error;
+  }
+}
+
 /** Build and publish the current workspace directly to local registries. */
 export async function publishLocalRelease(
   options: LocalPublishOptions,
@@ -46,7 +65,7 @@ export async function publishLocalRelease(
   const localRegistry = resolveLocalRegistry(options.localRegistry);
   const activeIndexes = activePythonIndexes();
   const localPypi = resolveLocalPypi(options.localPypi, activeIndexes);
-  const publishes: Promise<unknown>[] = [];
+  const publishes: ChildProcessResult[] = [];
 
   if (
     options.localPypi.toLowerCase() === "auto" &&
@@ -62,7 +81,7 @@ export async function publishLocalRelease(
     const publishNpmScript = localPublishTaskPath("publish.ts");
     logger.info(`building and publishing npm workspace to ${localRegistry}`);
     publishes.push(
-      runTaskCommandAsync(root, process.execPath, [
+      spawnTaskCommand(root, process.execPath, [
         publishNpmScript,
         options.version,
         "--registry",
@@ -75,7 +94,7 @@ export async function publishLocalRelease(
     const publishPythonScript = localPublishTaskPath("publish-python.ts");
     logger.info(`building and publishing Python workspace to ${localPypi.publishUrl}`);
     publishes.push(
-      runTaskCommandAsync(root, process.execPath, [
+      spawnTaskCommand(root, process.execPath, [
         publishPythonScript,
         options.version,
         "--root",
@@ -93,7 +112,7 @@ export async function publishLocalRelease(
     return { npm: false, python: false };
   }
 
-  await Promise.all(publishes);
+  await awaitLocalPublishers(publishes);
   logger.success(`published local workspace ${options.version}`);
   return { npm: Boolean(localRegistry), python: Boolean(localPypi) };
 }

package/tasks/release.ts

@@ -3,7 +3,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import * as projectUtils from "@dbx-tools/core/project-utils";
-import { errorUtils, log } from "@dbx-tools/shared-core";
+import { errorUtils, json, log } from "@dbx-tools/shared-core";
 import type { Command } from "commander";
 import { z } from "zod";
 import { parsedTaskOptions, runTaskMain, taskCommand } from "./cli.ts";
@@ -11,7 +11,13 @@ import { publishLocalRelease } from "./local-publish.ts";
 import { TaskDirectoriesOptionSchema, TaskRootOptionSchema } from "./options.ts";
 import { writeReleaseNotes } from "./release-notes.ts";
 import { assertReleaseVersion } from "./release-version.ts";
-import { captureTaskCommand, runTaskCommand, taskCommandSucceeds } from "../src/_task-command.ts";
+import {
+  captureTaskCommand,
+  runTaskCommand,
+  streamTaskCommand,
+  taskCommandSucceeds,
+} from "../src/_task-command.ts";
+import { RELEASE_WORKFLOW_FILE } from "../src/release-context.ts";
 import {
   RELEASE_INSTALL_MODES,
   RELEASE_PUBLISH_TARGETS,
@@ -24,6 +30,143 @@ import {
 import { readWorkspaceVersion } from "../src/workspace-version.ts";
 
 const logger = log.logger("projen:release");
+const GITHUB_ACTIONS_START_TIMEOUT_MS = 2 * 60_000;
+const GITHUB_ACTIONS_POLL_INTERVAL_MS = 2_000;
+
+const GithubReleaseRunSchema = z
+  .object({
+    databaseId: z.number().int().positive(),
+    headBranch: z.string(),
+    headSha: z.string(),
+    status: z.string(),
+    url: z.string(),
+  })
+  .passthrough();
+
+/** Inputs required to locate and watch one tag-triggered release workflow. */
+export interface WatchReleaseGithubActionsOptions {
+  readonly account: projectUtils.ProjectGhAccount;
+  readonly head: string;
+  readonly root: string;
+  readonly tag: string;
+  readonly pollIntervalMs?: number;
+  readonly startTimeoutMs?: number;
+}
+
+/** GitHub release watcher boundary replaceable by release tests. */
+export type ReleaseGithubActionsWatcher = (
+  options: WatchReleaseGithubActionsOptions,
+) => Promise<void>;
+
+function githubRepository(account: projectUtils.ProjectGhAccount): string {
+  return account.host === "github.com"
+    ? account.remote.repository
+    : `${account.host}/${account.remote.repository}`;
+}
+
+function delay(milliseconds: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+/** Whether this release selection has remote work worth watching. */
+export function shouldWatchReleaseGithubActions(
+  options: Pick<ReleaseSelectionOptions, "publish"> & { readonly watchGithubActions?: boolean },
+  selection: ReturnType<typeof releaseStepSelection>,
+): boolean {
+  if (options.watchGithubActions === false) return false;
+  if (options.publish === "local" && !selection.npm && !selection.pypi && !selection.docs) {
+    return false;
+  }
+  return Object.values(selection).some(Boolean);
+}
+
+/** Wait for a tag-triggered workflow, show live progress, then print its logs. */
+export async function watchReleaseGithubActions(
+  options: WatchReleaseGithubActionsOptions,
+): Promise<void> {
+  const {
+    account,
+    head,
+    root,
+    tag,
+    pollIntervalMs = GITHUB_ACTIONS_POLL_INTERVAL_MS,
+    startTimeoutMs = GITHUB_ACTIONS_START_TIMEOUT_MS,
+  } = options;
+  const repository = githubRepository(account);
+  const deadline = Date.now() + startTimeoutMs;
+  let run: z.infer<typeof GithubReleaseRunSchema> | undefined;
+  while (!run && Date.now() < deadline) {
+    const output = captureTaskCommand(
+      root,
+      "gh",
+      [
+        "run",
+        "list",
+        "--repo",
+        repository,
+        "--workflow",
+        RELEASE_WORKFLOW_FILE,
+        "--commit",
+        head,
+        "--event",
+        "push",
+        "--limit",
+        "20",
+        "--json",
+        "databaseId,headBranch,headSha,status,url",
+      ],
+      { check: true, env: account.env, stderr: "inherit" },
+    );
+    const parsed = z.array(GithubReleaseRunSchema).safeParse(json.parse(output, []));
+    if (!parsed.success) throw new Error("GitHub returned invalid release workflow metadata");
+    run = parsed.data.find(
+      (candidate) => candidate.headSha === head && candidate.headBranch === tag,
+    );
+    if (!run) await delay(pollIntervalMs);
+  }
+  if (!run) {
+    logger.warn("GitHub Actions release run did not start before the watch timeout", {
+      repository: account.remote.repository,
+      tag,
+    });
+    return;
+  }
+
+  logger.info("watching GitHub Actions release", {
+    repository: account.remote.repository,
+    runId: run.databaseId,
+    status: run.status,
+    url: run.url,
+  });
+  try {
+    await streamTaskCommand(
+      root,
+      "gh",
+      [
+        "run",
+        "watch",
+        String(run.databaseId),
+        "--repo",
+        repository,
+        "--interval",
+        String(Math.max(1, Math.round(pollIntervalMs / 1_000))),
+      ],
+      { env: { ...account.env, NO_COLOR: "1" } },
+    );
+    runTaskCommand(
+      root,
+      "gh",
+      ["run", "view", String(run.databaseId), "--repo", repository, "--log"],
+      { env: account.env },
+    );
+  } catch (error) {
+    logger.warn("GitHub Actions release watch stopped; the remote run was not cancelled", {
+      error: errorUtils.toError(error),
+      runId: run.databaseId,
+      url: run.url,
+    });
+  }
+}
 
 /** Whether the root manifest exposes one repository-owned script. */
 function hasPackageScript(root: string, name: string): boolean {
@@ -244,6 +387,10 @@ export async function runRelease(
     /** Path to complete release notes supplied instead of invoking Genie. */
     readonly releaseNotesFile?: string;
     readonly writeReleaseNotes?: typeof writeReleaseNotes;
+    /** After local release actions, wait for and stream the matching GitHub Actions run. */
+    readonly watchGithubActions?: boolean;
+    readonly githubActionsWatcher?: ReleaseGithubActionsWatcher;
+    readonly resolveGithubAccount?: typeof projectUtils.resolveProjectGhAccount;
   },
 ): Promise<string> {
   const { branch, prefix, remote, root } = options;
@@ -368,6 +515,25 @@ export async function runRelease(
     ]);
   }
 
+  if (shouldWatchReleaseGithubActions(options, selection)) {
+    const account = (options.resolveGithubAccount ?? projectUtils.resolveProjectGhAccount)(root, {
+      remote,
+    });
+    if (account) {
+      await (options.githubActionsWatcher ?? watchReleaseGithubActions)({
+        account,
+        head,
+        root,
+        tag,
+      });
+    } else {
+      logger.info("skipping GitHub Actions release watch: no authenticated account", {
+        remote,
+        tag,
+      });
+    }
+  }
+
   return tag;
 }
 
@@ -383,12 +549,15 @@ export const ReleaseOptionsSchema = z.object({
     .default("packages/py")
     .describe("Python package root for local publish"),
   validate: TaskDirectoriesOptionSchema.describe("Repeatable task to run before pushing"),
-  bump: z.boolean().default(true).describe("Create and synchronize a patch version bump"),
+  bump: z
+    .boolean()
+    .default(true)
+    .describe("Create and synchronize a patch bump; disable only for an existing committed bump"),
   publish: z.enum(RELEASE_PUBLISH_TARGETS).default("auto").describe("Publication scope"),
   install: z
     .enum(RELEASE_INSTALL_MODES)
     .default("auto")
-    .describe("Local workspace dependency installation"),
+    .describe("Dependency install mode: auto follows manifests, always installs, never reuses"),
   npm: z.boolean().default(true).describe("Build and publish npm packages"),
   pypi: z.boolean().default(true).describe("Build and publish Python packages"),
   docs: z.boolean().optional().describe("Build and deploy documentation"),
@@ -396,7 +565,14 @@ export const ReleaseOptionsSchema = z.object({
     .boolean()
     .default(true)
     .describe("Run optional release validation tasks before publishing"),
-  releaseNotes: z.boolean().default(true).describe("Write release notes before tagging"),
+  watchGithubActions: z
+    .boolean()
+    .default(true)
+    .describe("Wait for and log the tag-triggered GitHub Actions release"),
+  releaseNotes: z
+    .boolean()
+    .default(true)
+    .describe("Generate and commit release notes for a new version bump"),
   releaseNotesText: z
     .string()
     .optional()
@@ -414,7 +590,7 @@ export const ReleaseOptionsSchema = z.object({
   demoDeploy: z
     .boolean()
     .optional()
-    .describe("Deploy the AppKit demo after tagging and local publication"),
+    .describe("Run the local-only AppKit demo deployment after tagging and publication"),
   profile: z
     .string()
     .trim()
@@ -460,6 +636,7 @@ export function createReleaseCommand(): Command {
       pypi: options.pypi,
       docs: options.docs,
       validation: options.validation,
+      watchGithubActions: options.watchGithubActions,
       validationTasks: options.validate,
       demoDeploy: options.demoDeploy,
       demoProfile: options.profile,