forge-workflow 0.1.0-beta.6 → 0.1.0-beta.8

package/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 > **Note**: `/check` was renamed to `/validate` and `/merge` was renamed to `/premerge` in v0.0.3. Historical entries below may use the old names.
 
+## [Unreleased]
+
+## [0.1.0-beta.8] - 2026-09-26
+
+### Added
+
+- **Deterministic full generation for the test workflow.** `forge release generate-test-workflow --expect-head <sha>` renders `.github/workflows/test.yml` from its canonical staged template and Bun pin under an exact actor, worktree, source-HEAD, path, operation, and content-bound authorization. Bun pin updates delegate this workflow to the same renderer, preventing partial pin replacement from authorizing unrelated CI changes. (PR #567; issue `a541c8ca-579d-4b8e-9bfd-7980b7547302`)
+- **Optional transparent GitHub account routing per clone.** `forge github use <login> --auto` extends the existing secure account binding to shell-resolved `gh` and HTTPS Git commands when Forge's router is first on PATH, so concurrent terminals and harness shells can use different native GitHub CLI accounts without per-launch wrapping. Unbound and non-enabled clones pass through unchanged; local-only commands and `gh auth` remain native, while network-capable aliases and extensions inherit the selected account. V1 is public `github.com` only; built-in destination conflicts and non-public targets fail closed, and arbitrary user-installed code remains outside Forge's wrong-destination guarantee. The machine-local router registry must refuse uninstall while another verified clone remains enabled and must never store credentials. Release acceptance requires the installed PATH chain and warm median targets of 250 ms for unbound/local-only routing and 1,000 ms for bound `gh` and helper resolution. Forge never stores a token. (PR #563; issue `8168bee5-b74e-44e5-8fd8-1b9ccb917c1d`)
+
+### Fixed
+
+- **The npm package installs with Bun.** `@forge/flow`, `@forge/memory`, and `@forge/contracts` are now only bundled in `forge-workflow`, not also declared as registry `dependencies`; Bun resolved those entries from the registry, where the unpublished workspaces return 404, so `bun add forge-workflow@0.1.0-beta.7` failed. The workspaces stay linked for development as `devDependencies`, and npm installs are unchanged. The packed-install smoke now also installs the tarball with `bun add` and runs `forge --version` and `forge setup --quick --yes`. (issue `95ed8d5f-0578-48de-bc44-17b5afa48161`)
+- **Canonical validation exposes an honest full-suite resource budget.** `forge validate --shards N` forwards a positive integer budget to the Forge scheduler. Windows budgets that cannot fund a required worker fail before test workers start; automatic defaults normalize visibly. Requested/effective or rejection evidence is retained and displayed by the CLI without changing required tests, deadlines, or receipt identity. (#574, issue `e0cb0671-735c-4980-944b-286d6f78fe48`)
+- **Standalone package smoke installs identify packed packages before npm builds the install tree.** The fixture now carries each package name from the same successful `npm pack --json` result into its local tarball specification, avoiding npm's redundant add-request name discovery while preserving tarball extraction, bundled workspaces, installed identity checks, CLI version/setup coverage, and the existing deadlines. (issue `6b432d06-5ab3-4188-8814-0ae056430cac`)
+- **Exact version queries avoid loading the command graph.** Direct `forge --version` and `forge -V` print the packaged version before loading command modules, reducing cold startup during standalone installation checks. Imported helpers and mixed command arguments keep their existing behavior. (issue `6b432d06-5ab3-4188-8814-0ae056430cac`)
+- **The workflow projection hook test avoids a duplicate Git scan.** It retains the real commit-hook rejection and verifies the exact projection mismatch and zero authority consumption through existing fixture readers, without changing test deadlines or production authorization. (issue `e70683d6-f8df-471b-b859-a6dacb69825c`)
+- **Segmented Flow monitor checkpoints no longer repeat full-tail compression searches.** Recovery planning bounds records once and adapts from the last accepted segment width while preserving payload limits, ordered records, integrity metadata, terminal snapshot placement, and fail-closed interrupted-plan recovery. (issues `9eb98ac0-ebe1-4604-a57a-5fefadad6682`, `6648ef9b-381a-4a19-ad9a-06341e62676f`)
+- **The failed full-suite child regression now selects only its test gate.** Its synthetic validation fixture still proves fail-closed classification and stale receipt deletion without running unrelated repository checks. (issue `3ce7c502-ccaf-46e6-af12-961ff5ffd2e7`)
+- **The smart-status CRLF fixture avoids a redundant wrapper on compatible Windows jq executables.** It verifies genuine CRLF bytes before selecting native jq, preserves the CRLF-producing fallback for LF-only commands and non-Windows hosts, and propagates jq failures through that wrapper without changing the 20-second test deadline or production status behavior. (issue `c8ece1ef-e410-45b8-98bc-ca184fa4f828`)
+- **Forge pushes use the supervised full-suite runner when validation cannot be reused.** Consumer repositories retain their configured test command, and failed or incomplete runs prevent the push. Git arguments retain their order across Forge's passthrough delimiter. (issues `11e5ef49-5ae3-4cd0-a32e-0f233fc00ce8`, `e8b5e91f-d9f3-40e3-921a-e12c392054f1`)
+- **Slow pre-push hooks no longer expire authorization for completed checks.** Reuse is bound to the live push, its worktree, branch, unchanged inputs, and completed gates; ended or mismatched invocations run the ordinary hooks. Quick pushes continue to omit tests explicitly. (issue `291d09b0-b3c4-41a6-8fa0-6b843e7fad05`)
+- **The test workflow template marker no longer resembles a credential assignment.** Internal renderer code now describes `__BUN_VERSION__` as a placeholder, so the shipped-library secret scan accepts the deterministic workflow writer without weakening its detection rules or changing generated workflow bytes. (issue `0acc4a68-ab0a-4008-83bf-6e954d075007`)
+
+## [0.1.0-beta.7] - 2026-09-11
+
+### Changed
+
+- **A clean full validation is reused by the next unchanged `forge push`.** Forge stores a one-hour, signed local receipt bound to the canonical worktree, exact HEAD, clean state, Forge, Bun, and Node runtimes, and complete nonzero gate results. Branch protection and lint still run; invalid or stale evidence falls back to the full suite, while raw Git pushes and CI remain independent.
+- **A local full suite no longer reruns its already-included E2E directory.** Targeted E2E execution is unchanged, while full validation avoids an exact duplicate. (issue `4aed2cc8-57eb-451b-bb3a-02bbdd93af49`)
+- **The shared public contract package is now `@forge/contracts`.** The product-neutral name replaces the former unpublished Memory-qualified name before beta.7, and all three scoped packages explicitly publish as public MIT packages linked to the public Forge repository. (issue `4d41ffb7-8793-4a17-a30b-92130db69672`)
+
+### Fixed
+
+- **The npm package now includes every internal runtime workspace.** Root runtime imports use the `@forge/memory`, `@forge/contracts`, and `@forge/flow` package boundaries, and npm bundles those unpublished workspaces into `forge-workflow`. The installed-package smoke accepts npm 10 lifecycle output before its JSON payload, so Node 22 verifies the same package correctly. A fresh packed install now runs `forge --version` and `forge setup --quick --yes`, preventing the `MODULE_NOT_FOUND` failure in v0.1.0-beta.6. (issue `95372af8-da00-42e0-af64-0111ddab3405`)
+
 ## [0.1.0-beta.6] - 2026-09-11
 
 ### Added
@@ -23,6 +58,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **Bun workflow commit-boundary validation avoids redundant Windows process startup.** Protected-state checks batch the complete source/index pin snapshot into four Git calls and reuse successful executable resolution for an unchanged command environment; Windows full-suite scheduling defers unit work until subprocess workers release the machine, preserving every assertion and fail-closed check without increasing timeouts. (#557, issue `c56c483c-34ef-4354-a976-030464ac416e`)
 - **Legacy claim repair now compares exact Windows file identities and timestamps.** BigInt filesystem metadata prevents rounded device/inode collisions from treating distinct files as aliases, while nanosecond timestamps keep recovery-state drift checks fail closed. (#556, issue `7e164066-4d41-4d14-90ef-1b7ee14e2b73`)
 - **Dep-guard apply-decision tests no longer contend with shared Windows subprocess shards.** The process-heavy suite now uses the existing exclusive resource lane, with exact scheduler coverage and no timeout increase or exemption. (issue `762ae565-0059-4827-9c3d-b4249f2b3364`)
 - **Bun workflow proof tests no longer contend with shared full-suite shards.** The process-heavy commit-boundary proof now uses the existing exclusive resource lane, with exact scheduler coverage and no timeout increase or exemption. (#552, issue `2daab8c0-34d6-4378-8cf4-dce6fdbfb86b`)

package/bin/forge-gh-proxy.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+'use strict';
+
+const { isLocalGhInvocation, runNativeGh } = require('../lib/native-gh');
+
+function runProxyEntrypoint(args, projectRoot = process.cwd(), options = {}) {
+  const ghArgs = args[0] === '--' ? args.slice(1) : args;
+  if (isLocalGhInvocation(ghArgs)) return (options.runNative || runNativeGh)(ghArgs, projectRoot, options);
+  const runProxy = options.runProxy || require('../lib/gh-proxy').runGhProxy;
+  return runProxy(ghArgs, projectRoot);
+}
+
+if (require.main === module) process.exitCode = runProxyEntrypoint(process.argv.slice(2));
+
+module.exports = { runProxyEntrypoint };

package/bin/forge-github-credential.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+
+function runCredentialEntrypoint(args, projectRoot = process.cwd(), options = {}) {
+  const operation = args[0] === '--' ? args[1] : args[0];
+  if (!['get', 'store', 'erase'].includes(operation)) return 1;
+  try {
+    const input = operation === 'get' ? (options.readInput || (() => fs.readFileSync(0, 'utf8')))() : '';
+    const runCredential = options.runCredential || require('../lib/github-credential').runCredentialHelper;
+    return runCredential(operation, { input, projectRoot });
+  } catch {
+    (options.writeError || (value => process.stderr.write(value)))('Forge could not read the Git credential request.\n');
+    return 1;
+  }
+}
+
+if (require.main === module) process.exitCode = runCredentialEntrypoint(process.argv.slice(2));
+
+module.exports = { runCredentialEntrypoint };

package/bin/forge.js

@@ -46,6 +46,11 @@ const { execSync } = require('node:child_process');
 const packageDir = path.dirname(__dirname);
 const packageJson = require('../package.json');
 const VERSION = packageJson.version;
+const args = process.argv.slice(2);
+
+if (require.main === module && args.length === 1 && ['--version', '-V'].includes(args[0])) {
+  console.log(`Forge v${VERSION}`);
+} else {
 
 // Load PluginManager for discoverable agent architecture
 const PluginManager = require('../lib/plugin-manager');
@@ -104,7 +109,6 @@ const { detectHusky, migrateHusky } = require('../lib/husky-migration');
 
 // Get the project root (let allows reassignment after --path flag handling)
 let projectRoot = process.env.INIT_CWD || process.cwd();
-const args = process.argv.slice(2);
 
 // Incremental setup state (set during main() from parsed flags)
 let FORCE_MODE = false;
@@ -3650,6 +3654,16 @@ async function handleExternalServices(skipExternal, selectedAgents) {
 
 async function main() {
   let command = args[0];
+  if (command === 'github' && args[1] === 'credential') {
+    const { runCredentialEntrypoint } = require('./forge-github-credential');
+    process.exitCode = runCredentialEntrypoint(args.slice(2), process.cwd());
+    return;
+  }
+  if (command === 'github' && args[1] === 'proxy' && args[2] === '--') {
+    const { runProxyEntrypoint } = require('./forge-gh-proxy');
+    process.exitCode = runProxyEntrypoint(args.slice(2), process.cwd());
+    return;
+  }
   const flags = parseFlags();
   const suppressJsonIntrospectionOutput = ['options', 'explain'].includes(command) && args.includes('--json');
   const suppressCommandJsonOutput = args.includes('--json');
@@ -4520,3 +4534,4 @@ module.exports = {
   validateDirectoryPathInput,
   validateUserInput,
 };
+}

package/docs/guides/MIGRATION.md

@@ -1,6 +1,6 @@
 # Migration Guide
 
-Use this guide when moving older Forge docs, habits, or installed scaffolding toward the v0.1.0-beta.6 public framing.
+Use this guide when moving older Forge docs, habits, or installed scaffolding toward the v0.1.0-beta.8 public framing.
 
 ## What Changed
 
@@ -39,8 +39,9 @@ forge setup --agents claude,cursor
 
 ## Version Labels
 
-- `0.1.0-beta.6` is the current prerelease package version.
-- `0.1.0-beta.5` is the previous prerelease package version.
+- `0.1.0-beta.8` is the current prerelease package version.
+- `0.1.0-beta.7` is the previous prerelease package version; npm installs it, but Bun cannot, because it also declares the bundled runtime workspaces as registry dependencies. Upgrade directly to beta.8.
+- `0.1.0-beta.6` omits required runtime workspaces from its npm tarball; do not install it.
 - Internal labels such as `0.0.19` or `v3` describe roadmap slices or historical codenames. Do not present them as current package versions.
 
 ## Safe Upgrade Path

package/docs/reference/RELEASE.md

@@ -2,9 +2,9 @@
 
 This page documents release readiness. Package publishing still requires the explicit publish step after merge.
 
-## v0.1.0-beta.6 Boundary
+## v0.1.0-beta.8 Boundary
 
-v0.1.0-beta.6 is the current prerelease boundary. The release branch declares `0.1.0-beta.6`; publish only after the release PR is merged, tagged, and validated on that exact SHA.
+v0.1.0-beta.8 is the current prerelease boundary. The release branch declares `0.1.0-beta.8`; publish only after the release PR is merged, tagged, and validated on that exact SHA.
 
 Keep these release steps explicit:
 
@@ -25,6 +25,8 @@ npm pack --dry-run
 
 The trusted npm workflow is generated through `forge release generate-npm-workflow --expect-head "$(git rev-parse HEAD)"`; the full expected SHA must match the current checkout, and direct workflow edits remain blocked. The generated authorization is bound to that SHA, actor, worktree, path, and exact content, so moving HEAD before staging also fails closed. On a release event, the workflow resolves the tag once, runs the complete supported repository suite on that immutable commit, and allows publication only when the attributable suite receipt, verification checkout, and publish checkout all name the same SHA.
 
+Generate the canonical test workflow through `forge release generate-test-workflow --expect-head "$(git rev-parse HEAD)"`. The command renders the staged `lib/workflow-templates/test.yml` with the staged manifest's exact Bun version, rejects unrelated target bytes, and binds the protected write to the expected HEAD and exact generated content. For a Bun version change, use `forge release update-bun-pins --expect-head "$(git rev-parse HEAD)"`; it delegates `test.yml` to the same full renderer while preserving the pin-only updates for the other workflows.
+
 For docs-heavy changes, also run a Markdown link check if available. If no docs checker exists and adding one would broaden the PR, create a follow-up issue instead.
 
 ## Packaging Check
@@ -43,7 +45,7 @@ Release notes should include:
 - adapter compatibility
 - DeepWiki refresh checklist
 
-The v0.1.0-beta.6 release notes live in [CHANGELOG.md](../../CHANGELOG.md).
+The v0.1.0-beta.8 release notes live in [CHANGELOG.md](../../CHANGELOG.md).
 
 ## Rollback
 

package/docs/reference/VALIDATION.md

@@ -19,6 +19,20 @@ bun run check
 
 Security audit behavior distinguishes blocking high/critical vulnerabilities from lower-severity warnings.
 
+## Canonical Validation Resource Budget
+
+In a Forge source checkout, run the receipt-producing command from a clean, committed worktree:
+
+```bash
+forge validate --shards 2
+```
+
+`--shards N` accepts a positive integer resource budget for the full-suite scheduler. Unit workers cost one unit; on Windows, subprocess and exclusive workers cost two. An explicit budget below a required worker's cost fails before test workers start. Omitting the flag selects an automatic budget, which may increase to the minimum needed to run every lane. Output records the requested and effective budget, or the requested and minimum budget on rejection.
+
+These weights govern Forge's lane workers; they do not impose an operating-system limit on every process a test may create. The budget changes scheduling, not required test coverage or deadlines. Consumer repositories cannot use this flag because their test commands do not implement Forge's scheduler contract.
+
+A successful full validation can be reused by the next unchanged `forge push` under the existing receipt checks. Changing the source or validation inputs requires fresh evidence.
+
 ## Supporting Commands
 
 ```bash

package/docs/reference/github-accounts.md

@@ -28,74 +28,123 @@ from that session before interactive login; do not print their values.
 Inside the work clone:
 
 ```sh
-forge github use WORK_LOGIN
+forge github use WORK_LOGIN --auto
 forge github status
-forge github run -- codex
+codex
 ```
 
 Inside the personal clone, in another terminal:
 
 ```sh
-forge github use PERSONAL_LOGIN
+forge github use PERSONAL_LOGIN --auto
 forge github status
-forge github run -- t3
+t3
 ```
 
 Replace the uppercase labels with your GitHub logins. Both sessions can remain
 open together. Substitute any installed, trusted CLI harness or shell for `codex`
 or `t3`, such as `claude`, `pwsh`, or `bash`.
 
-`use` verifies the named stored account and repository access, then writes only
-`git config --local github.account`. It does not log in, switch the globally
-active account, or modify another clone. Linked Git worktrees normally share this
-clone-local configuration; use separate clones when you need separate bindings.
-
-Supported GitHub-dependent Forge commands use the binding automatically. To give
-the same identity to a harness's own `gh` calls, start that harness with
-`forge github run --`. Already-running terminals and harnesses are not changed.
-
-The launcher deliberately gives its child GitHub authority through transient
-environment variables. Only launch programs you trust with that account. Forge
-does not persist the token, but the launched program can access it. Harnesses or
-tools using their own credentials instead of the inherited `gh` environment are
-outside this guarantee.
+`use --auto` verifies the named stored account and repository access, installs a
+marked router beside the current Forge launcher, then writes only clone-local Git
+settings: the account selector, an automatic-routing marker, and an absolute
+GitHub HTTPS credential-helper route. It refuses to overwrite a non-Forge `gh`
+launcher in that directory. It does not store a credential, log in, switch the
+globally active account, or modify another clone. Linked Git
+worktrees normally share this clone-local configuration; use separate clones when
+you need separate bindings. The machine-local clone registration is durable before
+automatic routing is enabled; disabling routing removes the clone setting before
+its registry entry. If either ordering step cannot complete, automatic routing
+stays disabled or fails closed.
+
+The opt-in `gh` router reads the clone marker on each invocation. In an enabled
+clone it selects the named account for the real GitHub CLI process; elsewhere it
+passes through unchanged. Zero-argument, help, completion, configuration, and
+other local-only `gh` operations also bypass account resolution. The complete
+`gh auth` namespace always passes through so login and recovery remain native.
+Network-capable built-in commands, configured aliases, and installed extensions
+inherit the selected child account; they do not trigger per-command account
+discovery. Built-in destinations from command arguments, URLs, `GH_HOST`,
+`GH_REPO`, and repository inference are checked for conflicts and public-host
+support before a credential is injected. Arbitrary code inside a user-installed
+alias or extension is outside Forge's wrong-destination guarantee. HTTPS Git uses
+the same account through the clone-local helper. SSH key selection remains
+controlled by SSH configuration.
+Enablement stops if another `gh` resolves before Forge on `PATH`, instead of
+claiming automatic routing when the router cannot run. Run automatic setup from
+an installed Forge command; transient `npx`/`bunx` package-runner shims are ignored.
+
+Repositories can therefore be opened normally in T3 Code, VS Code, terminals,
+Codex, or Claude Code. Shell-based `gh` and HTTPS Git commands started with that
+clone as their working directory route automatically when the application PATH
+resolves Forge's router first. Start a new terminal or application after changing
+PATH order; POSIX shells may also need `hash -r`. A program that invokes an
+absolute `gh` executable or bypasses shell command resolution cannot be
+intercepted and must use `forge github run -- PROGRAM` or its own account setting.
+
+`forge github use LOGIN` without `--auto` preserves the original explicit mode.
+Supported Forge routes use the binding, and arbitrary trusted children can still
+be launched with `forge github run -- PROGRAM`.
 
 ## Check or undo
 
 ```sh
 forge github status --json
+forge github auto --disable
 forge github unset
+forge github router --uninstall --force
 ```
 
 Status reports the selected and verified login, clone-local binding source,
-effective Git author, origin transport, helper classification, and repository
+router reachability, effective Git author, origin transport, helper classification, and repository
 access. It does not print tokens, raw remote URLs, or raw credential-helper
 commands. Treat author and account labels as personal information when sharing
 diagnostics.
 
-`unset` is safe to repeat. It removes only the clone binding, not either stored
-login. It does not revoke authority from a running child: close that session and
-start a new one after changing or removing a binding.
+`auto --disable` removes only Forge-owned transparent routing and keeps the clone
+binding. `unset` is safe to repeat and removes both the binding and Forge-owned
+routing. Forge records only canonical clone and Git common-directory paths in a
+machine-local registry under the router lock; it stores no credentials. Current
+enabled state comes from each clone's live `github.auto` value, and router
+ownership comes from the launcher marker. Missing or corrupt registry state, an
+enabled clone absent from the registry, or an unavailable registered clone fails
+closed and leaves the shared router in place. The shared router remains while
+another clone uses it and passes through unchanged outside enabled clones. When
+`router --uninstall --force` runs, Forge prunes only entries it can prove are
+disabled and refuses to remove marked router files while any verified clone
+remains. None of these commands removes a
+stored login or revokes authority from a running child: close that process after
+changing or removing a binding.
+
+The safe order is: disable or unset every opted-in clone, run
+`router --uninstall --force` last, then uninstall Forge itself. Package managers
+cannot clean clone-local Git configuration after the executable is gone. If that
+order was missed, reinstall Forge and run `forge github auto --disable` or
+`forge github unset`; these commands remove only Forge-owned configuration. Do not
+use `git config --unset-all` because another local HTTPS helper may share the same
+key.
 
 ## Three separate identities
 
 | Identity | Controlled by |
 | --- | --- |
-| GitHub API account used by supported Forge routes | Clone-local `github.account` |
+| GitHub API account used by Forge and automatic `gh` routes | Clone-local `github.account` + `github.auto` |
 | Commit author | Git `user.name` and `user.email` |
 | Fetch/push authentication | SSH configuration or the HTTPS credential helper |
 
-Forge does not change your author, origin, SSH keys, or credential helper.
+Forge does not change your author, origin, or SSH keys. Automatic mode owns only
+the clone-local GitHub HTTPS helper it installs and refuses to replace another
+clone-local helper.
 Existing SSH keys and host aliases remain valid; custom aliases must resolve to
-`github.com` for Forge's repository-access check. HTTPS and SSH GitHub.com origins
-are supported; insecure HTTP/Git transports and Enterprise hosts are not V1 targets.
-
-HTTPS has one important coupling: if Git uses `gh auth git-credential` as its
-helper, Git commands inside the explicitly launched session may use that session's
-selected token too. Other HTTPS helpers and SSH key selection remain independent.
-For native multi-account transport, keep separate SSH keys/aliases or configure
-your HTTPS credential manager to distinguish repository URLs (`useHttpPath`).
-These are optional Git choices, not Forge setup steps; see
+`github.com` for Forge's repository-access check. V1 automatic routing supports
+public `github.com` only. An explicit non-public `--hostname` or remote host fails
+closed before the selected public credential is injected; GitHub Enterprise
+routing remains native and outside this feature. HTTPS and SSH GitHub.com origins
+are supported; insecure HTTP/Git transports are not V1 targets.
+
+Automatic mode routes canonical GitHub HTTPS remotes through the selected native
+GitHub CLI account. SSH key selection remains independent; keep separate SSH
+keys/aliases when using SSH. See
 [GitHub's multi-account transport guide](https://docs.github.com/en/account-and-profile/how-tos/account-management/managing-multiple-accounts).
 
 ## Platforms and recovery
@@ -119,16 +168,43 @@ and `--path`. Git Bash is still required for Forge's existing Windows Bash helpe
 - **Unsupported GitHub CLI:** upgrade `gh` to a version supporting named-account
   token retrieval. Unbound projects do not need that capability.
 - **Program not found:** install the harness and check its executable name/PATH.
-
-The supported workflow entrypoints are `forge`, `forge-workflow`, and the compiled
-Forge executable. Direct developer invocation of `node bin/forge-cmd.js` is an
+- **Router conflict:** another `gh` launcher already exists beside Forge. Forge
+  leaves it untouched; move or remove it deliberately before retrying.
+- **Router shadowed:** put Forge's launcher directory before the native GitHub CLI
+  directory on PATH, restart the application, and rerun `use --auto`.
+- **Explicit repository override:** `gh -R` and `gh --repo` still use the account
+  bound to the current working clone; run them from the clone whose identity you intend.
+- **Configured `gh` alias or extension:** network-capable aliases and extensions inherit
+  the selected clone account. Local-only or account-management commands retain their
+  native bypass rules. Forge cannot guarantee the destination of arbitrary code inside
+  an opaque alias or extension; inspect it yourself if it targets another host.
+
+The supported workflow entrypoints are `forge`, `forge-workflow`, and a compiled
+Forge executable whose directory is on PATH; it installs the router beside itself. Rerun `use --auto`
+after moving a compiled executable or changing Forge installation managers so
+the marked launchers refresh their target. Direct developer invocation of `node bin/forge-cmd.js` is an
 internal legacy utility, not an account-isolated V1 entrypoint.
 
+## Performance and installed-product acceptance
+
+Automatic routing is designed to be warm and local on the common path. Release
+acceptance measures the added latency over at least five warm runs, excluding the
+native command itself: a median of at most 250 ms for unbound or local-only
+routing, 1,000 ms for a bound `gh` route before native command work, and 1,000 ms
+for credential-helper resolution. These are acceptance targets, not a promise
+about a slow machine or the remote GitHub operation.
+
+The installed-product acceptance run must exercise the generated PATH launchers
+and the real Forge router, proxy, and credential-helper chain in two concurrent
+clone-local contexts, plus unbound and fail-closed cases. The native `gh` process
+may be substituted only at that process boundary; Forge itself is not substituted.
+The release run uses two securely stored accounts and never prints their tokens.
+
 ## CuraPod adoption
 
 Only after this Forge feature is merged, the merged build is installed, and its
 acceptance checks pass: open each intended CuraPod clone, run
-`forge github use WORK_LOGIN`, verify `forge github status`, then launch the
-chosen harness with `forge github run --`. Keep personal clones separately bound
+`forge github use WORK_LOGIN --auto`, verify `forge github status`, then open the
+chosen harness normally. Keep personal clones separately bound
 to `PERSONAL_LOGIN`. This example does not discover or modify existing CuraPod
 repositories, remotes, keys, or accounts automatically.

package/lib/bun-workflow-pins.js

@@ -19,7 +19,6 @@ const BUN_WORKFLOW_SPECS = Object.freeze([
 	{ path: '.github/workflows/pr-monitor.yml', key: 'bun-version', count: 1 },
 	{ path: '.github/workflows/required-checks-bypass.yml', key: 'bun-version', count: 1 },
 	{ path: '.github/workflows/size-check.yml', key: 'bun-version', count: 1 },
-	{ path: '.github/workflows/test.yml', key: 'bun-version', count: 8 },
 	{ path: '.github/workflows/yaml-lint.yml', key: 'bun-version', count: 1 },
 ].map(Object.freeze));
 
@@ -128,6 +127,76 @@ function readSourcePackageManifest(projectRoot, sourceHead, execGit = secureExec
 	return Buffer.from(execGit('git', ['show', `${sourceHead}:package.json`], { ...options, encoding: 'buffer' }));
 }
 
+function parseRegularEntries(raw, expectedPaths, pattern, errorForPath) {
+	const entries = new Map();
+	for (const line of raw.trim().split(/\r?\n/).filter(Boolean)) {
+		const match = pattern.exec(line);
+		if (match) entries.set(match[2], match[1]);
+	}
+	for (const filePath of expectedPaths) {
+		if (!entries.has(filePath)) throw new Error(errorForPath(filePath));
+	}
+	return entries;
+}
+
+function readBlobBatch(projectRoot, objectIds, execGit) {
+	const output = Buffer.from(execGit('git', ['cat-file', '--batch'], {
+		cwd: projectRoot,
+		encoding: 'buffer',
+		input: Buffer.from(`${objectIds.join('\n')}\n`),
+		stdio: ['pipe', 'pipe', 'pipe'],
+		windowsHide: true,
+	}));
+	const blobs = [];
+	let offset = 0;
+	for (const expectedId of objectIds) {
+		const headerEnd = output.indexOf(0x0a, offset);
+		if (headerEnd < 0) throw new Error(`Git did not return blob metadata for ${expectedId}.`);
+		const match = /^([0-9a-f]+) blob (\d+)$/.exec(output.subarray(offset, headerEnd).toString('utf8'));
+		if (!match || match[1] !== expectedId) throw new Error(`Git did not return the expected blob ${expectedId}.`);
+		const contentStart = headerEnd + 1;
+		const contentEnd = contentStart + Number(match[2]);
+		if (contentEnd >= output.length || output[contentEnd] !== 0x0a) {
+			throw new Error(`Git returned an incomplete blob ${expectedId}.`);
+		}
+		blobs.push(Buffer.from(output.subarray(contentStart, contentEnd)));
+		offset = contentEnd + 1;
+	}
+	if (offset !== output.length) throw new Error('Git returned unexpected extra blob data.');
+	return blobs;
+}
+
+function readCompleteBunPinBatch(projectRoot, sourceHead, extraIndexedPaths = [], execGit = secureExecFileSync) {
+	const sourcePaths = ['package.json', ...BUN_WORKFLOW_SPECS.map(spec => spec.path)];
+	const indexedPaths = [...sourcePaths, ...extraIndexedPaths];
+	const options = {
+		cwd: projectRoot,
+		encoding: 'utf8',
+		stdio: ['ignore', 'pipe', 'pipe'],
+		windowsHide: true,
+	};
+	const sourceEntries = parseRegularEntries(
+		execGit('git', ['ls-tree', sourceHead, '--', ...sourcePaths], options),
+		sourcePaths,
+		/^100(?:644|755) blob ([0-9a-f]+)\t(.+)$/,
+		filePath => filePath === 'package.json'
+			? `package.json is not a regular file at ${sourceHead}.`
+			: `${filePath} is not a regular workflow file at ${sourceHead}.`,
+	);
+	const indexedEntries = parseRegularEntries(
+		execGit('git', ['ls-files', '--stage', '--', ...indexedPaths], options),
+		indexedPaths,
+		/^100(?:644|755) ([0-9a-f]+) 0\t(.+)$/,
+		filePath => `${filePath} is not one regular file in the Git index.`,
+	);
+	const sourceBlobs = readBlobBatch(projectRoot, sourcePaths.map(filePath => sourceEntries.get(filePath)), execGit);
+	const indexedBlobs = readBlobBatch(projectRoot, indexedPaths.map(filePath => indexedEntries.get(filePath)), execGit);
+	return {
+		source: new Map(sourcePaths.map((filePath, index) => [filePath, sourceBlobs[index]])),
+		indexed: new Map(indexedPaths.map((filePath, index) => [filePath, indexedBlobs[index]])),
+	};
+}
+
 function resolveBunVersionTarget(projectRoot, options = {}) {
 	const indexReader = options.readIndexedPackageManifest || readIndexedPackageManifest;
 	const indexed = Buffer.from(indexReader(projectRoot, options.execGit));
@@ -308,16 +377,24 @@ async function applyWorkflowUpdate(projectRoot, update, context) {
 	return { success: true, result: { path: update.path, write, authorization, completion } };
 }
 
+/**
+ * Runs the Bun-pin, npm, and test workflow writers as one recoverable batch bound to the preflight
+ * target and generated test bytes. On failure, earlier writes are restored only while their bytes
+ * still match this batch's output; concurrent changes are preserved and reported as unrecovered.
+ */
 async function updateBunWorkflowPins(projectRoot, options = {}) {
 	const npmWorkflow = require('./npm-publish-workflow');
+	const testWorkflow = require('./test-workflow');
 	const { verifyExpectedHead } = npmWorkflow;
 	const head = verifyExpectedHead(projectRoot, options.expectedHead, options.resolveHead);
 	if (!head.success) return head;
 	const sourceHead = head.sourceHead;
-	const actor = options.actor || options.env?.FORGE_ACTOR || process.env.FORGE_ACTOR || process.env.USER || process.env.USERNAME || 'forge-release';
+	const env = options.env || process.env;
+	const actor = options.actor || env.FORGE_PROTECTED_STATE_ACTOR || env.FORGE_ACTOR || env.USER || env.USERNAME || 'unknown';
 
 	let updates;
 	let npmUpdate;
+	let testUpdate;
 	try {
 		const target = resolveBunVersionTarget(projectRoot, options);
 		updates = BUN_WORKFLOW_SPECS.map(spec => {
@@ -371,6 +448,11 @@ async function updateBunWorkflowPins(projectRoot, options = {}) {
 			},
 			recoveryOperation: 'recover_npm_workflow',
 		};
+		testUpdate = (options.resolveTestWorkflowUpdate || testWorkflow.resolveTestWorkflowUpdate)(
+			projectRoot,
+			sourceHead,
+			options,
+		);
 	} catch (error) {
 		return { success: false, error: error.message };
 	}
@@ -437,12 +519,55 @@ async function updateBunWorkflowPins(projectRoot, options = {}) {
 		return failedUpdate(npm.error, results, attempts, authorizations, projectRoot, context, { npm });
 	}
 
+	const testAuthorization = {
+		actor,
+		path: testWorkflow.TEST_WORKFLOW_PATH,
+		sourceHead,
+		capabilityId: context.createCapabilityId(),
+	};
+	authorizations.push(testAuthorization);
+	attempts.push({
+		...testUpdate,
+		original: testUpdate.snapshot,
+		writeOptions: {
+			actor,
+			operation: 'generate_test_workflow',
+			viaForgeApi: true,
+			surface: 'workflows',
+		},
+		recoveryOperation: 'recover_test_workflow',
+	});
+	const testGenerator = options.generateTestWorkflow || testWorkflow.generateTestWorkflow;
+	let testWorkflowResult;
+	try {
+		testWorkflowResult = await testGenerator(projectRoot, {
+			actor,
+			env: options.env,
+			kernelDeps: options.kernelDeps,
+			expectedHead: sourceHead,
+			resolveHead: options.resolveHead,
+			capabilityId: testAuthorization.capabilityId,
+			createCapabilityId: () => testAuthorization.capabilityId,
+			expectedSnapshot: testUpdate.snapshot,
+			expectedUpdate: { version: testUpdate.version, content: testUpdate.content },
+		});
+	} catch (error) {
+		return failedUpdate(error.message, results, attempts, authorizations, projectRoot, context, { npm });
+	}
+	if (!testWorkflowResult.success) {
+		return failedUpdate(testWorkflowResult.error, results, attempts, authorizations, projectRoot, context, {
+			npm,
+			testWorkflow: testWorkflowResult,
+		});
+	}
+
 	return {
 		success: true,
 		version: updates[0].version,
-		paths: [...results.map(result => result.path), npm.path],
+		paths: [...results.map(result => result.path), npm.path, testWorkflowResult.path],
 		results,
 		npm,
+		testWorkflow: testWorkflowResult,
 	};
 }
 
@@ -454,6 +579,7 @@ module.exports = {
 	readIndexedWorkflow,
 	readIndexedPackageManifest,
 	readSourcePackageManifest,
+	readCompleteBunPinBatch,
 	resolveBunVersionTarget,
 	resolveCurrentHead,
 	deriveBunWorkflowUpdate,