@guiho/runx 0.2.4 → 0.2.6

package/CHANGELOG.md

@@ -15,6 +15,20 @@ owner: runx
 
 # Changelog
 
+## 0.2.6 - 2026-07-14
+
+### Added
+
+- Added Windows CI coverage for replacing a running executable, verifying the
+  installed target version, cleaning the old image, and rolling back failures.
+
+### Fixed
+
+- Fixed `runx upgrade` on Windows so it replaces and verifies `runx.exe` before
+  reporting success instead of returning a detached `scheduled: true` state.
+- Failed Windows replacements now restore the previous executable, report a
+  non-zero error, and clean `.new` and `.old` update files safely.
+
 ## 0.2.4 - 2026-07-14
 
 ### Added

package/DOCS.md

@@ -122,9 +122,11 @@ runx agents install local
 
 `devops/install.ps1` installs Windows assets and `devops/install.sh` installs
 macOS/Linux assets from GitHub Releases into the user's local bin directory.
-`runx upgrade` uses the matching release asset and replaces a native executable;
-on Windows replacement is scheduled after RunX exits. `runx uninstall` removes
-the same native executable and supports `--dry-run`.
+`runx upgrade` uses the matching release asset and replaces a native executable.
+On Windows it renames the running executable, installs and verifies the target
+version at the original path, and restores the previous executable if replacement
+fails. Only cleanup of the renamed old image is deferred until RunX exits.
+`runx uninstall` removes the same native executable and supports `--dry-run`.
 
 When the latest GitHub Release matches the installed version, `runx upgrade` prints `Already up to date.` and exits successfully without downloading or scheduling executable replacement. JSON output reports `upToDate: true`.
 

package/docs/decisions/decisions.xdocs.md

@@ -6,16 +6,22 @@ children: []
 files:
   alpha-boundaries.md: Captures accepted alpha scope, safety, distribution, and compatibility decisions.
   citty-cli-migration.md: Defines the accepted full migration from handwritten parsing and routing to Citty.
+  mirror-automatic-push.md: Defines automatic Mirror release pushes with a synchronized protected-main gate.
   npm-trusted-publishing.md: Defines the accepted npm OIDC publishing workflow and protected-branch patch-release trial.
+  windows-self-upgrade.md: Defines synchronous Windows executable replacement, verification, rollback, and cleanup.
 documents:
   alpha-boundaries.md: Decision record for RunX alpha boundaries.
   citty-cli-migration.md: Decision record for the complete Citty CLI parser and router migration.
+  mirror-automatic-push.md: Accepted release-policy decision for Mirror push=true and protected delivery ordering.
   npm-trusted-publishing.md: Decision record for GitHub Actions npm trusted publishing and the first automated patch release.
+  windows-self-upgrade.md: Accepted design for synchronous and recoverable Windows native self-upgrade.
 tags:
   - decisions
 keywords:
   - runx
   - decisions
+  - mirror push
+  - windows self-upgrade
 flags: []
 status: stable
 ---

package/docs/decisions/mirror-automatic-push.md

@@ -0,0 +1,84 @@
+---
+name: RunX Mirror Automatic Release Push
+purpose: Record the accepted policy that Mirror pushes RunX release commits and tags automatically.
+description: Defines push=true, the synchronized-main precondition, protected GitHub delivery, failure behavior, and rollback boundary.
+created: 2026-07-14
+flags:
+  - accepted
+tags:
+  - decisions
+  - release
+  - mirror
+keywords:
+  - runx
+  - mirror push
+  - protected main
+  - release tags
+owner: runx-decisions
+---
+
+# RunX Mirror Automatic Release Push
+
+## Status
+
+Accepted by the repository owner on 2026-07-14.
+
+## Context
+
+RunX previously configured Mirror with `push = false`. Each release applied the
+version commit and tag locally, then required separate branch delivery and tag
+push commands. The owner wants RunX to match the automatic Mirror release flow
+used by the related GUIHO repositories.
+
+RunX also protects `main` and `@guiho/runx@*` tags. Automatic pushing must not
+allow a release tag to reference a commit that has not reached protected
+`main`.
+
+## Decision
+
+- Set `[git].push = true` in `mirror.config.toml`.
+- Run future `mirror version apply` operations only from a clean, synchronized
+  local `main` whose HEAD equals `origin/main`.
+- Complete implementation changes through protected pull requests before
+  applying Mirror.
+- Treat `mirror version apply` as the single release mutation that writes the
+  version, commits, tags, and pushes the configured refs.
+- Keep package publication behind the GitHub `production` environment approval
+  and npm OIDC trusted publishing.
+
+## Alternatives Considered
+
+- Keep `push = false`: rejected because it preserves the manual release step the
+  owner explicitly asked to remove.
+- Pass `--push` per release: rejected because it makes release behavior depend
+  on operator memory instead of repository configuration.
+- Apply Mirror on a release branch and merge later: rejected because the tag
+  could publish a commit before that commit is part of protected `main`.
+
+## Consequences
+
+- Successful Mirror applies will immediately push release refs and can trigger
+  the public Publish workflow.
+- Operators must treat `mirror version apply` as an externally visible release,
+  not a local preparation step.
+- The synchronized-main gate becomes mandatory; failures stop before apply.
+- Existing GitHub rulesets, environment review, and OIDC remain the enforcement
+  layers for branch, tag, and package publication.
+
+## Reversal Or Revisit Conditions
+
+Return to `push = false` if Mirror cannot push through repository protections
+reliably, if releases need a separate staging phase, or if automatic tag
+publication creates unacceptable operational risk.
+
+## Follow-up Work
+
+- Update repository instructions and XDocs metadata.
+- Validate resolved Mirror configuration and a read-only patch plan.
+- Deliver the configuration through protected `main` without applying another
+  release.
+
+## References
+
+- [Citty CLI Migration Plan](../plans/citty-cli-migration.md)
+- [npm Trusted Publishing Decision](npm-trusted-publishing.md)

package/docs/decisions/windows-self-upgrade.md

@@ -0,0 +1,98 @@
+---
+name: RunX Windows Self-Upgrade
+purpose: Define synchronous and recoverable replacement of the running RunX executable on Windows.
+description: Records the accepted Windows executable-swap, verification, rollback, cleanup, testing, and patch-release behavior.
+created: 2026-07-14
+flags:
+  - accepted
+  - implemented
+tags:
+  - decisions
+  - cli
+  - windows
+keywords:
+  - runx upgrade
+  - windows self-upgrade
+  - executable replacement
+  - rollback
+owner: runx-decisions
+---
+
+# RunX Windows Self-Upgrade
+
+## Context
+
+RunX 0.2.5 downloads a Windows update to `runx.exe.new`, starts a detached
+`cmd.exe` process, reports `scheduled: true`, and exits without confirming that
+the installed executable was replaced. The detached move can fail silently and
+leave later invocations on the previous version.
+
+Windows permits the running executable to be renamed while its image remains
+mapped. A new executable can then be installed at the original path before the
+current RunX process exits. Only deletion of the renamed, still-running image
+must wait until the process releases it.
+
+## Decision
+
+`runx upgrade` on Windows will complete the executable swap synchronously:
+
+1. Download the selected release asset to `runx.exe.new`.
+2. Remove any stale backup that is not in use.
+3. Rename the installed `runx.exe` to `runx.exe.old`.
+4. Rename `runx.exe.new` to the canonical installed path.
+5. Execute the newly installed path with `--version` and require the expected
+   target version and a zero exit code.
+6. If installation or verification fails, remove the failed replacement and
+   restore `runx.exe.old` to the canonical path.
+7. After successful verification, delete the backup immediately when possible;
+   when Windows still locks the running image, schedule only that backup cleanup
+   for after the current process exits.
+
+The upgrade result reports `scheduled: false`. Deferred deletion of the old,
+renamed image is cleanup and does not defer or weaken successful replacement.
+
+## Error Handling
+
+- A replacement failure must throw a concise `RunXError` and produce a non-zero
+  CLI exit code.
+- Rollback must be attempted whenever the installed executable was renamed but
+  the new executable was not verified.
+- If rollback also fails, the error must report both the replacement and
+  recovery failures and identify the affected installed path.
+- The `.new` file must be removed after failures and must not remain after a
+  successful rename.
+- A locked stale `.old` file must stop a new upgrade before the current
+  executable is modified.
+
+## Testing
+
+Automated coverage must prove that:
+
+- the configured Windows self path contains the downloaded replacement before
+  `upgradeSelf()` resolves;
+- successful Windows upgrades report `scheduled: false`;
+- no `.new` file remains after success;
+- a failed replacement restores the original executable;
+- the equal-version no-op remains unchanged;
+- `runx -h` continues to work outside a manifest directory.
+
+The full release gate is `bun run typecheck`, `bun test`, `bun run build`,
+`bun run binary`, `bun run binaries`, and strict XDocs validation.
+
+## Release
+
+After implementation and validation, use Mirror to plan and apply the next
+patch. Update the changelog before applying the Mirror-managed version. Do not
+hand-edit the package version or create the release tag manually.
+
+## Acceptance Criteria
+
+- When `runx upgrade` succeeds, the executable at the installed path is already
+  the target release.
+- A same-terminal or new-terminal invocation immediately reports the target
+  version.
+- The command never reports `scheduled: true` for upgrade replacement.
+- Replacement and verification failures are visible and recover the old binary.
+- Temporary update files are cleaned up safely.
+- Issue #9 has automated Windows regression coverage and issue #1 remains
+  covered by the Citty help tests.

package/docs/plans/mirror-automatic-push.md

@@ -0,0 +1,77 @@
+---
+name: RunX Mirror Automatic Push Plan
+purpose: Execute the accepted push=true release policy through protected main without creating another release.
+description: Sequences configuration, safety instructions, XDocs validation, protected delivery, and post-merge verification.
+created: 2026-07-14
+flags:
+  - approved
+tags:
+  - plans
+  - release
+  - mirror
+keywords:
+  - runx
+  - mirror push
+  - protected main
+  - configuration
+owner: runx-plans
+---
+
+# RunX Mirror Automatic Push Plan
+
+## Source Decision
+
+- [RunX Mirror Automatic Release Push](../decisions/mirror-automatic-push.md)
+
+## Unit 1: Configure And Document Automatic Push
+
+- Goal: Make automatic release pushing a repository-owned Mirror policy.
+- Owner: RunX repository.
+- Dependencies: Accepted automatic-push decision; `0.2.4` already applied and
+  pushed, so this change must not apply another version.
+- Files:
+  - `mirror.config.toml`
+  - `AGENTS.md`
+  - `runx.xdocs.md`
+- Data, auth, and cache: No application data, authentication, authorization, or
+  cache impact. GitHub credentials and rulesets remain external.
+- Changes:
+  - Set `[git].push = true`.
+  - Require clean synchronized `main` before `mirror version apply`.
+  - Document that apply is an externally visible release mutation.
+- Checks:
+  - `mirror config check`
+  - `mirror config show`
+  - `mirror version plan patch --format json`
+  - Verify the plan reports `pushEnabled: true` and next patch `0.2.5` without
+    applying it.
+  - Strict root XDocs metadata and doctor checks.
+- Acceptance: The resolved config enables push; safety guidance prevents apply
+  from a feature branch or stale main; no version, commit, or tag is created by
+  validation.
+- Stop conditions: Stop if Mirror cannot load the config, the read-only plan
+  mutates state, or the worktree contains unrelated changes.
+
+## Unit 2: Deliver Through Protected Main
+
+- Goal: Merge the configuration policy without bypassing required CI.
+- Dependencies: Unit 1 complete and committed.
+- Delivery:
+  - Push `codex/mirror-auto-push`.
+  - Open a ready pull request to `main`.
+  - Wait for required CI and merge through the repository ruleset.
+  - Synchronize local `main` and confirm `mirror config show` reports
+    `push: true`.
+- Acceptance: `origin/main` owns the configuration and instructions; no new
+  release tag was created.
+- Stop conditions: Stop on CI failure, unresolved protection failure, or an
+  unexpected version/tag mutation.
+
+## TODO Alignment
+
+This is a bounded owner-approved configuration change completed in one session;
+it does not require a separate TODO entry.
+
+## First Executable Unit
+
+Unit 1: set and document the resolved Mirror automatic-push policy.

package/docs/plans/plans.xdocs.md

@@ -6,17 +6,23 @@ children: []
 files:
   alpha-implementation.md: Breaks the accepted alpha into implementation and validation units.
   citty-cli-migration.md: Executes the full Citty command-tree migration, compatibility validation, protected delivery, and patch release.
+  mirror-automatic-push.md: Enables automatic Mirror release pushes with a synchronized protected-main safety gate.
   npm-trusted-publishing-release.md: Sequences workflow implementation, protected delivery, Mirror patching, and public trusted-publishing verification.
+  windows-self-upgrade.md: Sequences synchronous Windows replacement, rollback coverage, validation, issue closure, and patch delivery.
 documents:
   alpha-implementation.md: Plan used for the initial RunX implementation.
   citty-cli-migration.md: Active plan for replacing handwritten CLI parsing and routing with Citty and delivering its patch release.
+  mirror-automatic-push.md: Approved plan for configuring, validating, and merging Mirror push=true without applying another release.
   npm-trusted-publishing-release.md: Approved executable plan for the RunX 0.2.1 trusted-publishing release trial.
+  windows-self-upgrade.md: Approved executable plan for fixing Windows native self-upgrade and delivering its patch.
 tags:
   - plans
 keywords:
   - runx
   - implementation
   - citty
+  - mirror push
+  - windows self-upgrade
 flags: []
 status: stable
 ---

package/docs/plans/windows-self-upgrade.md

@@ -0,0 +1,129 @@
+---
+name: RunX Windows Self-Upgrade Plan
+purpose: Execute the accepted synchronous and recoverable Windows self-upgrade design.
+description: Sequences executable replacement, regression coverage, documentation, validation, issue closure, and the next Mirror patch.
+created: 2026-07-14
+flags:
+  - approved
+  - executed
+tags:
+  - plans
+  - cli
+  - windows
+keywords:
+  - runx upgrade
+  - executable replacement
+  - rollback
+  - patch release
+owner: runx-plans
+---
+
+# RunX Windows Self-Upgrade Plan
+
+## Sources
+
+- [Windows Self-Upgrade Decision](../decisions/windows-self-upgrade.md)
+- [Alpha Command Catalog Requirements](../requirements/alpha-command-catalog.md)
+- [CLI Architecture](../architecture/cli-architecture.md)
+- GitHub issues `CGuiho/runx#9` and `CGuiho/runx#1`
+
+## Unit 1: Replace the Windows Executable Synchronously
+
+- Goal: Make `upgradeSelf()` return successfully only after the canonical
+  Windows executable path contains and runs the target release.
+- Owner: `C:\GUIHO\runx`.
+- Dependencies: Accepted Windows self-upgrade decision.
+- Files:
+  - `source/self-management.ts`
+  - `source/types.ts` only if the result contract must change
+- Behavior:
+  - Download to `.new`, rename the installed executable to `.old`, install the
+    new file at the original path, and verify `<self-path> --version`.
+  - Return `scheduled: false` after verified replacement.
+  - On failure, remove the failed target, restore `.old`, remove `.new`, and
+    return a non-zero `RunXError` with recovery context.
+  - Delete `.old` immediately when possible; defer only deletion of the locked
+    old image after the current process exits.
+- Data/schema, auth, permissions, and cache: No application data, schema,
+  authentication, authorization, or cache impact. Filesystem write permission
+  to the installed executable remains required.
+- Acceptance: The installed path is the verified target before
+  `upgradeSelf()` resolves and no `.new` file remains.
+- Stop conditions: Stop if Windows cannot rename the running executable, the
+  target cannot be verified, rollback cannot restore the installed path, or
+  unrelated self-management behavior changes.
+
+## Unit 2: Add Regression Coverage
+
+- Goal: Prove the fixed upgrade contract and preserve the already-correct help
+  behavior from issue #1.
+- Dependencies: Unit 1 complete.
+- Files:
+  - `source/guiho-runx.spec.ts` or a focused colocated self-management spec
+  - existing `source/cli.spec.ts` only if help coverage needs correction
+- Checks:
+  - Mock the GitHub latest-release response and downloaded Windows binary.
+  - Configure `RUNX_SELF_PATH` to an isolated executable path.
+  - Assert the replacement exists at that path before the promise resolves,
+    reports `scheduled: false`, runs as the expected version, and leaves no
+    `.new` file.
+  - Force verification failure and assert restoration of the original file.
+  - Run the existing `-h`/`--help` tests outside a manifest directory.
+- Acceptance: Windows CI exercises success and rollback; issue #1 remains
+  covered without changing its implemented behavior.
+- Stop conditions: Stop on nondeterministic process cleanup, leaked test
+  processes, platform-dependent assertions on non-Windows runners, or failure
+  to restore global fetch/environment state.
+
+## Unit 3: Align Documentation and Validate
+
+- Goal: Make public and structured documentation describe completed rather than
+  scheduled Windows replacement, then pass the full release gate.
+- Dependencies: Units 1 and 2 complete.
+- Files:
+  - `DOCS.md`
+  - `source/source.xdocs.md`
+  - `runx.xdocs.md`
+  - accepted decision and plan lifecycle flags when implementation completes
+- Checks:
+  - `bun run typecheck`
+  - `bun test`
+  - `bun run build`
+  - `bun run binary`
+  - `bun run binaries`
+  - `xdocs meta . --documents --strict --owner runx --format json`
+  - `xdocs doctor . --warnings-as-errors --format json`
+  - `git diff --check`
+- Acceptance: All checks pass, docs agree with behavior, and the worktree
+  contains only understood task changes.
+- Stop conditions: Stop on any failed validation or unexpected worktree change.
+
+## Unit 4: Close Issues and Apply the Patch
+
+- Goal: Close both resolved GitHub issues and publish the next
+  Mirror-managed patch state.
+- Dependencies: Unit 3 committed and the worktree clean.
+- Sequence:
+  - Confirm issue #9 acceptance evidence and issue #1 Citty regression evidence.
+  - Close issues #9 and #1 with concise resolution comments.
+  - Run `mirror config show` and `mirror version plan patch`.
+  - Update the configured changelog with the planned next version and commit
+    release preparation.
+  - Run the full typecheck/test gate again if release preparation changes any
+    executable inputs.
+  - Apply `mirror version apply patch --yes`; allow configured commit/push/tag
+    behavior and do not hand-edit Mirror-managed fields.
+- Acceptance: Both issues are closed, the changelog records the fix, and
+  package version, release commit, tag, and configured remote push agree.
+- Stop conditions: Stop if an issue acceptance criterion is unproved, Mirror
+  plans an unexpected version, validation fails, or protected push is rejected.
+
+## TODO Alignment
+
+This is one approved, focused execution session. No additional durable TODO
+entry or delegated component task is required.
+
+## First Executable Unit
+
+Unit 1: implement synchronous Windows replacement and rollback in
+`source/self-management.ts`.

package/docs/reviews/implementation/implementation.xdocs.md

@@ -5,8 +5,10 @@ parent: runx-reviews
 children: []
 files:
   citty-cli-migration-review.md: Reviews the implemented Citty command tree, compatibility adapter, tests, documentation, packaging, and release readiness.
+  windows-self-upgrade-review.md: Reviews synchronous Windows replacement, rollback, cleanup, tests, CI coverage, and release readiness.
 documents:
   citty-cli-migration-review.md: Accepted implementation review for the full Citty CLI migration.
+  windows-self-upgrade-review.md: Accepted implementation review for the Windows native self-upgrade fix.
 tags:
   - reviews
   - implementation
@@ -14,6 +16,7 @@ keywords:
   - runx
   - citty
   - implementation review
+  - windows self-upgrade
 flags: []
 status: stable
 ---

package/docs/reviews/implementation/windows-self-upgrade-review.md

@@ -0,0 +1,79 @@
+---
+name: RunX Windows Self-Upgrade Implementation Review
+purpose: Review the implemented Windows self-upgrade fix against its accepted decision and plan.
+description: Confirms synchronous replacement, target verification, rollback, cleanup, tests, CI coverage, documentation, and release readiness.
+created: 2026-07-14
+flags:
+  - accepted
+tags:
+  - reviews
+  - implementation
+  - windows
+keywords:
+  - runx upgrade
+  - executable replacement
+  - rollback
+  - windows ci
+owner: runx-implementation-reviews
+---
+
+# RunX Windows Self-Upgrade Implementation Review
+
+## Verdict
+
+Accepted. No blocker, high, medium, or low findings remain.
+
+## Findings
+
+No actionable findings. The implementation matches the approved synchronous
+replacement and recovery design without changing manifest execution, Citty
+routing, uninstall behavior, or non-Windows upgrade behavior.
+
+## Acceptance Criteria
+
+- `upgradeSelf()` renames the running Windows executable, installs the
+  downloaded target at the canonical path, and awaits `<path> --version`.
+- Successful Windows upgrade results report `scheduled: false`.
+- Verification failures remove the invalid replacement and restore `.old`.
+- `.new` is absent after success and rollback.
+- Cleanup retries deletion of the locked `.old` image after the old process
+  releases it.
+- A Windows-only test holds a real copied executable open during replacement,
+  verifies the new binary at the canonical path before completion, and observes
+  backup cleanup.
+- A second Windows test proves rollback after invalid-binary verification.
+- Existing Citty tests continue to prove `-h` and `--help` outside a manifest.
+- The GitHub workflow now runs typecheck, tests, build, and native compilation
+  on `windows-latest` in addition to the existing Linux release-matrix gate.
+
+## Verification Evidence
+
+- `bun run typecheck`: passed.
+- `bun test`: 15 passed, 0 failed, 134 assertions.
+- `bun run build`: passed.
+- `bun run binary`: passed.
+- `bun run binaries`: twelve native assets built and verified.
+- Windows x64 native `-h` outside a manifest: passed.
+- Windows x64 native `--version`: reported `0.2.5` before the release bump.
+- CI workflow YAML parse: passed.
+- `xdocs doctor . --warnings-as-errors --format json`: 0 errors, 0 warnings.
+- `git diff --check`: passed.
+
+## Documentation and TODO
+
+`DOCS.md`, source/root/workflow XDocs descriptors, the accepted decision, plan,
+plan review, this implementation review, and validation evidence are aligned.
+No TODO entry is needed for this completed single-session fix.
+
+## Residual Risk
+
+The new `windows-latest` job cannot execute until the committed workflow reaches
+GitHub. Local Windows coverage exercises the same live-file replacement and
+cleanup behavior. Public upgrade from 0.2.0 to the new patch can only be verified
+after the patch release assets exist.
+
+## References
+
+- [Decision](../../decisions/windows-self-upgrade.md)
+- [Plan](../../plans/windows-self-upgrade.md)
+- [Plan Review](../plans/windows-self-upgrade-review.md)

package/docs/reviews/plans/mirror-automatic-push-review.md

@@ -0,0 +1,57 @@
+---
+name: RunX Mirror Automatic Push Plan Review
+purpose: Verify that the automatic-push configuration plan is safe, bounded, and ready for execution.
+description: Reviews synchronized-main safeguards, read-only validation, protected delivery, and release side effects.
+created: 2026-07-14
+flags:
+  - approved
+tags:
+  - reviews
+  - plans
+  - release
+keywords:
+  - runx
+  - mirror push
+  - plan review
+  - protected main
+owner: runx-plan-reviews
+---
+
+# RunX Mirror Automatic Push Plan Review
+
+## Verdict
+
+Ready for execution.
+
+## Findings
+
+- No blocker or high-severity findings remain.
+- The clean, synchronized `main` precondition is explicit and prevents a
+  release tag from pointing at an unmerged feature or stale commit.
+- Unit 1 uses only read-only Mirror validation and explicitly prohibits another
+  version apply, so the current `0.2.4` release remains unchanged.
+- The plan documents that `push = true` makes every future Mirror apply an
+  externally visible release mutation.
+- No application data, authentication, authorization, or cache behavior is
+  affected. GitHub credentials, rulesets, environment approval, and npm OIDC
+  remain external enforcement layers.
+
+## Delivery Review
+
+- The configuration change must pass the protected pull-request workflow
+  before reaching `main`.
+- Post-merge verification checks the resolved configuration on synchronized
+  `main` and confirms that no `0.2.5` tag was created.
+- A CI failure, protection failure, or unexpected version mutation is an
+  explicit stop condition.
+
+## First Executable Unit
+
+Execute Unit 1 in
+[RunX Mirror Automatic Push Plan](../../plans/mirror-automatic-push.md): set and
+document the resolved automatic-push policy without applying a release.
+
+## References
+
+- [RunX Mirror Automatic Push Plan](../../plans/mirror-automatic-push.md)
+- [RunX Mirror Automatic Release Push](../../decisions/mirror-automatic-push.md)

package/docs/reviews/plans/plans.xdocs.md

@@ -5,10 +5,14 @@ parent: runx-reviews
 children: []
 files:
   citty-cli-migration-review.md: Reviews completeness, compatibility, safety invariants, native packaging, and release sequencing for the Citty migration.
+  mirror-automatic-push-review.md: Reviews synchronized-main safeguards, read-only validation, protected delivery, and release side effects.
   npm-trusted-publishing-release-review.md: Reviews sequencing, acceptance criteria, safety gates, and validation for the RunX 0.2.1 trusted-publishing plan.
+  windows-self-upgrade-review.md: Reviews synchronous replacement, rollback, regression coverage, issue closure, and patch delivery.
 documents:
   citty-cli-migration-review.md: Ready-for-execution review of the full Citty CLI migration plan.
+  mirror-automatic-push-review.md: Ready-for-execution review of the Mirror automatic-push configuration plan.
   npm-trusted-publishing-release-review.md: Ready-for-execution review of the npm trusted-publishing release plan.
+  windows-self-upgrade-review.md: Ready-for-execution review of the Windows native self-upgrade fix plan.
 tags:
   - reviews
   - plans
@@ -16,7 +20,9 @@ keywords:
   - runx
   - plan review
   - citty
+  - mirror push
   - trusted publishing
+  - windows self-upgrade
 flags: []
 status: stable
 ---

package/docs/reviews/plans/windows-self-upgrade-review.md

@@ -0,0 +1,71 @@
+---
+name: RunX Windows Self-Upgrade Plan Review
+purpose: Verify that the Windows self-upgrade plan is safe, complete, and executable.
+description: Reviews replacement sequencing, rollback, tests, documentation, issue closure, and Mirror patch delivery.
+created: 2026-07-14
+flags:
+  - approved
+tags:
+  - reviews
+  - plans
+  - windows
+keywords:
+  - runx upgrade
+  - executable replacement
+  - rollback
+  - mirror patch
+owner: runx-plan-reviews
+---
+
+# RunX Windows Self-Upgrade Plan Review
+
+## Verdict
+
+Ready for execution.
+
+## Findings
+
+No blocker, high, medium, or low findings remain. The plan traces to the accepted
+Windows self-upgrade decision and existing native-upgrade requirement. Each unit
+has a bounded outcome, named files, dependencies, acceptance criteria, checks,
+and explicit stop conditions.
+
+## Sequencing and Failure Safety
+
+- Replacement precedes verification, and successful completion requires the
+  canonical path to execute the expected target version.
+- Rollback occurs before any failure is surfaced after the old executable was
+  renamed.
+- Deferred work is limited to deleting the locked old image; replacement itself
+  is complete before success.
+- Issue closure and Mirror application follow implementation validation and a
+  clean committed worktree.
+- The plan recognizes configured Mirror commit, push, and tag side effects and
+  stops on protected-push rejection.
+
+## Coverage Review
+
+- Success, failure, rollback, temporary-file cleanup, and platform isolation are
+  explicit.
+- Existing `-h` coverage directly supports closing issue #1.
+- Typecheck, unit tests, library build, local binary, the twelve-target matrix,
+  strict XDocs checks, and diff hygiene are included.
+- No route, API, UI, data schema, authentication, authorization, cache, cloud,
+  secret, or database work is in scope.
+
+## TODO and Documentation Alignment
+
+The work is a single focused package session and does not need a long-running
+TODO entry. Public `DOCS.md`, source/root XDocs descriptors, lifecycle records,
+and the changelog are included in the correct sequence.
+
+## First Executable Unit
+
+Implement synchronous replacement, target-version verification, rollback, and
+old-image cleanup in `source/self-management.ts`.
+
+## References
+
+- [Plan](../../plans/windows-self-upgrade.md)
+- [Decision](../../decisions/windows-self-upgrade.md)
+- [CLI Architecture](../../architecture/cli-architecture.md)

package/docs/validation/validation.xdocs.md

@@ -6,10 +6,12 @@ children: []
 files:
   alpha-implementation-summary.md: Records the completed alpha implementation, checks, and release boundaries.
   citty-cli-migration.md: Records the complete local validation gate for the Citty command-tree migration.
+  windows-self-upgrade.md: Records Windows replacement, rollback, cleanup, native build, CI, and XDocs validation evidence.
 documents:
   alpha-implementation-summary.md: Validation summary for the first RunX implementation.
   citty-cli-migration.md: Validation evidence for TypeScript, tests, native assets, npm packaging, CLI behavior, and XDocs.
   npm-trusted-publishing-0.2.2.md: Validation evidence for the blocked 0.2.2 npm trusted-publishing retry.
+  windows-self-upgrade.md: Validation evidence for GitHub issues #9 and #1 and the Windows self-upgrade patch.
 tags:
   - validation
 keywords:
@@ -17,6 +19,7 @@ keywords:
   - citty
   - tests
   - summary
+  - windows self-upgrade
 flags: []
 status: stable
 ---

package/docs/validation/windows-self-upgrade.md

@@ -0,0 +1,85 @@
+---
+name: RunX Windows Self-Upgrade Validation
+purpose: Record verification evidence for the Windows self-upgrade fix and issue closure.
+description: Captures Windows replacement and rollback tests, complete Bun build checks, native CLI checks, CI syntax, XDocs health, and residual release risk.
+created: 2026-07-14
+flags:
+  - validated
+tags:
+  - validation
+  - windows
+  - cli
+keywords:
+  - runx upgrade
+  - windows executable
+  - rollback
+  - issue 9
+  - issue 1
+owner: runx-validation
+---
+
+# RunX Windows Self-Upgrade Validation
+
+## Summary
+
+The implementation is ready for commit, issue closure, and the requested
+Mirror-managed patch. All local checks passed on Windows.
+
+## Scope
+
+- Synchronous Windows replacement of a running native executable.
+- Target-version verification before successful completion.
+- Rollback after invalid replacement verification.
+- Deferred cleanup of the locked old executable only.
+- Existing manifest-free `-h` behavior from issue #1.
+- Windows CI coverage and structured documentation health.
+
+## Commands and Results
+
+| Check | Result | Evidence |
+| --- | --- | --- |
+| `bun run typecheck` | passed | TypeScript completed without diagnostics. |
+| `bun test` | passed | 15 tests, 0 failures, 134 assertions. |
+| `bun run build` | passed | Library output compiled. |
+| `bun run binary` | passed | Local Windows executable compiled. |
+| `bun run binaries` | passed | All twelve release assets built and verified. |
+| Native `runx-windows-x64.exe -h` outside a manifest | passed | Citty usage rendered with exit code 0. |
+| Native `runx-windows-x64.exe --version` | passed | Reported `0.2.5` before the patch bump. |
+| `Bun.YAML.parse(.github/workflows/ci.yml)` | passed | Workflow YAML parsed successfully. |
+| `xdocs meta . --documents --strict --owner runx --format json` | passed | Root metadata and companions valid. |
+| `xdocs doctor . --warnings-as-errors --format json` | passed | 0 errors and 0 warnings. |
+| `git diff --check` | passed | No whitespace errors. |
+
+## Behavioral Evidence
+
+`source/self-management.spec.ts` runs only on Windows for the platform-specific
+cases. Its success case launches a copied PowerShell executable from the
+configured self path, keeps that executable running, upgrades the same path to
+the current Bun executable, and requires the replacement to report the expected
+version before `upgradeSelf()` resolves. It also observes removal of `.new` and
+eventual removal of `.old` after the running process exits.
+
+The rollback case downloads invalid executable bytes, requires verification to
+fail, and confirms that the original bytes are restored with neither `.new` nor
+`.old` left behind.
+
+The existing `source/cli.spec.ts` root-help test proves both `-h` and `--help`
+work without a manifest, satisfying issue #1.
+
+## Skipped or Blocked Checks
+
+- The new GitHub-hosted `windows-latest` job is not locally runnable; it will
+  execute after the commit reaches GitHub.
+- An actual 0.2.0-to-new-patch public upgrade is blocked until the new release
+  assets are published.
+
+## Readiness
+
+Ready for commit, closing GitHub issues #9 and #1, changelog preparation, and
+the requested Mirror patch plan/apply sequence.
+
+## References
+
+- [Implementation Review](../reviews/implementation/windows-self-upgrade-review.md)
+- [Plan](../plans/windows-self-upgrade.md)
+- [Decision](../decisions/windows-self-upgrade.md)

package/library/self-management.d.ts

@@ -1,8 +1,9 @@
 import type { RunXUpgradeResult, UpdateResult } from './types.js';
-export declare const checkForLatestVersion: () => Promise<UpdateResult>;
-export declare const listAvailableVersions: () => Promise<string[]>;
-export declare const upgradeSelf: (dryRun: boolean) => Promise<RunXUpgradeResult>;
-export declare const uninstallSelf: (dryRun: boolean) => Promise<{
+export { checkForLatestVersion, listAvailableVersions, uninstallSelf, upgradeSelf, };
+declare const checkForLatestVersion: () => Promise<UpdateResult>;
+declare const listAvailableVersions: () => Promise<string[]>;
+declare const upgradeSelf: (dryRun: boolean) => Promise<RunXUpgradeResult>;
+declare const uninstallSelf: (dryRun: boolean) => Promise<{
     executablePath: string;
     scheduled: boolean;
     dryRun: boolean;

package/library/self-management.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"self-management.d.ts","sourceRoot":"","sources":["../source/self-management.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAMjE,eAAO,MAAM,qBAAqB,QAAa,OAAO,CAAC,YAAY,CAYlE,CAAA;AAED,eAAO,MAAM,qBAAqB,QAAa,OAAO,CAAC,MAAM,EAAE,CAK9D,CAAA;AAED,eAAO,MAAM,WAAW,WAAkB,OAAO,KAAG,OAAO,CAAC,iBAAiB,CAmB5E,CAAA;AAED,eAAO,MAAM,aAAa,WAAkB,OAAO,KAAG,OAAO,CAAC;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAW5H,CAAA"}
+{"version":3,"file":"self-management.d.ts","sourceRoot":"","sources":["../source/self-management.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEjE,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,aAAa,EACb,WAAW,GACZ,CAAA;AAMD,QAAA,MAAM,qBAAqB,QAAa,OAAO,CAAC,YAAY,CAY3D,CAAA;AAED,QAAA,MAAM,qBAAqB,QAAa,OAAO,CAAC,MAAM,EAAE,CAKvD,CAAA;AAED,QAAA,MAAM,WAAW,WAAkB,OAAO,KAAG,OAAO,CAAC,iBAAiB,CAmBrE,CAAA;AAED,QAAA,MAAM,aAAa,WAAkB,OAAO,KAAG,OAAO,CAAC;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAWrH,CAAA"}

package/library/self-management.js

@@ -1,9 +1,11 @@
+import { Buffer } from 'node:buffer';
 import { chmod, rename, rm } from 'node:fs/promises';
 import { basename } from 'node:path';
 import { RunXError } from './errors.js';
 import { readVersion } from './help.js';
+export { checkForLatestVersion, listAvailableVersions, uninstallSelf, upgradeSelf, };
 const repositoryApi = 'https://api.github.com/repos/CGuiho/runx/releases';
-export const checkForLatestVersion = async () => {
+const checkForLatestVersion = async () => {
     const currentVersion = readVersion();
     try {
         const response = await fetch(`${repositoryApi}/latest`, { headers: { accept: 'application/vnd.github+json' } });
@@ -18,14 +20,14 @@ export const checkForLatestVersion = async () => {
         return { currentVersion, latestVersion: currentVersion, updateAvailable: false };
     }
 };
-export const listAvailableVersions = async () => {
+const listAvailableVersions = async () => {
     const response = await fetch(`${repositoryApi}?per_page=20`, { headers: { accept: 'application/vnd.github+json' } });
     if (!response.ok)
         throw new RunXError(`Could not retrieve RunX releases: HTTP ${response.status}`);
     const releases = await response.json();
     return releases.map((release) => release.tag_name.replace(/^@guiho\/runx@/, '').replace(/^v/, ''));
 };
-export const upgradeSelf = async (dryRun) => {
+const upgradeSelf = async (dryRun) => {
     const executablePath = requireNativeExecutable();
     const update = await checkForLatestVersion();
     const upToDate = !update.updateAvailable && update.latestVersion === update.currentVersion && Boolean(update.url);
@@ -43,10 +45,10 @@ export const upgradeSelf = async (dryRun) => {
         await rename(temporaryPath, executablePath);
         return { ...update, executablePath, scheduled: false, upToDate: false };
     }
-    scheduleWindowsReplacement(temporaryPath, executablePath);
-    return { ...update, executablePath, scheduled: true, upToDate: false };
+    await replaceWindowsExecutable(temporaryPath, executablePath, update.latestVersion);
+    return { ...update, executablePath, scheduled: false, upToDate: false };
 };
-export const uninstallSelf = async (dryRun) => {
+const uninstallSelf = async (dryRun) => {
     const executablePath = requireNativeExecutable();
     if (dryRun)
         return { executablePath, scheduled: false, dryRun: true };
@@ -66,10 +68,65 @@ const requireNativeExecutable = () => {
         throw new RunXError('Self-management requires a native RunX executable installed from a GitHub release.');
     return executablePath;
 };
-const scheduleWindowsReplacement = (temporaryPath, executablePath) => {
-    const command = `ping 127.0.0.1 -n 2 > nul & move /y "${temporaryPath}" "${executablePath}" > nul`;
-    Bun.spawn(['cmd.exe', '/d', '/s', '/c', command], { detached: true, stdout: 'ignore', stderr: 'ignore', stdin: 'ignore' });
+const replaceWindowsExecutable = async (temporaryPath, executablePath, expectedVersion) => {
+    const backupPath = `${executablePath}.old`;
+    let originalMoved = false;
+    try {
+        await rm(backupPath, { force: true });
+        await rename(executablePath, backupPath);
+        originalMoved = true;
+        await rename(temporaryPath, executablePath);
+        await verifyExecutableVersion(executablePath, expectedVersion);
+        await cleanupWindowsBackup(backupPath);
+    }
+    catch (error) {
+        const replacementFailure = errorMessage(error);
+        await rm(temporaryPath, { force: true }).catch(() => undefined);
+        if (!originalMoved) {
+            throw new RunXError(`Could not replace the Windows RunX executable at ${executablePath}: ${replacementFailure}`);
+        }
+        try {
+            await rm(executablePath, { force: true });
+            await rename(backupPath, executablePath);
+        }
+        catch (rollbackError) {
+            throw new RunXError(`Windows RunX upgrade failed at ${executablePath}: ${replacementFailure}. Automatic rollback also failed: ${errorMessage(rollbackError)}`);
+        }
+        throw new RunXError(`Windows RunX upgrade failed; the previous executable was restored at ${executablePath}: ${replacementFailure}`);
+    }
+};
+const verifyExecutableVersion = async (executablePath, expectedVersion) => {
+    const verification = Bun.spawn([executablePath, '--version'], { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' });
+    const [stdout, stderr, exitCode] = await Promise.all([
+        new Response(verification.stdout).text(),
+        new Response(verification.stderr).text(),
+        verification.exited,
+    ]);
+    const actualVersion = stdout.trim();
+    if (exitCode !== 0)
+        throw new Error(`replacement exited with code ${exitCode}${stderr.trim() ? `: ${stderr.trim()}` : ''}`);
+    if (actualVersion !== expectedVersion)
+        throw new Error(`replacement reported version ${actualVersion || '<empty>'}; expected ${expectedVersion}`);
+};
+const cleanupWindowsBackup = async (backupPath) => {
+    try {
+        await rm(backupPath, { force: true });
+    }
+    catch { }
+    scheduleWindowsBackupCleanup(backupPath);
+};
+const scheduleWindowsBackupCleanup = (backupPath) => {
+    const command = 'for ($attempt = 0; $attempt -lt 300; $attempt += 1) { if (-not (Test-Path -LiteralPath $env:RUNX_BACKUP_PATH)) { exit 0 }; try { Remove-Item -LiteralPath $env:RUNX_BACKUP_PATH -Force -ErrorAction Stop; exit 0 } catch { Start-Sleep -Milliseconds 100 } }; exit 1';
+    const encodedCommand = Buffer.from(command, 'utf16le').toString('base64');
+    Bun.spawn(['cmd.exe', '/d', '/s', '/c', `powershell.exe -NoLogo -NoProfile -NonInteractive -WindowStyle Hidden -EncodedCommand ${encodedCommand}`], {
+        detached: true,
+        env: { ...process.env, RUNX_BACKUP_PATH: backupPath },
+        stdout: 'ignore',
+        stderr: 'ignore',
+        stdin: 'ignore',
+    });
 };
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);
 const compareVersions = (left, right) => {
     const parse = (value) => value.split(/[.+-]/).map((part) => Number.parseInt(part, 10) || 0);
     const a = parse(left);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@guiho/runx",
   "description": "A language-agnostic, documented command catalog and local CLI executor.",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "type": "module",
   "main": "./library/guiho-runx.js",
   "types": "./library/guiho-runx.d.ts",