@guiho/runx 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -15,6 +15,58 @@ owner: runx
 
 # Changelog
 
+## 0.5.1 - 2026-07-19
+
+### Fixed
+
+- Enforced LF line endings for Bash scripts so Windows checkouts preserve
+  portable installer syntax.
+- Gave the detached agent-maintenance integration test an explicit
+  platform-appropriate timeout so slower Windows CI runners validate the full
+  workflow without changing runtime behavior.
+
+## 0.5.0 - 2026-07-19
+
+### Added
+
+- Added silent detached maintenance that keeps both global `guiho-s-runx`
+  skill installations current and reconciles one nearest managed `AGENTS.md`
+  block without changing foreground output or exit behavior.
+- Added explicit regression coverage for every upgrade recovery outcome,
+  executable stable/prerelease installer verification, and the Unicode
+  description-aligned command tree.
+
+### Changed
+
+- `runx upgrade list` now returns the complete published catalog, including
+  labeled prereleases, unless pagination is explicitly requested.
+- The Linux/macOS installer and generated recovery commands now use Bash with
+  `set -euo pipefail`; canonical documentation no longer invokes `sh`.
+- Release delivery now validates the exact twelve native binaries and two
+  Markdown agent assets and uses only the matching changelog version section
+  for GitHub Release notes.
+
+### Fixed
+
+- Fixed `runx upgrade list` and `runx upgrade check` so Citty does not execute
+  the parent upgrade action after the selected leaf or append a second JSON
+  document.
+- Fixed automatic agent-resource updates to use idempotent atomic writes,
+  preserve user-authored instructions, migrate legacy markers, and remain safe
+  under concurrent invocations.
+
+## 0.4.1 - 2026-07-18
+
+### Fixed
+
+- Fixed `runx upgrade` so its required `--version`, `--arch`, `--variant`,
+  `--dry-run`, and `--format` flags route to the upgrade action instead of
+  being hidden by the command group or intercepted as the root version flag.
+- Fixed no-argument startup so a decoded cached update notice is printed before
+  the exact RunX banner without waiting for network work.
+- Fixed `runx agent prompt list --names` text output so it prints raw prompt
+  names, one per line, while JSON mode remains structured.
+
 ## 0.4.0 - 2026-07-18
 
 ### Added

package/DOCS.md

@@ -99,6 +99,14 @@ Skill install, update, and uninstall default to global scope and target both:
 
 Use `--local` for the corresponding project-local paths.
 
+Ordinary RunX commands schedule a hidden detached worker that compares the
+bundled skill with both global copies and rewrites only missing or stale
+targets. The worker finds the nearest existing `AGENTS.md` from effective
+`--cwd`; when none exists in an ancestor, it creates `AGENTS.md` at effective
+cwd. Reconciliation is atomic, migrates legacy RunX markers, preserves content
+outside managed markers, and is silent when no change is required. Worker
+failures never change foreground output or exit status.
+
 Instruction actions manage both `AGENTS.md` and `CLAUDE.md` when both exist,
 the existing one when only one exists, and create `AGENTS.md` when neither
 exists. The exact idempotent boundaries are:
@@ -114,8 +122,10 @@ names; `agent prompt show <id>` prints only the raw prompt.
 ## Upgrade And Installation
 
 `runx upgrade` accepts `--version`, `--arch`, `--variant`, `--dry-run`, and
-`--format`. x64 defaults to `baseline`. `upgrade list` supports positive
-`--page` and `--per-page` plus `--pre-releases`.
+`--format`. x64 defaults to `baseline`. `upgrade list` returns the complete
+published catalog, including labeled prereleases, by default. Positive
+`--page` and `--per-page` values request an explicit view; `--pre-releases` is
+accepted but is unnecessary because prereleases are never hidden.
 
 Replacement is transactional: download, native-format validation, backup,
 replacement, version verification, rollback on failure, agent-skill refresh,
@@ -150,6 +160,16 @@ runx-windows-arm64.exe
 runx-windows-x64.exe
 runx-windows-x64-baseline.exe
 runx-windows-x64-modern.exe
-guiho-s-runx
-guiho-i-runx
+guiho-s-runx.md
+guiho-i-runx.md
 ```
+
+The Markdown suffix is part of the public GitHub Release filename contract.
+Installers retain the standard installed skill filename `SKILL.md` and use the
+instruction asset contents when reconciling managed instruction blocks. Before
+either write, installers reject empty, executable, binary, invalid UTF-8, or
+misidentified Markdown payloads.
+
+Release descriptions contain only the matching `## <version> - <date>`
+changelog section. The publish workflow fails closed when that exact section is
+missing and refreshes the notes when rerunning an existing release.

package/README.md

@@ -32,13 +32,18 @@ irm https://raw.githubusercontent.com/CGuiho/runx/main/devops/install.ps1 | iex
 POSIX:
 
 ```sh
-curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/CGuiho/runx/main/devops/install.sh | sh
+curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/CGuiho/runx/main/devops/install.sh | bash
 ```
 
 The direct installers select and verify a native asset, install `runx` on PATH,
 install `guiho-s-runx` into both global agent-tool directories, and reconcile
 RunX instructions in the current project.
 
+After installation, ordinary RunX invocations schedule a silent background
+maintenance worker. It repairs missing or stale global skill copies and keeps
+one compact RunX block in the nearest `AGENTS.md` without delaying or changing
+the requested command's output.
+
 The npm package is a Node-compatible bootstrap that downloads and delegates to
 the version-matched native binary. Bun is not required for npm installation or
 first execution.

package/devops/build-binaries.ts

@@ -31,7 +31,7 @@ const binaryTargets: readonly BinaryTarget[] = [
   { bunTarget: 'bun-windows-x64-modern', assetName: 'runx-windows-x64-modern.exe' },
 ]
 
-const agentAssetNames = ['guiho-s-runx', 'guiho-i-runx'] as const
+const agentAssetNames = ['guiho-s-runx.md', 'guiho-i-runx.md'] as const
 const expectedReleaseAssetNames = [...binaryTargets.map((target) => target.assetName), ...agentAssetNames]
 
 if (expectedReleaseAssetNames.length !== 14 || new Set(expectedReleaseAssetNames).size !== 14) {
@@ -69,8 +69,8 @@ if (import.meta.main) {
     process.stdout.write(`built: ${target.assetName}\n`)
   }
 
-  await Bun.write(joinPath(bin, 'guiho-s-runx'), Bun.file(joinPath(root, 'skills', 'guiho-s-runx', 'SKILL.md')))
-  await Bun.write(joinPath(bin, 'guiho-i-runx'), Bun.file(joinPath(root, 'prompts', 'guiho-i-runx.md')))
+  await Bun.write(joinPath(bin, 'guiho-s-runx.md'), Bun.file(joinPath(root, 'skills', 'guiho-s-runx', 'SKILL.md')))
+  await Bun.write(joinPath(bin, 'guiho-i-runx.md'), Bun.file(joinPath(root, 'prompts', 'guiho-i-runx.md')))
 
   const observed = [...new Bun.Glob('*').scanSync({ cwd: bin, onlyFiles: true })].sort()
   const expected = [...expectedReleaseAssetNames].sort()

package/devops/devops.xdocs.md

@@ -4,11 +4,13 @@ description: Native release-asset compilation and direct RunX installer scripts.
 parent: runx
 children: []
 files:
-  build-binaries.ts: Cross-compiles twelve RFC-named native binaries and adds the two exact agent assets.
-  verify-release-assets.ts: Fails on any missing, duplicate, extra, or legacy release asset name.
-  installers.spec.ts: Verifies both installers expose progress, validation, dual-tool skills, instruction reconciliation, and no POSIX Bun dependency.
+  build-binaries.ts: Cross-compiles twelve RFC-named native binaries and adds the two exact .md agent assets.
+  extract-release-notes.ts: Extracts one exact version section from CHANGELOG.md and fails closed when the heading or notes are missing.
+  extract-release-notes.spec.ts: Verifies exact heading boundaries and exclusion of frontmatter and other release sections.
+  verify-release-assets.ts: Fails on missing, duplicate, extra, legacy, empty, binary, or misidentified release assets.
+  installers.spec.ts: Verifies installer progress, resources, exact stable/prerelease normalization, executable version matching, Markdown rejection, and no POSIX Bun dependency.
   install.ps1: Resolves an exact Windows release, downloads and validates a compatible asset, transactionally replaces the canonical executable, verifies its version, and rolls back on failure.
-  install.sh: POSIX installer for Linux or Darwin with progress, validation, PATH, dual skills, instructions, verification, and rollback.
+  install.sh: Bash installer for Linux or Darwin with strict mode, progress, validation, PATH, dual skills, instructions, verification, and rollback.
 documents: {}
 tags:
   - devops
@@ -24,5 +26,6 @@ flags: []
 status: stable
 ---
 
-These scripts build and verify the exact fourteen-asset release and support
-direct installation without npm or Bun.
+These scripts build and verify the exact fourteen-asset release, validate the
+downloaded Markdown resource contract, create exact version-only GitHub Release
+notes, and support direct installation without npm or Bun.

package/devops/extract-release-notes.spec.ts

@@ -0,0 +1,54 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+
+import { describe, expect, test } from 'bun:test'
+import { extractReleaseNotes } from './extract-release-notes.js'
+
+describe('extractReleaseNotes', () => {
+  test('extracts only the exact unbracketed version section', () => {
+    const changelog = `---
+name: Example
+---
+
+# Changelog
+
+## 0.4.10 - 2026-07-20
+
+### Fixed
+
+- Newer patch.
+
+## 0.4.1 - 2026-07-18
+
+### Fixed
+
+- Requested patch.
+
+## 0.4.0 - 2026-07-18
+
+### Added
+
+- Older release.
+`
+
+    expect(extractReleaseNotes(changelog, '0.4.1')).toBe(`## 0.4.1 - 2026-07-18
+
+### Fixed
+
+- Requested patch.
+`)
+  })
+
+  test('fails closed when the exact version heading is absent', () => {
+    expect(() => extractReleaseNotes('## 0.4.1 - 2026-07-18\n\n- Fixed.\n', '0.4.2')).toThrow(
+      'Expected exactly one changelog heading for version 0.4.2.',
+    )
+  })
+
+  test('rejects an empty version section', () => {
+    expect(() => extractReleaseNotes('## 0.4.2 - 2026-07-19\n## 0.4.1 - 2026-07-18\n\n- Older.\n', '0.4.2')).toThrow(
+      'Changelog section for version 0.4.2 has no release notes.',
+    )
+  })
+})

package/devops/extract-release-notes.ts

@@ -0,0 +1,40 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+
+export {
+  extractReleaseNotes,
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function extractReleaseNotes(changelog: string, version: string): string {
+  const normalized = changelog.replace(/\r\n/g, '\n')
+  const heading = new RegExp(`^## ${escapeRegExp(version)} - .+$`, 'gm')
+  const matches = [...normalized.matchAll(heading)]
+  if (matches.length !== 1 || matches[0]?.index === undefined) {
+    throw new Error(`Expected exactly one changelog heading for version ${version}.`)
+  }
+
+  const start = matches[0].index
+  const nextHeading = normalized.indexOf('\n## ', start + matches[0][0].length)
+  const section = normalized.slice(start, nextHeading === -1 ? normalized.length : nextHeading).trim()
+  if (!section.includes('\n')) {
+    throw new Error(`Changelog section for version ${version} has no release notes.`)
+  }
+
+  return `${section}\n`
+}
+
+if (import.meta.main) {
+  const [version, outputPath] = Bun.argv.slice(2)
+  if (!version || !outputPath) {
+    throw new Error('Usage: bun run devops/extract-release-notes.ts <version> <output-path>')
+  }
+
+  const changelog = await Bun.file(new URL('../CHANGELOG.md', import.meta.url)).text()
+  await Bun.write(outputPath, extractReleaseNotes(changelog, version))
+  process.stdout.write(`wrote release notes for ${version}: ${outputPath}\n`)
+}

package/devops/install.ps1

@@ -78,6 +78,25 @@ function Test-NativeBinary {
   finally { $stream.Dispose() }
 }
 
+function Test-MarkdownAsset {
+  param([string]$Path, [string]$ExpectedName)
+  $bytes = [System.IO.File]::ReadAllBytes($Path)
+  if ($bytes.Length -eq 0) { throw "Downloaded Markdown asset is empty: $Path" }
+  if ($bytes.Length -ge 2 -and $bytes[0] -eq 0x4D -and $bytes[1] -eq 0x5A) {
+    throw "Downloaded Markdown asset has a Windows executable header: $Path"
+  }
+  if ($bytes -contains 0) { throw "Downloaded Markdown asset contains binary NUL bytes: $Path" }
+  try {
+    $text = ([System.Text.UTF8Encoding]::new($false, $true)).GetString($bytes).Replace("`r`n", "`n")
+  } catch {
+    throw "Downloaded Markdown asset is not valid UTF-8 text: $Path"
+  }
+  if (-not $text.StartsWith("---`n")) { throw "Downloaded Markdown asset does not begin with YAML frontmatter: $Path" }
+  if ($text -notmatch "(?m)^name:\s*$([Regex]::Escape($ExpectedName))\s*$") {
+    throw "Downloaded Markdown asset identity does not match $ExpectedName`: $Path"
+  }
+}
+
 function Test-InstalledVersion {
   param([string]$Path, [string]$ExpectedVersion)
   $startInfo = New-Object System.Diagnostics.ProcessStartInfo
@@ -156,6 +175,8 @@ function Test-Shadowing {
   }
 }
 
+if ($env:RUNX_INSTALLER_SOURCE_ONLY -eq '1') { return }
+
 $detectedArch = if ($Arch) { $Arch } else { switch ($env:PROCESSOR_ARCHITECTURE) { 'AMD64' { 'x64' } 'ARM64' { 'arm64' } default { throw "Unsupported architecture: $env:PROCESSOR_ARCHITECTURE" } } }
 if ($detectedArch -notin @('x64', 'arm64')) { throw "Invalid architecture: $detectedArch" }
 if (-not [Environment]::Is64BitOperatingSystem) { throw 'Unsupported platform: Windows 32-bit is not supported.' }
@@ -208,13 +229,15 @@ try {
   if (-not $downloadedPath) { throw "No compatible RunX $targetVersion binary found at https://github.com/$Repo/releases" }
   Write-Host 'Replacing...'
   Install-Transactional -DownloadedPath $downloadedPath -Destination $destination -ExpectedVersion $targetVersion
-  $skillAsset = Join-Path $temporaryDirectory 'guiho-s-runx'
-  $promptAsset = Join-Path $temporaryDirectory 'guiho-i-runx'
+  $skillAsset = Join-Path $temporaryDirectory 'guiho-s-runx.md'
+  $promptAsset = Join-Path $temporaryDirectory 'guiho-i-runx.md'
   $assetBase = if ($DownloadBaseUrl) { "$DownloadBaseUrl/$encodedTag" } else { "https://github.com/$Repo/releases/download/$encodedTag" }
-  Write-Host "Downloading skill asset: $assetBase/guiho-s-runx"
-  Invoke-WebRequest -Uri "$assetBase/guiho-s-runx" -OutFile $skillAsset -UseBasicParsing
-  Write-Host "Downloading instruction asset: $assetBase/guiho-i-runx"
-  Invoke-WebRequest -Uri "$assetBase/guiho-i-runx" -OutFile $promptAsset -UseBasicParsing
+  Write-Host "Downloading skill asset: $assetBase/guiho-s-runx.md"
+  Invoke-WebRequest -Uri "$assetBase/guiho-s-runx.md" -OutFile $skillAsset -UseBasicParsing
+  Test-MarkdownAsset -Path $skillAsset -ExpectedName 'guiho-s-runx'
+  Write-Host "Downloading instruction asset: $assetBase/guiho-i-runx.md"
+  Invoke-WebRequest -Uri "$assetBase/guiho-i-runx.md" -OutFile $promptAsset -UseBasicParsing
+  Test-MarkdownAsset -Path $promptAsset -ExpectedName 'guiho-i-runx'
   foreach ($skillRoot in @((Join-Path $HOME '.agents\skills\guiho-s-runx'), (Join-Path $HOME '.claude\skills\guiho-s-runx'))) {
     New-Item -ItemType Directory -Force -Path $skillRoot | Out-Null
     Copy-Item -LiteralPath $skillAsset -Destination (Join-Path $skillRoot 'SKILL.md') -Force

package/devops/install.sh

@@ -1,5 +1,5 @@
-#!/usr/bin/env sh
-set -eu
+#!/usr/bin/env bash
+set -euo pipefail
 
 REPO="${RUNX_REPO:-CGuiho/runx}"
 VERSION="${RUNX_VERSION:-latest}"
@@ -106,6 +106,25 @@ verify_native_binary() {
   esac
 }
 
+verify_markdown_asset() {
+  path=$1
+  expected_name=$2
+  [ -s "$path" ] || fail "downloaded Markdown asset is empty: $path"
+  magic=$(od -An -tx1 -N2 "$path" 2>/dev/null | tr -d ' \n')
+  [ "$magic" != 4d5a ] || fail "downloaded Markdown asset has a Windows executable header: $path"
+  if od -An -tx1 "$path" 2>/dev/null | grep -Eq '(^|[[:space:]])00([[:space:]]|$)'; then
+    fail "downloaded Markdown asset contains binary NUL bytes: $path"
+  fi
+  iconv -f UTF-8 -t UTF-8 "$path" >/dev/null 2>&1 || fail "downloaded Markdown asset is not valid UTF-8 text: $path"
+  first_line=$(sed -n '1{s/\r$//;p;}' "$path")
+  [ "$first_line" = '---' ] || fail "downloaded Markdown asset does not begin with YAML frontmatter: $path"
+  awk -v expected="$expected_name" '
+    { sub(/\r$/, "") }
+    $0 == "name: " expected { found=1 }
+    END { exit(found ? 0 : 1) }
+  ' "$path" || fail "downloaded Markdown asset identity does not match $expected_name: $path"
+}
+
 verify_installed_version() {
   verify_output=$(mktemp "${TMPDIR:-/tmp}/runx-version.XXXXXX") || return 1
   "$1" --version >"$verify_output" 2>&1 &
@@ -135,10 +154,10 @@ verify_installed_version() {
 ensure_path() {
   PATH="$INSTALL_DIR:$PATH"; export PATH
   profile="$HOME/.profile"
-  case "${SHELL##*/}" in zsh) profile="$HOME/.zshrc" ;; bash) profile="$HOME/.bashrc" ;; fish) profile="$HOME/.config/fish/config.fish" ;; esac
+  case "${SHELL:-bash}" in */zsh|zsh) profile="$HOME/.zshrc" ;; */bash|bash) profile="$HOME/.bashrc" ;; */fish|fish) profile="$HOME/.config/fish/config.fish" ;; esac
   mkdir -p -- "$(dirname "$profile")"
   if ! grep -Fq "$INSTALL_DIR" "$profile" 2>/dev/null; then
-    if [ "${SHELL##*/}" = fish ]; then printf '\n# Added by runx installer\nfish_add_path %s\n' "$INSTALL_DIR" >>"$profile"
+    if [ "${SHELL:-bash}" = fish ] || [ "${SHELL:-bash}" = */fish ]; then printf '\n# Added by runx installer\nfish_add_path %s\n' "$INSTALL_DIR" >>"$profile"
     else printf '\n# Added by runx installer\nexport PATH=%s:$PATH\n' "$INSTALL_DIR" >>"$profile"; fi
   fi
 }
@@ -183,15 +202,17 @@ install_transactional() {
 
 install_agent_assets() {
   tag_base=${DOWNLOAD_BASE_URL:-"https://github.com/${REPO}/releases/download"}
-  skill_url="${tag_base%/}/${encoded_tag}/guiho-s-runx"
-  prompt_url="${tag_base%/}/${encoded_tag}/guiho-i-runx"
+  skill_url="${tag_base%/}/${encoded_tag}/guiho-s-runx.md"
+  prompt_url="${tag_base%/}/${encoded_tag}/guiho-i-runx.md"
   printf 'Downloading skill asset: %s\n' "$skill_url"
-  download_asset "$skill_url" "$TMP/guiho-s-runx" || fail 'could not download guiho-s-runx'
+  download_asset "$skill_url" "$TMP/guiho-s-runx.md" || fail 'could not download guiho-s-runx.md'
+  verify_markdown_asset "$TMP/guiho-s-runx.md" 'guiho-s-runx'
   printf 'Downloading instruction asset: %s\n' "$prompt_url"
-  download_asset "$prompt_url" "$TMP/guiho-i-runx" || fail 'could not download guiho-i-runx'
+  download_asset "$prompt_url" "$TMP/guiho-i-runx.md" || fail 'could not download guiho-i-runx.md'
+  verify_markdown_asset "$TMP/guiho-i-runx.md" 'guiho-i-runx'
   for skill_root in "$HOME/.agents/skills/guiho-s-runx" "$HOME/.claude/skills/guiho-s-runx"; do
     mkdir -p -- "$skill_root"
-    install -m 0644 "$TMP/guiho-s-runx" "$skill_root/SKILL.md"
+    install -m 0644 "$TMP/guiho-s-runx.md" "$skill_root/SKILL.md"
     printf 'Installed skill: %s\n' "$skill_root/SKILL.md"
   done
   targets=""
@@ -214,7 +235,7 @@ install_agent_assets() {
       cat "$clean_file"
       [ ! -s "$clean_file" ] || printf '\n'
       printf '<!-- BEGIN RUNX — DO NOT EDIT THIS SECTION -->\n'
-      cat "$TMP/guiho-i-runx"
+      cat "$TMP/guiho-i-runx.md"
       printf '\n<!-- END RUNX -->\n'
     } >"$instruction_file"
   done
@@ -222,7 +243,7 @@ install_agent_assets() {
 
 main() {
   parse_args "$@"
-  for command in awk cat curl date dirname grep head install mktemp mv od rm sed tr uname; do require_command "$command"; done
+  for command in awk cat curl date dirname grep head iconv install mktemp mv od rm sed tr uname; do require_command "$command"; done
   OS=$(detect_os); ARCH=$(detect_arch); TARGET_VERSION=$(resolve_target_version)
   TMP=$(mktemp -d "${TMPDIR:-/tmp}/runx-install.XXXXXX")
   mkdir -p -- "$INSTALL_DIR"
@@ -256,4 +277,8 @@ main() {
   printf 'Installed and verified RunX %s at %s\n' "$TARGET_VERSION" "$destination"
 }
 
+if [ "${RUNX_INSTALLER_SOURCE_ONLY:-0}" = 1 ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
 main "$@"

package/devops/installers.spec.ts

@@ -3,29 +3,176 @@
  */
 
 import { describe, expect, test } from 'bun:test'
+import { $ } from 'bun'
 
 describe('RunX direct installers', () => {
   test('PowerShell installer exposes the complete RFC sequence', async () => {
     const script = await Bun.file(new URL('./install.ps1', import.meta.url)).text()
     expect(script).toContain('Initiating GUIHO CLI Upgrade / Installation Sequence...')
-    expect(script).toContain('guiho-s-runx')
-    expect(script).toContain('guiho-i-runx')
+    expect(script).toContain('guiho-s-runx.md')
+    expect(script).toContain('guiho-i-runx.md')
     expect(script).toContain('.agents\\skills\\guiho-s-runx')
     expect(script).toContain('.claude\\skills\\guiho-s-runx')
     expect(script).toContain('BEGIN RUNX — DO NOT EDIT THIS SECTION')
     expect(script).toContain('Test-NativeBinary')
     expect(script).toContain('Install-Transactional')
+    expect(script).toContain('function Test-MarkdownAsset')
+    expect(script).toContain("Test-MarkdownAsset -Path $skillAsset -ExpectedName 'guiho-s-runx'")
+    expect(script).toContain("Test-MarkdownAsset -Path $promptAsset -ExpectedName 'guiho-i-runx'")
+    expect(script).toContain('Windows executable header')
+    expect(script).toContain('binary NUL bytes')
+    expect(script).toContain('not valid UTF-8 text')
   })
 
-  test('POSIX installer selects Darwin assets and has no Bun dependency', async () => {
+  test('Bash installer selects Darwin assets and has no runtime Bun dependency', async () => {
     const script = await Bun.file(new URL('./install.sh', import.meta.url)).text()
+    expect(script).toStartWith('#!/usr/bin/env bash\nset -euo pipefail')
     expect(script).toContain("Darwin) printf 'darwin")
     expect(script).toContain('--progress-bar')
-    expect(script).toContain('guiho-s-runx')
-    expect(script).toContain('guiho-i-runx')
+    expect(script).toContain('guiho-s-runx.md')
+    expect(script).toContain('guiho-i-runx.md')
     expect(script).toContain('.agents/skills/guiho-s-runx')
     expect(script).toContain('.claude/skills/guiho-s-runx')
+    expect(script).toContain('verify_markdown_asset()')
+    expect(script).toContain("verify_markdown_asset \"$TMP/guiho-s-runx.md\" 'guiho-s-runx'")
+    expect(script).toContain("verify_markdown_asset \"$TMP/guiho-i-runx.md\" 'guiho-i-runx'")
+    expect(script).toContain('Windows executable header')
+    expect(script).toContain('binary NUL bytes')
+    expect(script).toContain('iconv -f UTF-8 -t UTF-8')
     expect(script).toContain('BEGIN RUNX — DO NOT EDIT THIS SECTION')
     expect(script).not.toContain(' bun ')
   })
+
+  test('Bash installer passes syntax, piped startup, exact versions, and executable verification', async () => {
+    const bash = await bashExecutable()
+    const script = Bun.fileURLToPath(new URL('./install.sh', import.meta.url))
+    const syntax = Bun.spawnSync([bash, '-n', script])
+    expect(syntax.exitCode).toBe(0)
+
+    const piped = Bun.spawnSync([
+      bash,
+      '-c',
+      'cat "$1" | RUNX_INSTALLER_SOURCE_ONLY=1 bash -s --',
+      'bash',
+      script,
+    ])
+    expect(piped.exitCode).toBe(0)
+    expect(piped.stderr.toString()).toBe('')
+
+    const functions = Bun.spawnSync([
+      bash,
+      '-c',
+      [
+        'RUNX_INSTALLER_SOURCE_ONLY=1 source "$1"',
+        'stable=$(normalize_version v1.2.3)',
+        'prerelease=$(normalize_version @guiho/runx@1.3.0-alpha.2)',
+        'test "$stable" = 1.2.3',
+        'test "$prerelease" = 1.3.0-alpha.2',
+        'TARGET_VERSION=$(bun --version)',
+        'verify_installed_version "$(command -v bun)"',
+      ].join('; '),
+      'bash',
+      script,
+    ])
+    expect(functions.exitCode).toBe(0)
+  })
+
+  test('platform installer rejects a PE payload disguised as Markdown', async () => {
+    const temporaryDirectory = `${Bun.env.TEMP ?? Bun.env.TMPDIR ?? '/tmp'}/runx-markdown-${crypto.randomUUID()}`
+    const validAsset = `${temporaryDirectory}/valid.md`
+    const executableAsset = `${temporaryDirectory}/payload.md`
+    await $`mkdir -p ${temporaryDirectory}`
+    try {
+      await Bun.write(validAsset, '---\nname: guiho-s-runx\n---\n\n# Skill\n')
+      await Bun.write(executableAsset, new Uint8Array([0x4d, 0x5a, 0x00, 0x00]))
+
+      if (process.platform === 'win32') {
+        const script = Bun.fileURLToPath(new URL('./install.ps1', import.meta.url))
+        const valid = Bun.spawnSync([
+          'powershell',
+          '-NoLogo',
+          '-NoProfile',
+          '-NonInteractive',
+          '-ExecutionPolicy',
+          'Bypass',
+          '-Command',
+          `$env:RUNX_INSTALLER_SOURCE_ONLY='1'; . '${script.replaceAll("'", "''")}'; Test-MarkdownAsset -Path '${validAsset.replaceAll("'", "''")}' -ExpectedName 'guiho-s-runx'`,
+        ])
+        const invalid = Bun.spawnSync([
+          'powershell',
+          '-NoLogo',
+          '-NoProfile',
+          '-NonInteractive',
+          '-ExecutionPolicy',
+          'Bypass',
+          '-Command',
+          `$env:RUNX_INSTALLER_SOURCE_ONLY='1'; . '${script.replaceAll("'", "''")}'; Test-MarkdownAsset -Path '${executableAsset.replaceAll("'", "''")}' -ExpectedName 'guiho-s-runx'`,
+        ])
+        expect(valid.exitCode).toBe(0)
+        expect(invalid.exitCode).not.toBe(0)
+        expect(invalid.stderr.toString()).toContain('Windows executable header')
+      } else {
+        const script = Bun.fileURLToPath(new URL('./install.sh', import.meta.url))
+        const bash = await bashExecutable()
+        const valid = Bun.spawnSync([
+          bash,
+          '-c',
+          `RUNX_INSTALLER_SOURCE_ONLY=1 . "$1"; verify_markdown_asset "$2" guiho-s-runx`,
+          'bash',
+          script,
+          validAsset,
+        ])
+        const invalid = Bun.spawnSync([
+          bash,
+          '-c',
+          `RUNX_INSTALLER_SOURCE_ONLY=1 . "$1"; verify_markdown_asset "$2" guiho-s-runx`,
+          'bash',
+          script,
+          executableAsset,
+        ])
+        expect(valid.exitCode).toBe(0)
+        expect(invalid.exitCode).not.toBe(0)
+        expect(invalid.stderr.toString()).toContain('Windows executable header')
+      }
+    } finally {
+      await $`rm -rf ${temporaryDirectory}`
+    }
+  })
+
+  if (process.platform === 'win32') {
+    test('PowerShell installer accepts exact stable and prerelease versions and verifies the executable', () => {
+      const script = Bun.fileURLToPath(new URL('./install.ps1', import.meta.url)).replaceAll("'", "''")
+      const bun = process.execPath.replaceAll("'", "''")
+      const command = [
+        "$env:RUNX_INSTALLER_SOURCE_ONLY='1'",
+        `. '${script}'`,
+        "$stable = Resolve-TargetVersion -RequestedVersion 'v1.2.3'",
+        "$prerelease = Resolve-TargetVersion -RequestedVersion '@guiho/runx@1.3.0-alpha.2'",
+        "if ($stable -ne '1.2.3' -or $prerelease -ne '1.3.0-alpha.2') { throw 'exact version normalization failed' }",
+        `Test-InstalledVersion -Path '${bun}' -ExpectedVersion '${process.versions.bun}'`,
+        "$mismatchRejected = $false",
+        `try { Test-InstalledVersion -Path '${bun}' -ExpectedVersion '0.0.0-impossible' } catch { $mismatchRejected = $true }`,
+        "if (-not $mismatchRejected) { throw 'version mismatch was not rejected' }",
+      ].join('; ')
+      const result = Bun.spawnSync([
+        'powershell',
+        '-NoLogo',
+        '-NoProfile',
+        '-NonInteractive',
+        '-ExecutionPolicy',
+        'Bypass',
+        '-Command',
+        command,
+      ])
+      expect(result.exitCode).toBe(0)
+    })
+  }
 })
+
+async function bashExecutable(): Promise<string> {
+  const gitBash = 'C:\\Program Files\\Git\\bin\\bash.exe'
+  if (process.platform === 'win32' && await Bun.file(gitBash).exists()) return gitBash
+  const bash = Bun.which('bash')
+  if (!bash) throw new Error('Bash is required to validate devops/install.sh.')
+  return bash
+}

package/devops/verify-release-assets.ts

@@ -14,4 +14,18 @@ if (JSON.stringify(observed) !== JSON.stringify(expected)) {
   throw new Error(`Expected exactly ${expected.length} release assets.\nExpected: ${expected.join(', ')}\nObserved: ${observed.join(', ')}`)
 }
 
+for (const [assetName, expectedName] of [
+  ['guiho-s-runx.md', 'guiho-s-runx'],
+  ['guiho-i-runx.md', 'guiho-i-runx'],
+] as const) {
+  const bytes = await Bun.file(joinPath(bin, assetName)).bytes()
+  if (bytes.length === 0 || (bytes[0] === 0x4d && bytes[1] === 0x5a) || bytes.includes(0)) {
+    throw new Error(`Release Markdown asset is empty or binary: ${assetName}`)
+  }
+  const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes).replace(/\r\n/g, '\n')
+  if (!text.startsWith('---\n') || !new RegExp(`^name:\\s*${expectedName}\\s*$`, 'm').test(text)) {
+    throw new Error(`Release Markdown asset has invalid frontmatter identity: ${assetName}`)
+  }
+}
+
 process.stdout.write(`${JSON.stringify({ count: observed.length, assets: observed }, null, 2)}\n`)

package/docs/architecture/architecture.xdocs.md

@@ -1,6 +1,6 @@
 ---
 subject: runx-architecture
-description: Technical architecture for the RunX manifest, Citty command tree, agent skill, and native distribution.
+description: Technical architecture for the RunX manifest, Citty command tree, automatic agent maintenance, and native distribution.
 parent: runx-docs
 children: []
 files:
@@ -14,6 +14,7 @@ keywords:
   - bun
   - cli
   - citty
+  - agent maintenance
 flags: []
 status: stable
 ---