Skip to content

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.

fix(cli): install the hn command for existing users (#417)

Deed3ce52b1496e
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 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 coverage
run: npm run test:dsh-updates
diff --git a/cli/scripts/test-hn-upgrade.mjs b/cli/scripts/test-hn-upgrade.mjs
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.md
index 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 creation
A 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 and
tmux 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.md
new file mode 100644
index 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.