@guiho/runx 0.4.0 → 0.5.1

package/docs/validation/rfc-0034-cli-compliance-migration.md

@@ -10,7 +10,7 @@ tags:
   - cli
 keywords:
   - RFC 0034
-  - 38 tests
+  - 44 tests
   - 14 assets
   - RunX
 owner: runx-validation
@@ -20,31 +20,53 @@ owner: runx-validation
 
 ## Summary
 
-All local RFC completion gates passed. No validation blocker remains.
+All local RFC completion gates passed after independent audit corrections for
+upgrade routing, no-argument cached notices, and names-only prompt output. No
+validation blocker remains.
 
 ## Commands Run
 
 | Command or check | Result |
 | --- | --- |
 | `bun run typecheck` | Passed |
-| `bun test --timeout 30000` | Passed: 38 tests, 262 assertions |
+| `bun test --timeout 30000` | Passed: 44 tests, 288 assertions |
 | `bun run build` | Passed |
 | `bun run binary` | Passed |
 | `bun run binaries` | Passed: twelve native targets |
 | `bun run verify-assets` | Passed: exactly fourteen unique assets |
+| `bun test devops/extract-release-notes.spec.ts` | Passed: exact heading boundaries, missing-section failure, and frontmatter/older-section exclusion |
 | `node --check scripts/runx-bin.mjs` | Passed |
 | packed npm bootstrap local-server smoke | Passed with Node and Bun removed from PATH |
 | prohibited core Node-import scan | Passed: zero matches |
 | CLI banner/help/config/agent/output/exit smoke tests | Passed in CLI suite |
+| live `upgrade --help`, prompt names, source banner, and compiled version smokes | Passed |
 | PowerShell and POSIX installer contract tests | Passed |
+| disguised-PE Markdown installer regression | Passed: installer rejected `MZ` payload before any resource write |
 | `xdocs doctor --warnings-as-errors` | Passed: zero errors and zero warnings |
 | `git diff --check` | Passed |
 
+## Independent Audit Regression Evidence
+
+- `runx upgrade` now exposes and executes `--version`, `--arch`, `--variant`,
+  `--dry-run`, and `--format` without root-version interception while retaining
+  `upgrade check` and `upgrade list`.
+- A valid `newVersionAvailable: true` cache produces the required notice before
+  the no-argument banner with the update worker disabled.
+- `agent prompt list --names` prints `guiho-i-runx` as a raw text line; JSON
+  mode still returns a parseable names array.
+- The stale ignored `bin/runx.exe` created by the single-target build was
+  removed before matrix verification. The verifier itself remains strict and
+  observed only the twelve RFC binaries plus the two named agent assets.
+
 ## Exact Release Asset Evidence
 
 The verifier observed twelve `runx-*` assets using Linux, Darwin, and Windows
-names plus `guiho-s-runx` and `guiho-i-runx`. It found no duplicate, extra,
-missing, or legacy platform name.
+names plus `guiho-s-runx.md` and `guiho-i-runx.md`. It found no duplicate,
+extra, missing, or legacy platform name.
+
+The publish workflow writes a temporary notes file containing only the exact
+version section from `CHANGELOG.md`. Existing releases receive the same notes
+through `gh release edit` before their asset set is refreshed.
 
 ## Skipped Checks
 
@@ -57,9 +79,9 @@ These are release mutations rather than local validation requirements.
 
 ## Readiness
 
-Ready for the authorized Mirror minor version application, one-file commits,
+Ready for the authorized Mirror patch application to `0.4.1`, one-file commits,
 main push, and Mirror-managed tag/ref push. Package publication and GitHub
-Release creation remain intentionally unperformed.
+Release creation remain intentionally unperformed as direct local actions.
 
 ## References
 

package/docs/validation/unicode-help-tree.md

@@ -0,0 +1,43 @@
+---
+name: RunX Unicode Help Tree Validation
+purpose: Record direct verification evidence for GitHub issue 17.
+description: Captures focused and full help tests, native tree smoke, builds, exact assets, XDocs, and Git integrity.
+created: 2026-07-19
+flags:
+  - validated
+tags:
+  - validation
+  - cli
+  - help
+keywords:
+  - RunX
+  - issue 17
+  - Unicode tree
+  - aligned descriptions
+owner: runx-validation
+---
+
+# RunX Unicode Help Tree Validation
+
+## Summary
+
+The RunX help tree matches the requested readable Unicode hierarchy. No
+validation blocker remains.
+
+## Commands Run
+
+| Command or check | Result |
+| --- | --- |
+| `bun run typecheck` | Passed |
+| focused CLI tests | Passed: 11 tests, 140 assertions |
+| explicit root tree assertions | Passed: `├──`, `└──`, `│`, aligned list description, no `|-` |
+| `bun test --timeout 30000` | Passed: 53 tests, 368 assertions |
+| build, native matrix, exact assets | Passed: library, single binary, twelve native targets, exactly fourteen assets |
+| native Windows x64 `--help-tree-depth 2` | Passed: Unicode nesting and aligned descriptions; no `|-` |
+| strict XDocs metadata and doctor | Passed for source and docs: zero errors and zero warnings |
+| `git diff --check` | Passed |
+
+## References
+
+- [Implementation review](../reviews/implementation/unicode-help-tree-review.md)
+- [Task specification](../todo/unicode-help-tree.md)

package/docs/validation/upgrade-reliability-issue-12.md

@@ -0,0 +1,74 @@
+---
+name: RunX Upgrade Reliability Issue 12 Validation
+purpose: Record current-main evidence for GitHub issue 12.
+description: Captures focused and full transaction, catalog, routing, native, live GitHub, XDocs, and Git integrity checks.
+created: 2026-07-19
+flags:
+  - validated
+tags:
+  - validation
+  - cli
+  - reliability
+keywords:
+  - RunX
+  - issue 12
+  - 50 tests
+  - 14 assets
+owner: runx-validation
+---
+
+# RunX Upgrade Reliability Issue 12 Validation
+
+## Summary
+
+All local completion gates for GitHub issue #12 passed after correcting the
+complete-list default and Citty parent/subcommand routing. No validation
+blocker remains.
+
+## Commands Run
+
+| Command or check | Result |
+| --- | --- |
+| `bun run typecheck` | Passed |
+| focused catalog, transaction, reporting, and CLI tests | Passed: 31 tests, 222 assertions |
+| `bun test --timeout 30000` | Passed: 50 tests, 342 assertions |
+| `bun run build` | Passed |
+| `bun run binary` | Passed |
+| `bun run binaries` | Passed: twelve native targets |
+| `bun run verify-assets` | Passed: exactly fourteen unique assets |
+| live source `upgrade list --format json` | Passed: one JSON document, ten current published releases, current/latest/asset metadata |
+| live source `upgrade check --format json` | Passed: one JSON document, no parent upgrade envelope |
+| strict XDocs metadata and doctor | Passed for source and docs: zero errors and zero warnings |
+| `git diff --check` | Passed |
+
+## Transaction Evidence
+
+- The self-management suite renames a running Windows executable, places the
+  new binary at the canonical path, executes that path with `--version`, and
+  reports success only after the exact target is observed.
+- Controlled second-rename, target-version mismatch, and rollback-failure tests
+  prove nonzero structured outcomes and deterministic restoration behavior.
+- Plan and phase callbacks prove plan output precedes download work and
+  replacement starts only after download and native validation.
+
+## Catalog Evidence
+
+- GitHub `Link` pagination, SemVer/prerelease ordering, channel labels,
+  malformed payloads, candidate ordering, and missing compatible assets are
+  covered by focused tests.
+- A real Citty-route regression follows two mocked release pages, includes an
+  alpha release without an opt-in flag, parses exactly one JSON document, and
+  proves the parent upgrade action did not execute.
+- Live GitHub-backed list and check routes each returned one parseable document
+  with exit code zero.
+
+## Skipped Checks
+
+- No installed user executable was replaced.
+- No package publication, GitHub Release creation, Mirror version, or tag was
+  performed during this issue unit.
+
+## References
+
+- [Implementation review](../reviews/implementation/upgrade-reliability-issue-12-review.md)
+- [Implementation plan](../plans/upgrade-reliability-implementation.md)

package/docs/validation/upgrade-reliability-issue-13.md

@@ -0,0 +1,72 @@
+---
+name: RunX Upgrade Reliability Issue 13 Validation
+purpose: Record current-main exact recovery and installer evidence for GitHub issue 13.
+description: Captures outcome-matrix, exact target, executable installer, native text/JSON, full suite, assets, XDocs, and Git checks.
+created: 2026-07-19
+flags:
+  - validated
+tags:
+  - validation
+  - cli
+  - reliability
+keywords:
+  - RunX
+  - issue 13
+  - exact recovery
+  - installer verification
+owner: runx-validation
+---
+
+# RunX Upgrade Reliability Issue 13 Validation
+
+## Summary
+
+All local completion gates for GitHub issue #13 passed. No validation blocker
+remains.
+
+## Commands Run
+
+| Command or check | Result |
+| --- | --- |
+| `bun run typecheck` | Passed |
+| focused recovery, transaction, reporting, and installer tests | Passed: 23 tests, 126 assertions |
+| `bun test --timeout 30000` | Passed: 52 tests, 358 assertions |
+| `bun run build` | Passed |
+| `bun run binary` and `bun run binaries` | Passed: single local build and twelve native targets |
+| `bun run verify-assets` | Passed: exactly fourteen unique assets |
+| native Windows x64 already-current text smoke | Passed: exact 0.4.1 installer followed by separate stop command |
+| native Windows x64 already-current JSON smoke | Passed: resolved 0.4.1 recovery object |
+| strict XDocs metadata and doctor | Passed for source, devops, and docs: zero errors and zero warnings |
+| `git diff --check` | Passed |
+
+## Recovery Evidence
+
+- The reporter test matrix covers `upgraded`, `up-to-date`, `dry-run`,
+  `rolled-back`, and `failed`; every summary precedes the exact installer, and
+  every installer precedes the separate process-stop command.
+- Discovery failure retains a visibly labeled fallback-current repair command.
+- Download and replacement failures retain the resolved recovery object in the
+  shared upgrade envelope.
+- JSON exposes `targetVersion`, `targetSource`, `installCommand`, and
+  `stopProcessCommand` without mixing text into stdout.
+
+## Installer Evidence
+
+- Windows and POSIX recovery generators preserve full prerelease identifiers.
+- The PowerShell installer functions execute exact stable and prerelease
+  normalization, accept the real Bun executable when its reported version
+  matches, and reject a controlled mismatch.
+- Installer contract tests cover exact flags, native validation, transactional
+  replacement, rollback language, and the separate stop workflow.
+
+## Platform Boundary
+
+No WSL distribution is installed in the current Windows environment. Git for
+Windows Bash executes the installer syntax, piped startup, exact-version
+normalization, and executable verification locally; Ubuntu CI remains the
+native Linux gate.
+
+## References
+
+- [Implementation review](../reviews/implementation/upgrade-reliability-issue-13-review.md)
+- [Umbrella validation](./upgrade-reliability.md)

package/docs/validation/upgrade-reliability.md

@@ -1,11 +1,11 @@
 ---
 name: RunX Upgrade Reliability Validation
-purpose: Record release-ready verification evidence for GitHub issues 12 and 13.
-description: Results for release pagination, progress reporting, transactional replacement, rollback, recovery commands, direct installers, native builds, live release smokes, and XDocs integrity.
+purpose: Preserve the completed umbrella validation for GitHub issues 12 and 13.
+description: Summarizes current release discovery, transaction, recovery, installer, native, and structured documentation evidence.
 created: 2026-07-15
+updated: 2026-07-19
 flags:
-  - superseded
-  - needs-revalidation
+  - validated
 tags:
   - validation
   - cli
@@ -24,101 +24,40 @@ owner: runx-validation
 
 ## Current Status
 
-The first validation pass below is superseded by independent review findings.
-The implementation has since been corrected for exact JSON envelope fidelity,
-post-backup rename/rollback state, downgrade prevention, installer failure
-classification, Ubuntu portability, and executable controlled installer tests.
-Candidate verification now has a bounded ten-second timeout in the CLI and both
-direct installers. Those corrections still require the complete release gate
-to be rerun before this document or the TODO task can return to
-`validated`/`completed`.
-
-No package publication, version apply, or tag operation was performed.
-
-## Superseded Automated Gate
-
-| Command | Result |
-| --- | --- |
-| `bun run typecheck` | Passed. |
-| `bun test` | Passed: 37 tests, 0 failures, 245 assertions across 8 files. |
-| `bun run build` | Passed; TypeScript library output compiled. |
-| `bun run binary` | Passed; local native executable compiled. |
-| `bun run binaries` | Passed; all 12 Linux, macOS, and Windows release assets compiled and were non-empty. |
-| `bun test devops/installers.spec.ts` | Superseded: the earlier suite relied partly on source-pattern checks. The replacement suite executes controlled native installer and recovery scenarios and awaits revalidation. |
-
-Generated `library/` and `bin/` outputs remain ignored and are not part of the
-committed change.
-
-## Superseded Behavior Evidence
-
-- Release-catalog tests follow `Link: rel="next"`, reject malformed/non-2xx
-  responses, apply SemVer prerelease precedence, retain invalid tags last, and
-  enforce baseline/default/modern asset candidates.
-- Reporting tests prove the complete plan precedes `Downloading`, which
-  precedes the download body and then `Validating`, `Replacing`, and
-  `Verifying`.
-- The Windows test runs a copied executable, keeps it mapped in a live process,
-  renames it, installs the new canonical executable immediately, verifies the
-  exact version, and allows only old-image cleanup to be deferred.
-- Failure tests reject non-native downloads before mutation and restore the
-  original executable after target verification failure.
-- Bun-launcher failure returns a recovery command pinned to the resolved target
-  instead of losing recovery at the generic CLI error boundary.
-- Installer tests enforce unique temporary paths, exact target versions,
-  canonical verification, rollback language/behavior, and separate stop
-  commands.
-
-## Superseded Compiled Binary Smoke
-
-The compiled `runx-windows-x64-baseline.exe` reported version `0.2.7`.
-`upgrade --dry-run` queried live GitHub release metadata and printed the full
-plan before any mutation, followed by the pinned `0.2.7` PowerShell recovery
-command and the separate safe stop command. `upgrade list --format json`
-returned one valid schema-versioned document containing all eight currently
-published releases from `0.2.7` through `0.2.0`, newest first, with current,
-latest-stable, publication, channel, and compatible-asset data.
-
-The first smoke command targeted `bin/runx.exe` after the complete matrix build
-had replaced the local single-binary output with named assets. It failed only
-because that path no longer existed; the smoke was immediately rerun against
-the actual baseline matrix asset and passed.
-
-## Superseded XDocs Gate
-
-Using an equivalent validation-only XDocs configuration with agent file writes
-disabled:
-
-- strict metadata passed for `docs/plans`, `docs/reviews/plans`, `docs/todo`,
-  `source`, `devops`, and `skills/guiho-s-runx`;
-- `xdocs doctor --warnings-as-errors --format json` returned `valid: true`,
-  zero errors, and zero warnings; and
-- `xdocs tree` returned one connected RunX tree without duplicate subjects or
-  orphans.
+Validated.
+
+The earlier blocked validation is superseded by the current-main issue-specific
+reviews and passing gates. GitHub issue #12 owns immediate verified replacement
+and the complete release catalog. GitHub issue #13 owns exact-version recovery
+instructions and direct installer verification.
+
+## Completion Evidence
+
+- The canonical executable is replaced and verified before success; only old
+  backup cleanup may be deferred on Windows.
+- Replacement, verification, and rollback failures return stable structured
+  outcomes and preserve exact recovery instructions.
+- Release discovery follows every GitHub page, applies SemVer ordering and
+  channel labels, and exposes current/latest/date/compatible-asset metadata.
+- The default public list includes all published prereleases and emits only its
+  selected Citty leaf result.
+- Every terminal upgrade outcome renders a pinned install command before a
+  separate platform process-stop command.
+- PowerShell and POSIX installers accept exact stable and prerelease versions,
+  validate native assets, verify the installed `--version`, and fail nonzero on
+  mismatch.
+- TypeScript, the complete Bun suite, library build, twelve native targets,
+  exact fourteen assets, live native text/JSON smokes, XDocs, and Git integrity
+  pass on the final implementation.
+
+## Detailed Records
+
+- [Issue 12 implementation review](../reviews/implementation/upgrade-reliability-issue-12-review.md)
+- [Issue 12 validation](./upgrade-reliability-issue-12.md)
+- [Issue 13 implementation review](../reviews/implementation/upgrade-reliability-issue-13-review.md)
+- [Issue 13 validation](./upgrade-reliability-issue-13.md)
 
 ## Release Boundary
 
-The branch preserves package version `0.2.7`. A future merge/release owner must
-use Mirror to plan and apply any requested patch release; this implementation
-does not publish or tag automatically.
-
-## Required Revalidation
-
-- `bun run typecheck`
-- `bun test`, including the controlled installer/recovery suite on Ubuntu and Windows
-- `bun run build`, `bun run binary`, and `bun run binaries`
-- compiled CLI text/JSON smokes, including failed and rolled-back envelopes
-- strict XDocs metadata, doctor warnings-as-errors, and tree validation
-
-The current isolated Windows worktree could not begin that rerun because
-`bun install --frozen-lockfile` was denied while opening `bun.lock` with
-`EPERM`. This is an environment validation blocker, not a passing result.
-
-## Review-Correction Checks
-
-| Command | Result |
-| --- | --- |
-| Cached TypeScript 6 compiler, `-p . --noEmit` | Passed after the review corrections. |
-| PowerShell parser for `devops/install.ps1` | Passed. |
-| Git Bash `bash -n devops/install.sh` | Passed. |
-| `git diff --check` | Passed. |
-| Focused Bun tests | Blocked before test execution by `EPERM` reading the isolated worktree and `tsconfig.json`; zero tests passed in that attempt. |
+No package publication or GitHub Release mutation was performed directly.
+Mirror versioning remains deferred to the single final open-issue release step.

package/docs/validation/validation.xdocs.md

@@ -4,20 +4,30 @@ description: Validation evidence and implementation summaries for RunX releases.
 parent: runx-docs
 children: []
 files:
+  bash-installer.md: Records Bash syntax, piped startup, exact versions, executable verification, native assets, XDocs, and Git evidence for issue 15.
   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.
   interactive-init-manifest.md: Records validation evidence for the interactive initializer and strict manifest contract.
   windows-self-upgrade.md: Records Windows replacement, rollback, cleanup, native build, CI, and XDocs validation evidence.
-  upgrade-reliability.md: Tracks the superseded first pass and required revalidation after independent upgrade reliability review corrections.
-  rfc-0034-cli-compliance-migration.md: Records passing RFC tests, builds, bootstrap, installer, import, and fourteen-asset evidence.
+  upgrade-reliability.md: Summarizes completed current-main validation for GitHub issues 12 and 13.
+  rfc-0034-cli-compliance-migration.md: Records passing RFC tests, live upgrade/startup/prompt regressions, builds, bootstrap, installers, import scan, and fourteen-asset evidence.
+  automatic-agent-maintenance.md: Records focused and full tests, native builds, exact assets, import scan, XDocs, and Git evidence for issue 11.
+  upgrade-reliability-issue-12.md: Records transaction, complete catalog, Citty routing, native matrix, live GitHub, XDocs, and Git evidence for issue 12.
+  upgrade-reliability-issue-13.md: Records all-outcome recovery, exact target, executable installer, native text/JSON, XDocs, and Git evidence for issue 13.
+  unicode-help-tree.md: Records focused/full tests, explicit glyph/alignment assertions, native smoke, assets, XDocs, and Git evidence for issue 17.
 documents:
+  bash-installer.md: Current-main validation report for the RunX Bash installer.
   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.
   interactive-init-manifest.md: Validation evidence for the RunX interactive init manifest feature.
   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.
-  upgrade-reliability.md: Revalidation record for GitHub issues 12 and 13; currently marked needs-revalidation.
-  rfc-0034-cli-compliance-migration.md: Complete RFC 0034 validation and readiness report.
+  upgrade-reliability.md: Completed umbrella validation for GitHub issues 12 and 13.
+  rfc-0034-cli-compliance-migration.md: Complete RFC 0034 correction validation and patch-release readiness report.
+  automatic-agent-maintenance.md: Complete validation report for automatic RunX agent maintenance.
+  upgrade-reliability-issue-12.md: Current-main validation report for GitHub issue 12.
+  upgrade-reliability-issue-13.md: Current-main validation report for GitHub issue 13.
+  unicode-help-tree.md: Current-main validation report for the RunX Unicode help tree.
 tags:
   - validation
 keywords:

package/library/agent-maintenance.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+export { agentMaintenanceWorkerCwd, runAgentMaintenanceWorker, spawnAgentMaintenanceWorker, };
+type AgentWorkerSpawnOptions = {
+    readonly detached: true;
+    readonly stdout: 'ignore';
+    readonly stderr: 'ignore';
+    readonly stdin: 'ignore';
+    readonly cwd: string;
+    readonly env: Record<string, string | undefined>;
+};
+type AgentWorkerSpawner = (command: string[], options: AgentWorkerSpawnOptions) => {
+    unref(): unknown;
+};
+declare function agentMaintenanceWorkerCwd(rawArgs: string[]): string | null;
+declare function runAgentMaintenanceWorker(cwd: string): Promise<void>;
+declare function spawnAgentMaintenanceWorker(cwd: string, spawn?: AgentWorkerSpawner): boolean;
+//# sourceMappingURL=agent-maintenance.d.ts.map

package/library/agent-maintenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-maintenance.d.ts","sourceRoot":"","sources":["../source/agent-maintenance.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,OAAO,EACL,yBAAyB,EACzB,yBAAyB,EACzB,2BAA2B,GAC5B,CAAA;AAED,KAAK,uBAAuB,GAAG;IAC7B,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CACjD,CAAA;AACD,KAAK,kBAAkB,GAAG,CACxB,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE,uBAAuB,KAC7B;IAAE,KAAK,IAAI,OAAO,CAAA;CAAE,CAAA;AAQzB,iBAAS,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAOnE;AAED,iBAAe,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnE;AAED,iBAAS,2BAA2B,CAClC,GAAG,EAAE,MAAM,EACX,KAAK,GAAE,kBAAsE,GAC5E,OAAO,CAmBT"}

package/library/agent-maintenance.js

@@ -0,0 +1,49 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { Type } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+import { maintainAgentIntegration } from './agents.js';
+import { RunXError } from './errors.js';
+import { directoryName, resolvePath } from './path-utils.js';
+export { agentMaintenanceWorkerCwd, runAgentMaintenanceWorker, spawnAgentMaintenanceWorker, };
+const workerFlag = '--maintain-agent-integration-worker';
+const workerArgsSchema = Type.Tuple([
+    Type.Literal(workerFlag),
+    Type.String({ minLength: 1 }),
+]);
+function agentMaintenanceWorkerCwd(rawArgs) {
+    if (rawArgs[0] !== workerFlag)
+        return null;
+    try {
+        return resolvePath(Value.Decode(workerArgsSchema, rawArgs)[1]);
+    }
+    catch (error) {
+        throw new RunXError(`Invalid agent-maintenance worker invocation: ${error instanceof Error ? error.message : String(error)}`, 2);
+    }
+}
+async function runAgentMaintenanceWorker(cwd) {
+    await maintainAgentIntegration(resolvePath(cwd));
+}
+function spawnAgentMaintenanceWorker(cwd, spawn = (command, options) => Bun.spawn(command, options)) {
+    if (Bun.env.RUNX_DISABLE_AGENT_MAINTENANCE_WORKER === '1')
+        return false;
+    const effectiveCwd = resolvePath(cwd);
+    const command = process.execPath.toLowerCase().includes('bun')
+        ? [process.execPath, Bun.main, workerFlag, effectiveCwd]
+        : [process.execPath, workerFlag, effectiveCwd];
+    try {
+        spawn(command, {
+            detached: true,
+            stdout: 'ignore',
+            stderr: 'ignore',
+            stdin: 'ignore',
+            cwd: directoryName(process.execPath),
+            env: { ...process.env, RUNX_DISABLE_AGENT_MAINTENANCE_WORKER: '1' },
+        }).unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/library/agents.d.ts

@@ -2,11 +2,15 @@
  * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
 import type { AgentScope } from './types.js';
-export { applyAgentInstructions, installAgentSkill, listAgentPrompts, listAgentSkills, removeAgentInstructions, showAgentInstructions, showAgentPrompt, showAgentSkill, uninstallAgentSkill, updateAgentInstructions, updateAgentSkill, };
+export { applyAgentInstructions, installAgentSkill, listAgentPrompts, listAgentSkills, maintainAgentIntegration, removeAgentInstructions, showAgentInstructions, showAgentPrompt, showAgentSkill, uninstallAgentSkill, updateAgentInstructions, updateAgentSkill, };
 type EmbeddedResources = {
     skill: string;
     prompt: string;
 } | undefined;
+type AgentMaintenanceResult = {
+    readonly skills: string[];
+    readonly instructions: string[];
+};
 declare global {
     var __RUNX_EMBEDDED_RESOURCES__: EmbeddedResources;
 }
@@ -27,9 +31,11 @@ declare function applyAgentInstructions(cwd: string): Promise<string[]>;
 declare function updateAgentInstructions(cwd: string): Promise<string[]>;
 declare function removeAgentInstructions(cwd: string): Promise<string[]>;
 declare function showAgentInstructions(): Promise<string>;
-declare function listAgentPrompts(namesOnly?: boolean): string[] | Array<{
+declare function listAgentPrompts(namesOnly: true): string[];
+declare function listAgentPrompts(namesOnly?: false): Array<{
     id: string;
     description: string;
 }>;
 declare function showAgentPrompt(id: string): Promise<string>;
+declare function maintainAgentIntegration(cwd: string): Promise<AgentMaintenanceResult>;
 //# sourceMappingURL=agents.d.ts.map

package/library/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../source/agents.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,uBAAuB,EACvB,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,GACjB,CAAA;AAED,KAAK,iBAAiB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAA;AAEtE,OAAO,CAAC,MAAM,CAAC;IACb,IAAI,2BAA2B,EAAE,iBAAiB,CAAA;CACnD;AAOD,iBAAe,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAElF;AAED,iBAAe,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEjF;AAED,iBAAe,mBAAmB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAIpF;AAED,iBAAS,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAIpF;AAED,iBAAe,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC,CAQtI;AAED,iBAAe,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEpE;AAED,iBAAe,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAErE;AAED,iBAAe,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAYrE;AAED,iBAAe,qBAAqB,IAAI,OAAO,CAAC,MAAM,CAAC,CAEtD;AAED,iBAAS,gBAAgB,CAAC,SAAS,UAAQ,GAAG,MAAM,EAAE,GAAG,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAIlG;AAED,iBAAe,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG1D"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../source/agents.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,wBAAwB,EACxB,uBAAuB,EACvB,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,GACjB,CAAA;AAED,KAAK,iBAAiB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAA;AACtE,KAAK,sBAAsB,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAA;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAChC,CAAA;AAED,OAAO,CAAC,MAAM,CAAC;IACb,IAAI,2BAA2B,EAAE,iBAAiB,CAAA;CACnD;AASD,iBAAe,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAElF;AAED,iBAAe,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEjF;AAED,iBAAe,mBAAmB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAIpF;AAED,iBAAS,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAIpF;AAED,iBAAe,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC,CAQtI;AAED,iBAAe,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEpE;AAED,iBAAe,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAErE;AAED,iBAAe,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAYrE;AAED,iBAAe,qBAAqB,IAAI,OAAO,CAAC,MAAM,CAAC,CAEtD;AAED,iBAAS,gBAAgB,CAAC,SAAS,EAAE,IAAI,GAAG,MAAM,EAAE,CAAA;AACpD,iBAAS,gBAAgB,CAAC,SAAS,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAOxF,iBAAe,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG1D;AAED,iBAAe,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAoBpF"}