The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
fix(cli): install the hn command for existing users (#417)
Deed3ce52b1496e
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 1f2b0eabe..092d3e657 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -101,6 +101,11 @@ jobs:# `npm run test:tmux-real` and friends are how those are run, on a machine that has them.- run: npx vitest run+ - name: Verify hn launcher repair in an existing installation+ run: |+ npm run bundle+ node scripts/test-hn-upgrade.mjs+- name: Require complete harness updater coveragerun: npm run test:dsh-updatesdiff --git a/cli/scripts/test-hn-upgrade.mjs b/cli/scripts/test-hn-upgrade.mjsnew file mode 100644index 000000000..fd0a20269--- /dev/null+++ b/cli/scripts/test-hn-upgrade.mjs@@ -0,0 +1,127 @@+/** Packaged CLI upgrade smoke test. Run after `npm run bundle`, optionally with the previous+ * published cli.js and a frozen native hn binary as the second and third arguments. All state,+ * launchers and requests stay in a disposable home and a guarded loopback fixture. */+import assert from 'node:assert/strict'+import { execFile } from 'node:child_process'+import { createHash } from 'node:crypto'+import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'+import { createServer } from 'node:http'+import { tmpdir } from 'node:os'+import { dirname, join, resolve } from 'node:path'+import { promisify } from 'node:util'++const run = promisify(execFile)+const candidate = resolve(process.argv[2] || 'dist/cli.js')+const previous = process.argv[3] && resolve(process.argv[3])+const native = process.argv[4] && resolve(process.argv[4])+const bytes = readFileSync(candidate)+const notify = readFileSync(join(dirname(candidate), 'notify.mjs'))+const root = mkdtempSync(join(tmpdir(), 'hn-upgrade-'))+const home = join(root, "home with ' quotes")+const cliDir = join(home, '.harness', 'cli')+const bin = join(home, '.local', 'bin')+const cli = join(cliDir, 'cli.js')+const harness = join(bin, 'harness')+const hn = join(bin, 'hn')+const prefix = `hn-upgrade-${process.pid}`+const port = 19449+assert(port >= 19440 && port <= 19449)+const base = `http://127.0.0.1:${port}`+const quote = value => `'${value.replace(/'/g, `'\\''`)}'`+const sha = data => createHash('sha256').update(data).digest('hex')+const tui = join(root, 'tui-fixture')+const recorder = join(root, 'record.mjs')+// Do not inherit auth, sockets, tmux, data directories or a real daemon's port.+const env = {+ HOME: home, PATH: `${bin}:${dirname(process.execPath)}:/usr/bin:/bin`,+ PORT: String(port), HN_SOCKET_NAME: prefix, HN_TMPDIR: root,+ HARNESS_TUI_BIN: tui, ADAPTER_UPDATE_DISABLE: 'true',+ ADAPTER_UPDATE_URL: `${base}/metadata.json`, HARNESS_STORE_CATALOG_URL: `${base}/catalog.json`,+ ADAPTER_RUNTIME_METADATA_URL: `${base}/runtime.json`, ADAPTER_GRID_RUNTIME_METADATA_URL: `${base}/grid.json`,+ SHELL: '/bin/sh', TERM: 'xterm-256color',+}+const options = { env, cwd: root, timeout: 20_000, encoding: 'utf8' }+const server = createServer()+let version+const requests = []+server.on('request', (request, response) => {+ requests.push(request.url)+ if (request.url === '/metadata.json') {+ response.end(JSON.stringify({ cli: {+ version,+ cli: { url: `${base}/cli.js`, sha256: sha(bytes), size: bytes.length },+ notify: { url: `${base}/notify.mjs`, sha256: sha(notify), size: notify.length },+ } }))+ } else if (request.url === '/cli.js') response.end(bytes)+ else if (request.url === '/notify.mjs') response.end(notify)+ else { response.statusCode = 404; response.end() }+})++try {+ for (const dir of [cliDir, bin]) mkdirSync(dir, { recursive: true })+ writeFileSync(join(cliDir, 'package.json'), '{"type":"module"}\n')+ copyFileSync(previous || candidate, cli)+ writeFileSync(join(cliDir, 'notify.mjs'), notify)+ writeFileSync(harness, `#!/bin/sh\nexport ADAPTER_UPDATE_DISABLE=true\nexec ${quote(process.execPath)} ${quote(cli)} "$@"\n`, { mode: 0o755 })+ writeFileSync(recorder, 'console.log(JSON.stringify({args:process.argv.slice(2),home:process.env.HOME,port:process.env.PORT,socket:process.env.HN_SOCKET_NAME,pin:process.env.ADAPTER_UPDATE_DISABLE}))\n')+ writeFileSync(tui, `#!/bin/sh\nexec ${quote(process.execPath)} ${quote(recorder)} "$@"\n`, { mode: 0o755 })+ version = (await run(process.execPath, [candidate, 'version'], options)).stdout.trim()+ assert.match(version, /^\d+\.\d+\.\d+/)+ assert(!existsSync(hn), 'running a checkout must not migrate the installed copy')+ await new Promise((done, reject) => { server.once('error', reject); server.listen(port, '127.0.0.1', done) })++ if (previous) {+ const oldVersion = (await run(harness, ['version'], options)).stdout.trim()+ assert(!existsSync(hn), 'previous release fixture must predate launcher repair')+ const nextVersion = version+ version = oldVersion+ const alreadyCurrent = await run(harness, ['update'], options)+ assert(alreadyCurrent.stdout.includes(`Already on the latest version (v${oldVersion})`))+ assert(!existsSync(hn), 'reproduce the missing command after an already-current update')+ version = nextVersion+ console.log('PASS reproduced missing hn on the already-current previous release')+ const update = await run(harness, ['update'], options)+ assert(update.stdout.includes(`installed v${version}`), update.stdout)+ assert.equal(sha(readFileSync(cli)), sha(bytes))+ assert(!existsSync(hn), 'a staging canary must not migrate the live installation')+ console.log(`PASS published CLI ${oldVersion} stages ${version} with its original updater`)+ }++ // The first command on the new bundle also covers a machine already on the latest version.+ const current = await run(harness, ['update'], options)+ assert(current.stdout.includes(`Already on the latest version (v${version})`), current.stdout)+ assert(existsSync(hn), 'an already-current update must add the missing hn command')+ const args = ['-L', prefix, '--port', String(port), '--version']+ const launched = JSON.parse((await run(hn, args, options)).stdout)+ assert.deepEqual(launched, { args, home, port: String(port), socket: prefix, pin: 'true' })+ assert.equal(readFileSync(hn, 'utf8'), `#!/bin/sh\nexec ${quote(harness)} tui "$@"\n`)+ console.log('PASS already-current update creates hn; installed command preserves arguments, home and pin')++ rmSync(hn)+ await Promise.all(Array.from({ length: 8 }, () => run(harness, ['version'], options)))+ assert.equal(lstatSync(hn).mode & 0o100, 0o100)+ assert.deepEqual(readdirSync(bin).sort(), ['harness', 'hn'])+ console.log('PASS concurrent CLI starts publish one complete launcher and clean staging files')++ rmSync(hn)+ const other = join(root, 'unrelated-hn')+ writeFileSync(other, 'unrelated command\n')+ symlinkSync(other, hn)+ await run(harness, ['update'], options)+ assert.equal(readlinkSync(hn), other)+ assert.equal(readFileSync(other, 'utf8'), 'unrelated command\n')+ console.log('PASS an existing hn symlink and its target remain unchanged')++ if (native) {+ rmSync(hn)+ await run(harness, ['version'], options)+ const output = (await run(hn, args, { ...options, env: { ...env, HARNESS_TUI_BIN: native } })).stdout.trim()+ assert.match(output, /^hn \d+\.\d+\.\d+ \(tmux /)+ console.log(`PASS repaired hn launcher runs the frozen native release: ${output}`)+ }+ assert(requests.every(url => ['/metadata.json', '/cli.js', '/notify.mjs'].includes(url)), JSON.stringify(requests))+} finally {+ server.closeAllConnections()+ if (server.listening) await new Promise(done => server.close(done))+ rmSync(root, { recursive: true, force: true })+}diff --git a/cli/src/cli.ts b/cli/src/cli.tsindex 8b39b2d1a..afd291c28 100644--- a/cli/src/cli.ts+++ b/cli/src/cli.ts@@ -227,7 +227,7 @@ import {type Poller, type UpdateEntry,} from './lib/selfUpdate.js'import { managedNodePath } from './lib/nodeRuntime.js'-import { ensureLauncher, ensureManagedGrid, ensureManagedRuntime, startGridPinRecheck } from './lib/runtimeInstall.js'+import { ensureHnLauncher, ensureLauncher, ensureManagedGrid, ensureManagedRuntime, startGridPinRecheck } from './lib/runtimeInstall.js'import { readdir, stat } from 'fs/promises'import { CodexNormalizer, codexTaskError, lastCodexTurnText } from './engines/codex/normalizer.js'import { codexSubagentResolverFor } from './engines/codex/subagent.js'@@ -488,6 +488,7 @@ function tildify(p: string): string {/** The currently-running script — dist/cli.js when built, src/cli.ts under tsx. */const SCRIPT_PATH = fileURLToPath(import.meta.url)+ensureHnLauncher(SCRIPT_PATH)/*** Start the daemon that succeeds this one, on whatever bytes are in `~/.harness/cli` right now.diff --git a/cli/src/cliCommand.spec.ts b/cli/src/cliCommand.spec.tsindex 114134238..798022bc7 100644--- a/cli/src/cliCommand.spec.ts+++ b/cli/src/cliCommand.spec.ts@@ -118,7 +118,8 @@ describe('CLI login/start command contract', () => {cwd: CLI_ROOT,detached: true,env: envFor(root, {- PORT: String(20_000 + Math.floor(Math.random() * 20_000)),+ // The kernel reserves a free port atomically; a random choice can hit another test.+ PORT: '0',DISABLE_HOOK_INSTALL: 'true', CABLE_DISABLE: 'true', DISABLE_GRID_INSTALL: 'true',// Startup's sign-in contract does not need a runtime download or the developer's Grid.HARNESS_GRID_BIN: join(root, 'grid-unavailable'),diff --git a/cli/src/lib/runtimeInstall.spec.ts b/cli/src/lib/runtimeInstall.spec.tsindex 373b7c78b..7552fbd55 100644--- a/cli/src/lib/runtimeInstall.spec.ts+++ b/cli/src/lib/runtimeInstall.spec.ts@@ -1,7 +1,7 @@import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'import { execFileSync } from 'node:child_process'import { createHash } from 'node:crypto'-import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs'import { dirname, join } from 'node:path'import { tmpdir } from 'node:os'@@ -506,3 +506,87 @@ describe('ensureLauncher', () => {expect(existsSync(launcherPath())).toBe(false)})})++describe('hn launcher migration', () => {+ const quote = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`+ const cliPath = () => join(cliDir, 'cli.js')+ const harnessPath = () => join(binDir, 'harness')+ const hnPath = () => join(binDir, 'hn')++ beforeEach(() => {+ root = mkdtempSync(join(tmpdir(), "harness launcher's "))+ runtimeDir = join(root, '.harness', 'runtime')+ binDir = join(root, '.local', 'bin')+ cliDir = join(root, '.harness', 'cli')+ for (const dir of [runtimeDir, binDir, cliDir]) mkdirSync(dir, { recursive: true })+ writeFileSync(join(cliDir, 'package.json'), '{"type":"module"}')+ writeFileSync(cliPath(), 'console.log(JSON.stringify({args:process.argv.slice(2),pin:process.env.ADAPTER_UPDATE_DISABLE}))')+ writeFileSync(harnessPath(), `#!/bin/sh\nexport ADAPTER_UPDATE_DISABLE=true\nexec ${quote(process.execPath)} ${quote(cliPath())} "$@"\n`, { mode: 0o755 })+ })++ afterEach(() => {+ chmodSync(binDir, 0o755)+ rmSync(root, { recursive: true, force: true })+ for (const key of ['ADAPTER_RUNTIME_DIR', 'HARNESS_BIN_DIR', 'ADAPTER_CLI_DIR', 'ADAPTER_RUNTIME_METADATA_URL', 'ADAPTER_GRID_RUNTIME_METADATA_URL']) delete process.env[key]+ })++ it('upgrades an old install with a working hn command, preserving quoted arguments and its update pin', async () => {+ const { ensureHnLauncher } = await load()+ expect(ensureHnLauncher(cliPath())).toBe(true)+ const args = ['-L', 'hn-upgrade-unit', '--port', '19448', '--version', 'a b', "a'b", '$(false)']+ const childEnv: NodeJS.ProcessEnv = { ...process.env, HOME: root, PORT: '19448', HN_SOCKET_NAME: 'hn-upgrade-unit' }+ for (const key of ['TMUX', 'TMUX_PANE', 'HN_SOCKET']) delete childEnv[key]+ const result = JSON.parse(execFileSync(hnPath(), args, { env: childEnv, encoding: 'utf8' }))+ expect(result).toEqual({ args: ['tui', ...args], pin: 'true' })+ const inode = statSync(hnPath()).ino+ expect(ensureHnLauncher(cliPath())).toBe(false)+ expect(statSync(hnPath()).ino).toBe(inode)+ expect(readdirSync(binDir).sort()).toEqual(['harness', 'hn'])+ })++ it.each(['file', 'symlink', 'dangling symlink'])('preserves an existing hn %s', async (kind) => {+ const target = join(root, 'other-hn')+ if (kind !== 'dangling symlink') writeFileSync(target, 'another program')+ if (kind === 'file') writeFileSync(hnPath(), 'another program')+ else symlinkSync(target, hnPath())+ const { ensureHnLauncher } = await load()+ expect(ensureHnLauncher(cliPath())).toBe(false)+ if (kind === 'file') expect(readFileSync(hnPath(), 'utf8')).toBe('another program')+ else expect(readlinkSync(hnPath())).toBe(target)+ if (kind !== 'dangling symlink') expect(readFileSync(target, 'utf8')).toBe('another program')+ else expect(existsSync(target)).toBe(false)+ })++ it('does not migrate an installed copy while running a checkout or update canary', async () => {+ const { ensureHnLauncher } = await load()+ for (const other of [join(root, 'checkout', 'dist', 'cli.js'), join(cliDir, '.canary-test', 'cli.js')]) {+ mkdirSync(dirname(other), { recursive: true })+ writeFileSync(other, readFileSync(cliPath()))+ expect(ensureHnLauncher(other)).toBe(false)+ expect(existsSync(hnPath())).toBe(false)+ }+ })++ it('recognizes the installed bundle through a symlink', async () => {+ const alias = join(root, 'cli-link.js')+ symlinkSync(cliPath(), alias)+ const { ensureHnLauncher } = await load()+ expect(ensureHnLauncher(alias)).toBe(true)+ })++ it.each(['missing', 'foreign', 'not executable'])('leaves a %s harness launcher alone', async (kind) => {+ if (kind === 'missing') rmSync(harnessPath())+ else if (kind === 'foreign') writeFileSync(harnessPath(), '#!/bin/sh\nexec another-command "$@"\n')+ else chmodSync(harnessPath(), 0o644)+ const { ensureHnLauncher } = await load()+ expect(ensureHnLauncher(cliPath())).toBe(false)+ expect(existsSync(hnPath())).toBe(false)+ })++ it.skipIf(process.getuid?.() === 0)('tolerates an unwritable bin directory', async () => {+ const { ensureHnLauncher } = await load()+ chmodSync(binDir, 0o555)+ expect(ensureHnLauncher(cliPath())).toBe(false)+ expect(existsSync(hnPath())).toBe(false)+ })+})diff --git a/cli/src/lib/runtimeInstall.ts b/cli/src/lib/runtimeInstall.tsindex 1053e7923..c5d56db82 100644--- a/cli/src/lib/runtimeInstall.ts+++ b/cli/src/lib/runtimeInstall.ts@@ -1,5 +1,5 @@import { execFileSync } from 'node:child_process'-import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'+import { accessSync, chmodSync, constants, existsSync, linkSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs'import { dirname, join, sep } from 'node:path'import { env } from '../config/env.js'@@ -308,6 +308,43 @@ export function ensureLauncher(node: string, log: (message: string) => void = ()}}+/**+ * Add the short terminal command to an existing installation. Self-update replaces only the JS+ * bundles, so machines installed before hn shipped never re-run the installer's launcher step.+ * Run this on entry to the installed bundle, including daemon handoffs and an already-current+ * `harness update`. A checkout or update canary must never change the real installation.+ *+ * Delegate through the existing harness launcher so runtime repairs and --no-updates pins apply+ * equally to hn. Publish the complete script without replacing any existing file or symlink.+ */+export function ensureHnLauncher(scriptPath: string): boolean {+ let temporary: string | undefined+ try {+ const cli = join(env.ADAPTER_CLI_DIR, 'cli.js')+ if (realpathSync(scriptPath) !== realpathSync(cli)) return false+ const hn = join(env.HARNESS_BIN_DIR, 'hn')+ try { lstatSync(hn); return false } catch (error) {+ if ((error as NodeJS.ErrnoException).code !== 'ENOENT') return false+ }+ const launcher = join(env.HARNESS_BIN_DIR, 'harness')+ accessSync(launcher, constants.X_OK)+ const exec = EXEC_LINE.exec(readFileSync(launcher, 'utf8'))+ if (!exec || !(exec[0].includes(cli) || exec[0].includes(shellQuote(cli)))) return false++ temporary = mkdtempSync(join(env.HARNESS_BIN_DIR, '.hn-'))+ const staged = join(temporary, 'hn')+ writeFileSync(staged, `#!/bin/sh\nexec ${shellQuote(launcher)} tui "$@"\n`, { mode: 0o755 })+ // link, unlike rename, fails if another process or the user has already created hn.+ linkSync(staged, hn)+ return true+ } catch {+ // A read-only bin dir or a racing install must not prevent the CLI or daemon from running.+ return false+ } finally {+ if (temporary) { try { rmSync(temporary, { recursive: true, force: true }) } catch { /* best effort */ } }+ }+}+function shellQuote(value: string): string {return `'${value.replace(/'/g, `'\\''`)}'`}diff --git a/docs/research/2026-09-28-hn-release-race.md b/docs/research/2026-09-28-hn-release-race.mdindex 8549da7ef..bf751d4f5 100644--- a/docs/research/2026-09-28-hn-release-race.md+++ b/docs/research/2026-09-28-hn-release-race.md@@ -1,4 +1,4 @@-# hn release candidate: concurrent window creation+# hn 0.1.1 release: concurrent window creationA fresh check of the merged hn source found a real asynchronous creation race.[CI run 36384795117](https://github.com/autonomous-ai/openharness/actions/runs/36384795117)@@ -54,5 +54,47 @@ Local verification passed:These tests use frozen copies, disposable homes, guarded ports, explicit hn andtmux sockets, and cleanup of their own processes. They do not use a real daemon,real harnesses, default servers or the installed hn. The creature remains outside-the TUI. Linux CI and publication are separate gates recorded on the release PR-and workflow runs; this document records the correction and local evidence.+the TUI. The publication checks and outcome are recorded below.+++## Published release++[PR #413](https://github.com/autonomous-ai/openharness/pull/413) was squash-merged+at `610eb989313009d036c9fd7520382af972139142`. Its tree exactly matches the tested+candidate `d14b09f64f6af47653559a5b3699b498da2bff3d`.++- [Final CI](https://github.com/autonomous-ai/openharness/actions/runs/36387140310):+ all four jobs passed, including static Linux x86-64/ARM64 builds and integration+ suites, the full CLI suite and coverage gate, and backend compatibility.+- [hn 0.1.1](https://github.com/autonomous-ai/openharness/releases/tag/v0.1.1_tui):+ [release run 36389263332](https://github.com/autonomous-ai/openharness/actions/runs/36389263332)+ passed its tests, all four platform builds, and publication.+- [CLI 0.3.21](https://github.com/autonomous-ai/openharness/releases/tag/v0.3.21_cli):+ [release run 36390063621](https://github.com/autonomous-ai/openharness/actions/runs/36390063621)+ passed bundle publication, downloaded checksum/version checks, installer CDN+ byte verification, and GitHub release publication.++All four hn binaries were downloaded from the public manifest and matched its+SHA-256 values. The GitHub release assets have the same digests. The downloaded+macOS ARM64 binary reported `hn 0.1.1 (tmux 3.5a)`.++| Platform | Published SHA-256 |+| --- | --- |+| macOS ARM64 | `fdc31b129738e24d5722ea6ac7d59fa5b04ab927ef07a4512d80c0de6617edc1` |+| macOS x86-64 | `9f24b991183faba34372c3980cff2e74578dc47a5eb46b0e5554b9a9d327a6e0` |+| Linux ARM64 | `77006d8f87f638827df13386ecbd7b543ea185fb43f0117a2e74f4a43a782440` |+| Linux x86-64 | `bf9a1090badddeb726474875afbdb22b6976957c8520c65997912c24520a2061` |++The public CDN installer matched the released source, with SHA-256+`ae952b99a2a7d9ecf59642445183ad980e4a4976183f2882c2f7f7c8fad85a9b`.+A fresh macOS installation in a disposable home installed CLI 0.3.21 and hn 0.1.1.+The installed hn launcher created and drove a private native shell successfully.+The CLI's `harness tui --install` path was also verified in a second empty home+and downloaded the same binary. All owned runtime processes were cleaned up.++For the install smoke test only, hn and tmux version probes received explicit+private socket flags, and hn probes received the guarded port. The published+installer was not modified; its downloads, checksums, launchers and runtime+installation logic were exercised unchanged. No existing hn installation or real+daemon was changed. Fresh-install validation was on macOS; Linux runtime behavior+is covered by the two CI integration jobs above.diff --git a/docs/research/2026-09-28-hn-upgrade-launcher.md b/docs/research/2026-09-28-hn-upgrade-launcher.mdnew file mode 100644index 000000000..fd4e689cf--- /dev/null+++ b/docs/research/2026-09-28-hn-upgrade-launcher.md@@ -0,0 +1,52 @@+# hn launcher repair for existing installations++CLI 0.3.21 could report “Already on the latest version” while the shell reported+`hn: command not found`. The fresh installer wrote both launchers, but self-update+replaced only `cli.js` and `notify.mjs`. Installations created before hn shipped+never received its launcher.++The installed CLI now adds a missing `hn` command on entry. This includes daemon+handoffs after automatic updates and commands such as `harness update`, even when+there is no newer bundle. The script delegates to the existing `harness` launcher+with `tui`, preserving its managed Node runtime and any `--no-updates` pin.++The migration checks that it is running the installed bundle and that the+existing executable harness launcher names that bundle. Checkout builds and+staging canaries do not migrate the installation. A complete script is published+with an exclusive hard link, so concurrent invocations cannot truncate it or+replace an existing file or symlink. A read-only directory does not prevent the+CLI or daemon from starting.++An old updater whose daemon is stopped only stages the new bundle; the migration+runs when the new CLI is first invoked. `harness version` suffices. A running+daemon invokes the new bundle during its normal update handoff.++## Regression check++After building the bundle in `cli/`:++```sh+npm run typecheck+npm test+npm run bundle+node scripts/test-hn-upgrade.mjs+```++CI runs the packaged regression check. It uses a disposable home with spaces and+an apostrophe, an existing harness launcher, a loopback update manifest on guarded+port 19449, and a recording TUI fixture. It checks the already-current update,+argument and update-pin preservation, concurrent starts, and an existing hn+symlink. All owned files and the HTTP fixture are removed afterward.++For a real upgrade comparison, provide a saved previous release bundle and an+optional frozen native hn binary:++```sh+node scripts/test-hn-upgrade.mjs dist/cli.js /tmp/previous-cli.js /tmp/frozen-hn+```++This additionally reproduces the previous release's missing command after an+already-current update, exercises its original download/checksum/canary/staging+path, and runs the repaired launcher against the frozen native binary. Every+native invocation has a disposable home, explicit socket prefix and port; no+real daemon, harness or installed hn is used.