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
import { fork, spawn, spawnSync } from "child_process";
import { join } from "path";
import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, rmSync, statSync, symlinkSync, writeFileSync } from "fs";
import { tmpdir } from "os";
import { describe, expect, it, vi } from "vitest";
// vitest runs from cli/, so this is cli/scripts/install.sh — the file published to the CDN.
const installer = join(process.cwd(), "scripts", "install.sh");
// Every test here runs the real installer under /bin/sh, with fake commands it writes fresh. On macOS the
// first run of a freshly written executable waits on the system's check of it: 220 ms at a load of 100,
// 600 ms with 12 busy loops more, against 16 ms for one already run (2026-10-06). A test runs up to a
// dozen of them, and vitest's 5 s timed out 11 of these tests in one loaded unit run. The tests that
// already set 20 s did so for the same reason.
vi.setConfig({ testTimeout: 20_000 });
describe('installer interrupted downloads', () => {
it('recovers real truncated HTTP responses without mixing manifest or binary bytes', async () => {
const { createServer } = await import('node:http');
const scratch = mkdtempSync(join(tmpdir(), 'harness-download-http-'));
const bytes = Buffer.from([0, 1, 255, 10, 2, 0, 42, 128]);
const counts = new Map<string, number>();
const server = createServer((req, res) => {
const route = req.url!;
const count = (counts.get(route) ?? 0) + 1;
counts.set(route, count);
const body = route === '/manifest' ? Buffer.from('{"version":"verified"}') : bytes;
res.writeHead(200, { 'Content-Length': body.length, 'Connection': 'close' });
res.end(count < 3 ? body.subarray(0, 3) : body);
});
try {
await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve));
const port = (server.address() as { port: number }).port;
const source = readFileSync(installer, 'utf8');
const fn = source.slice(source.indexOf('download() {'), source.indexOf('# sha256 is'));
const child = spawn('/bin/sh', ['-ec', fn + '\ndownload "$URL/manifest"\ndownload "$URL/binary" -o "$TARGET"'], {
env: { ...process.env, URL: `http://127.0.0.1:${port}`, TARGET: join(scratch, 'binary') },
});
let stdout = '', stderr = '';
child.stdout.on('data', data => { stdout += data });
child.stderr.on('data', data => { stderr += data });
const code = await new Promise<number | null>((resolve, reject) => {
child.on('error', reject); child.on('close', resolve);
});
expect(code, stderr).toBe(0);
expect(JSON.parse(stdout)).toEqual({ version: 'verified' });
expect(readFileSync(join(scratch, 'binary'))).toEqual(bytes);
// Only the two paths the installer asked for. A loopback server is open to every process on the
// machine, and on a busy one something probed it with GET /v1/models mid-test (release check,
// 2026-10-06), which is not the installer's doing.
expect({ '/manifest': counts.get('/manifest'), '/binary': counts.get('/binary') }).toEqual({ '/manifest': 3, '/binary': 3 });
} finally {
server.closeAllConnections();
await new Promise<void>(resolve => server.close(() => resolve()));
rmSync(scratch, { recursive: true, force: true });
}
}, 30_000);
it.each([6, 7, 18, 28, 35, 52, 55, 56, 92])('retries curl error %i and discards partial manifest output', code => {
const scratch = mkdtempSync(join(tmpdir(), 'harness-download-'));
try {
writeCommand(scratch, 'curl', [
'n=0; [ ! -f "$COUNT" ] || n=$(cat "$COUNT")',
'n=$((n + 1)); echo "$n" > "$COUNT"',
`if [ "$n" -lt 3 ]; then printf 'broken partial JSON'; exit ${code}; fi`,
'printf \'{"version":"test"}\\n\'',
]);
writeCommand(scratch, 'sleep', ['exit 0']);
const source = readFileSync(installer, 'utf8');
const fn = source.slice(source.indexOf('download() {'), source.indexOf('# sha256 is'));
const result = spawnSync('/bin/sh', ['-c', fn + '\ndownload https://example.invalid/manifest'], {
encoding: 'utf8', env: { ...process.env, PATH: `${scratch}:/usr/bin:/bin`, COUNT: join(scratch, 'count') },
});
expect(result.status).toBe(0);
expect(JSON.parse(result.stdout)).toEqual({ version: 'test' });
expect(readFileSync(join(scratch, 'count'), 'utf8').trim()).toBe('3');
expect(result.stderr).toContain('retrying download (3/3)');
} finally { rmSync(scratch, { recursive: true, force: true }); }
});
it.each([[35, 3], [22, 1], [60, 1], [23, 1]])('bounds failures and preserves curl status %i', (code, attempts) => {
const scratch = mkdtempSync(join(tmpdir(), 'harness-download-fail-'));
try {
writeCommand(scratch, 'curl', [
'echo "$*" >> "$CALLS"', `printf partial; exit ${code}`,
]);
writeCommand(scratch, 'sleep', ['exit 0']);
const source = readFileSync(installer, 'utf8');
const fn = source.slice(source.indexOf('download() {'), source.indexOf('# sha256 is'));
const result = spawnSync('/bin/sh', ['-c', fn + '\ndownload https://example.invalid/runtime -o "$TARGET"'], {
encoding: 'utf8', env: { ...process.env, PATH: `${scratch}:/usr/bin:/bin`,
CALLS: join(scratch, 'calls'), TARGET: join(scratch, 'download') },
});
expect(result.status).toBe(code);
expect(result.stdout).toBe('');
const calls = readFileSync(join(scratch, 'calls'), 'utf8').trim().split('\n');
expect(calls).toHaveLength(attempts);
expect(calls[0]).toContain('--connect-timeout 20 --max-time 600');
expect(calls[0]).toContain(`-o ${join(scratch, 'download')}`);
} finally { rmSync(scratch, { recursive: true, force: true }); }
});
});
const writeCommand = (directory: string, name: string, lines: string[]) => {
const path = join(directory, name);
writeFileSync(path, ["#!/bin/sh", ...lines, ""].join("\n"));
chmodSync(path, 0o700);
};
// What the CLI runs on Linux besides tmux — the only other command step 1 asks about.
const writeLinuxHostCommands = (directory: string) => {
writeCommand(directory, "ps", ["exit 0"]);
};
// Step 1 of the script — the host-requirements ladder — as one runnable unit.
// From the constants (RUNTIME_DIR, BIN_DIR, the manifest URLs) through the whole host step.
const hostSetupOf = (source: string) =>
source.slice(source.indexOf('METADATA_URL="${HARNESS_METADATA_URL'), source.indexOf("# 2. Resolve the Node"));
// The download-tools check that guards the Node download, with the helpers it calls.
const downloadToolsOf = (source: string) =>
source.slice(source.indexOf('METADATA_URL="${HARNESS_METADATA_URL'), source.indexOf("tmux_runs()")) +
source.slice(
source.indexOf(" # Fetching, unpacking and verifying the runtime"),
source.indexOf(' echo "▸ Installing the Harness Node runtime'),
);
// Steps 5 and 6 — the verification, the wordmark and the guide, and the PATH reminder — as one
// runnable unit, from the constants down so BIN_DIR and LAUNCHER resolve the way they do in the script.
const finaleOf = (source: string) =>
source.slice(source.indexOf('METADATA_URL="${HARNESS_METADATA_URL'), source.indexOf("# Shared by every download")) +
source.slice(source.indexOf("# 5. Final verification"));
// A ~/.local/bin with a launcher that answers `version`, plus the node and tmux the verification runs.
const installedFixture = (scratch: string) => {
const home = join(scratch, "home");
const bin = join(home, ".local", "bin");
mkdirSync(bin, { recursive: true });
writeCommand(bin, "harness", ['[ "$1" = version ] && echo 0.2.60', "exit 0"]);
writeCommand(scratch, "node", ["exit 0"]);
writeCommand(scratch, "tmux", ['echo "tmux 3.7"']);
return { home, node: join(scratch, "node") };
};
/** What tells the installer an agent ran it: removed from this test's own environment, which may be an agent's. */
const AGENT_KEYS = ["CLAUDECODE", "CLAUDE_CODE_SESSION_ID", "CODEX_THREAD_ID", "AI_AGENT", "HARNESS_AGENT_SESSION"];
const runFinale = (mode: "standalone" | "desktop", pathHasBin: boolean, script = finaleOf, agent: Record<string, string> = {}) => {
const source = readFileSync(installer, "utf8");
const scratch = mkdtempSync(join(tmpdir(), "harness-finale-"));
try {
const { home, node } = installedFixture(scratch);
const bin = join(home, ".local", "bin");
return spawnSync("/bin/sh", ["-c", script(source)], {
encoding: "utf8",
env: {
...Object.fromEntries(Object.entries(process.env).filter(([key]) => !AGENT_KEYS.includes(key))),
...agent,
HOME: home,
INSTALL_MODE: mode,
NODE_BIN: node,
PATH: pathHasBin ? `${bin}:${scratch}:/usr/bin:/bin` : `${scratch}:/usr/bin:/bin`,
},
});
} finally {
rmSync(scratch, { recursive: true, force: true });
}
};
const LOGO = [
" _",
" | |__ __ _ _ __ _ __ ___ ___ ___",
" | '_ \\ / _` | '__| '_ \\ / _ \\/ __/ __|",
" | | | | (_| | | | | | | __/\\__ \\__ \\",
" |_| |_|\\__,_|_| |_| |_|\\___||___/___/",
];
describe("scripts/install.sh: what it says once it is done", () => {
it("ends with the wordmark and the guide — login, start, remote password, then harness remote — in that order", () => {
const result = runFinale("standalone", true);
expect(result.status).toBe(0);
const out = result.stdout;
for (const line of LOGO) expect(out).toContain(line);
expect(out).toContain("✓ harness 0.2.60 installed.");
const order = ["harness login", "harness start", "harness remote-password set", "harness remote ", "harness machines", "harness status", "harness --help"];
const at = order.map((command) => out.indexOf(command));
expect(at.every((index) => index >= 0)).toBe(true);
expect(at).toEqual([...at].sort((a, b) => a - b));
expect(out.indexOf(LOGO[1])).toBeLessThan(out.indexOf("harness login"));
// Every command is explained, and nothing is run: the fixture launcher only answered `version`.
expect(out).toContain("# 1. sign in");
expect(out).toContain("# 3. let your OTHER machines reach this one");
expect(out).not.toContain("'harness' is installed in ~/.local/bin");
}, 20_000);
it("the PATH reminder still comes after the guide when ~/.local/bin is not on PATH", () => {
const out = runFinale("standalone", false).stdout;
expect(out.indexOf("harness --help")).toBeLessThan(out.indexOf("'harness' is installed in ~/.local/bin"));
}, 20_000);
// The installer puts ~/.local/bin on its own PATH while it runs (the tmux step): the advice is about
// the terminal it runs in. Checked against its own, it never printed, and on a fresh Mac the `hn`
// it said to type was "command not found" (macOS VM, 2026-10-09).
const finaleAfterInstallOf = (source: string) =>
source.slice(source.indexOf('METADATA_URL="${HARNESS_METADATA_URL'), source.indexOf("# Shared by every download")) +
'export PATH="$BIN_DIR:$PATH"\n' +
source.slice(source.indexOf("# 5. Final verification"));
it("starts with a command this terminal can run, and says how to get `hn` by name, whatever the install did to its own PATH", () => {
const out = runFinale("standalone", false, finaleAfterInstallOf).stdout;
expect(out).toMatch(/^ {6}~\/\.local\/bin\/hn +# start locally; no login required$/m);
expect(out).toContain("'harness' is installed in ~/.local/bin");
const onPath = runFinale("standalone", true, finaleAfterInstallOf).stdout;
expect(onPath).toMatch(/^ {6}hn {29}# start locally; no login required$/m);
expect(onPath).not.toContain("'harness' is installed in ~/.local/bin");
}, 20_000);
it("tells an agent what to run next and what only the person can do, after the person's guide", () => {
const out = runFinale("standalone", true).stdout;
expect(out).toMatch(/^ {6}Next: harness start +\(starts Harness here; no account is needed\)$/m);
expect(out).toMatch(/^ {6}Then: harness whoami +\(whether you may start harnesses, and if not, what to ask the person\)$/m);
expect(out).toContain("harness login");
expect(out).toContain("harness settings agents-start-agents on");
expect(out).toContain("https://harness.autonomous.ai/agents");
// The person reads their guide first.
expect(out.indexOf("harness --help")).toBeLessThan(out.indexOf("Next: harness start"));
}, 20_000);
it("puts that first when an agent ran it, before the person's guide", () => {
for (const agent of [{ CLAUDECODE: "1" }, { CODEX_THREAD_ID: "t" }, { AI_AGENT: "cursor" }] as Array<Record<string, string>>) {
const out = runFinale("standalone", true, finaleOf, agent).stdout;
expect(out.indexOf("Next: harness start")).toBeGreaterThan(0);
expect(out.indexOf("Next: harness start")).toBeLessThan(out.indexOf("harness login "));
// Said once.
expect(out.split("Next: harness start")).toHaveLength(2);
}
}, 20_000);
it("desktop mode gets the one line and no guide: the app takes the person through sign-in", () => {
const out = runFinale("desktop", true).stdout;
expect(out).toContain("harness 0.2.60 installed.");
expect(out).not.toContain("Get started");
expect(out).not.toContain(LOGO[1]);
expect(out).not.toContain("Next: harness start");
}, 20_000);
});
describe("scripts/install.sh command contract", () => {
it("rejects a legacy machine-token argument before installing", () => {
const result = spawnSync("sh", [installer, "legacy-token"], { encoding: "utf8" });
expect(result.status).toBe(2);
expect(result.stderr).toContain("no longer accepts a machine token");
expect(result.stderr).toContain("harness login && harness start");
});
it("accepts only standalone default, explicit desktop mode or host mode", () => {
const source = readFileSync(installer, "utf8");
const parser = source.slice(0, source.indexOf('METADATA_URL='));
const standalone = spawnSync("/bin/sh", ["-s"], {
encoding: "utf8",
input: parser,
});
const desktop = spawnSync("/bin/sh", ["-s", "--", "--desktop"], {
encoding: "utf8",
input: parser,
});
const host = spawnSync("/bin/sh", ["-s", "--", "--host"], {
encoding: "utf8",
input: parser,
});
const extra = spawnSync(
"/bin/sh",
["-s", "--", "--desktop", "legacy-token"],
{ encoding: "utf8", input: parser },
);
expect(standalone.status).toBe(0);
expect(desktop.status).toBe(0);
expect(host.status).toBe(0);
expect(extra.status).toBe(2);
expect(extra.stderr).toContain("accepts no additional arguments");
});
it("accepts a desktop-supplied Node runtime and pins the launcher to it", () => {
const source = readFileSync(installer, "utf8");
expect(source).toContain('NODE_BIN="${HARNESS_NODE_BINARY:-}"');
expect(source).toContain('HARNESS_NODE_BINARY="$NODE_BIN"');
expect(source).toContain("const shellQuote");
expect(source).toContain("exec ' + shellQuote(NODE)");
});
// The CLI runs on the runtime under ~/.harness/runtime, never on whatever `node` PATH happens to
// resolve — the same rule the desktop app follows, so one cli.js is never driven by two Nodes.
it("installs its own Node runtime rather than requiring one", () => {
const source = readFileSync(installer, "utf8");
expect(source).toContain("harness/runtime/metadata.json");
expect(source).toContain('CURRENT_NODE_FILE="$RUNTIME_DIR/current-node"');
// The runtime is recorded for the desktop app to find, and only after it has answered.
expect(source).toContain('printf \'%s\\n\' "$NODE_BIN" > "$CURRENT_NODE_FILE"');
// No Node yet at that point, so the checksum has to be taken with the platform's own tool.
expect(source).toContain("shasum -a 256");
expect(source).toContain("sha256sum");
// The old behaviour — bail out and tell the user to go install Node — must not come back.
expect(source).not.toContain("brew install node");
expect(source).not.toContain("deb.nodesource.com");
});
it("refuses an unverified Node archive", () => {
const source = readFileSync(installer, "utf8");
expect(source).toContain('if [ "$node_got" != "$node_sha" ]; then');
expect(source).toContain("failed checksum verification");
});
it("prepares and verifies required tmux before installing Node or Harness", () => {
const source = readFileSync(installer, "utf8");
const tmuxStep = source.indexOf("# 1. Host requirements");
const nodeStep = source.indexOf("# 2. Resolve the Node");
const cliStep = source.indexOf("# 3. Fetch manifest");
expect(tmuxStep).toBeGreaterThan(-1);
expect(nodeStep).toBeGreaterThan(tmuxStep);
expect(cliStep).toBeGreaterThan(nodeStep);
expect(source).toContain("brew install tmux");
expect(source).toContain("install_managed_tmux");
expect(source).toContain("install_with_apt $missing_host_packages");
expect(source).toContain('if [ "$(id -u)" -eq 0 ]; then');
expect(source).toContain('sudo apt-get "$@"');
expect(source).not.toContain("sudo apt-get update &&");
expect(source).toContain("tmux is required but did not pass verification");
expect(source).toContain("exit 22");
// Obtaining tmux never needs a compiler, Xcode or the Homebrew installer any more.
expect(source).not.toContain("xcrun");
expect(source).not.toContain("xcode-select");
expect(source).not.toContain("Homebrew/install/HEAD/install.sh");
expect(source).not.toContain("exit 20");
expect(source).not.toContain("exit 21");
});
// The ladder, in source order: tmux is asked about first, Homebrew used only when tmux is missing
// and Homebrew is already there, the managed build for everything else.
it("asks about Homebrew only without tmux, and downloads the managed build without Homebrew", () => {
const source = readFileSync(installer, "utf8");
const hostStep = source.slice(source.indexOf("# 1. Host requirements"));
const darwin = hostStep.slice(hostStep.indexOf(" Darwin)"), hostStep.indexOf(" Linux)"));
const tmuxCheck = darwin.indexOf("if tmux_runs; then");
const brewCheck = darwin.indexOf("if command -v brew >/dev/null 2>&1; then");
const managed = darwin.indexOf("tmux_runs || install_managed_tmux");
expect(tmuxCheck).toBeGreaterThan(-1);
expect(brewCheck).toBeGreaterThan(tmuxCheck);
expect(managed).toBeGreaterThan(brewCheck);
// The managed archive is checksum-pinned by the manifest and recorded for the daemon.
expect(source).toContain("harness/runtime/tmux/metadata.json");
expect(source).toContain('CURRENT_TMUX_FILE="$RUNTIME_DIR/current-tmux"');
expect(source).toContain("tmux download failed checksum verification");
expect(source).toContain('ln -sfn "$tmux_target/bin/tmux" "$BIN_DIR/tmux"');
});
it("does nothing on a Mac that already runs tmux", () => {
const source = readFileSync(installer, "utf8");
const hostSetup = hostSetupOf(source);
const scratch = mkdtempSync(join(tmpdir(), "harness-mac-tmux-"));
const invoked = join(scratch, "brew-invoked");
try {
writeCommand(scratch, "uname", ["printf 'Darwin\\n'"]);
writeCommand(scratch, "tmux", ["printf 'tmux 3.6\\n'"]);
writeCommand(scratch, "brew", [`: > '${invoked}'`, "exit 99"]);
writeCommand(scratch, "sudo", [`: > '${invoked}'`, "exit 99"]);
writeCommand(scratch, "xcode-select", [`: > '${invoked}'`, "exit 99"]);
const result = spawnSync("/bin/sh", ["-c", hostSetup], {
encoding: "utf8",
env: { ...process.env, INSTALL_MODE: "standalone", PATH: scratch },
});
expect(result.status).toBe(0);
expect(result.stdout).toContain("tmux ready");
expect(result.stdout).not.toContain("Homebrew");
expect(() => readFileSync(invoked, "utf8")).toThrow();
} finally {
rmSync(scratch, { recursive: true, force: true });
}
});
it("installs tmux with an existing Homebrew and never fetches the managed build", () => {
const source = readFileSync(installer, "utf8");
const hostSetup = hostSetupOf(source);
const scratch = mkdtempSync(join(tmpdir(), "harness-mac-brew-"));
const invocations = join(scratch, "brew-invocations");
const fetched = join(scratch, "curl-invoked");
const fakeTmux = join(scratch, "tmux");
try {
writeCommand(scratch, "uname", ["printf 'Darwin\\n'"]);
writeCommand(scratch, "brew", [
`printf '%s\\n' "$*" >> '${invocations}'`,
`if [ "$1" = "shellenv" ]; then exit 0; fi`,
`printf '%s\\n' '#!/bin/sh' 'printf "tmux 3.7c\\\\n"' > '${fakeTmux}'`,
`/bin/chmod 700 '${fakeTmux}'`,
]);
writeCommand(scratch, "curl", [`: > '${fetched}'`, "exit 99"]);
const result = spawnSync("/bin/sh", ["-c", hostSetup], {
encoding: "utf8",
env: {
...process.env,
INSTALL_MODE: "standalone",
PATH: scratch,
HARNESS_HOMEBREW_PREFIXES: join(scratch, "no-homebrew"),
},
});
expect(result.status).toBe(0);
expect(readFileSync(invocations, "utf8")).toContain("install --force-bottle tmux\n");
expect(result.stdout).not.toContain("managed");
expect(() => readFileSync(fetched, "utf8")).toThrow();
} finally {
rmSync(scratch, { recursive: true, force: true });
}
});
it("finds Homebrew tmux and creates the first pane without changing its worker PATH", async () => {
const workerPath = process.env.PATH;
const exercise = async () => {
const scratch = mkdtempSync(join(tmpdir(), "harness-mac-brew-daemon-"));
const home = join(scratch, "home");
const prefix = join(scratch, "homebrew");
const bin = join(prefix, "bin");
mkdirSync(home);
mkdirSync(bin, { recursive: true });
try {
writeCommand(scratch, "uname", ["printf 'Darwin\\n'"]);
writeCommand(bin, "brew", [
`if [ "$1" = shellenv ]; then printf 'export PATH="${bin}:$PATH"\\n'; fi`,
"exit 0",
]);
writeCommand(bin, "tmux", [
'case "$1" in -V) printf "tmux 3.7c\\n" ;; new-session) printf "%%0\\n" ;; esac',
]);
const daemonEnv = { HOME: home, PATH: scratch, HARNESS_HOMEBREW_PREFIXES: prefix };
const installed = spawnSync("/bin/sh", ["-c", hostSetupOf(readFileSync(installer, "utf8"))], {
encoding: "utf8", env: { ...daemonEnv, INSTALL_MODE: "standalone" },
});
expect(installed.status, installed.stderr).toBe(0);
expect(installed.stdout).toContain("tmux ready (tmux 3.7c)");
expect(existsSync(join(home, ".harness/runtime/current-tmux"))).toBe(false);
// Found by QA on a quiet machine: a timed-out probe must not change later fixtures' PATH.
// This is the daemon's environment after the installer exits, so give it its own process.
const probe = await new Promise<Record<string, unknown>>((resolve, reject) => {
const child = fork(join(process.cwd(), "src/testing/installerTmuxProbe.ts"), [], {
execArgv: ["--import", "tsx"],
env: { ...process.env, ...daemonEnv },
silent: true,
// A node with tsx compiling the backend's modules, then two tmux creates through fresh fakes:
// seconds on a loaded machine (see the timeout above), never 5 s of a quiet one.
timeout: 15_000,
});
let response: Record<string, unknown> | undefined;
let stderr = "";
child.stderr!.on("data", data => { stderr += data; });
child.on("message", message => { response = message as Record<string, unknown>; });
child.once("error", reject);
child.once("close", (code, signal) => {
if (code === 0 && response) resolve(response);
else reject(new Error(`installer daemon probe exited ${code ?? signal}: ${stderr}`));
});
});
expect(probe.before).toMatchObject({ state: "failed", reason: "tmux is unavailable" });
expect(probe.adopted).toMatchObject({ state: "adopted" });
expect(probe.after).toMatchObject({
state: "succeeded", runtime: { backend: "tmux", paneId: "%0" },
});
} finally {
rmSync(scratch, { recursive: true, force: true });
}
};
const pending = exercise();
try {
// Found by QA on a quiet machine: a timed-out probe poisoned PATH for later fixtures.
expect(process.env.PATH).toBe(workerPath);
} finally { await pending; }
});
// A fake CDN: `curl -o` writes the archive, plain `curl` prints the manifest. The archive wraps a
// fake tmux so the whole managed path — fetch, verify, unpack, record, link — runs for real.
const managedFixture = (scratch: string, tamperSha = false) => {
const home = join(scratch, "home");
const root = "tmux-9.9-darwin-arm64";
const stage = join(scratch, "stage", root, "bin");
mkdirSync(stage, { recursive: true });
writeCommand(stage, "tmux", ["printf 'tmux 9.9\\n'"]);
const archive = join(scratch, `${root}.tar.gz`);
spawnSync("tar", ["-czf", archive, "-C", join(scratch, "stage"), root]);
const sha = spawnSync("shasum", ["-a", "256", archive], { encoding: "utf8" }).stdout.split(" ")[0];
const manifest = JSON.stringify({
tmux: {
"darwin-arm64": {
version: "9.9",
url: "https://cdn.example/tmux.tar.gz",
sha256: tamperSha ? "0".repeat(64) : sha,
size: 1,
archiveRoot: root,
},
},
}, null, 2);
writeFileSync(join(scratch, "manifest.json"), manifest);
// The ladder's first rung is `command -v tmux && tmux -V`, and PATH below still includes /usr/bin
// — where ubuntu-latest (CI) ships a real tmux 3.4, so on that runner the script found it, said
// "tmux ready (tmux 3.4)" and never took the managed path these tests exist for. A broken tmux
// in the fixture dir (first on PATH) fails that rung everywhere; once the managed build is
// linked, the script puts BIN_DIR ahead of PATH, so the 9.9 fake wins from then on.
writeCommand(scratch, "tmux", ["exit 127"]);
writeCommand(scratch, "curl", [
`printf '%s\\n' "$*" >> '${join(scratch, "curl-invocations")}'`,
`case "$*" in *"-o "*) cp '${archive}' "$4" ;; *) cat '${join(scratch, "manifest.json")}' ;; esac`,
]);
writeCommand(scratch, "uname", [`if [ "$1" = "-m" ]; then printf 'arm64\\n'; else printf 'Darwin\\n'; fi`]);
mkdirSync(home, { recursive: true });
return { home, root };
};
it("downloads, verifies and links the managed tmux when there is no Homebrew", () => {
const source = readFileSync(installer, "utf8");
const hostSetup = hostSetupOf(source);
const scratch = mkdtempSync(join(tmpdir(), "harness-mac-managed-"));
try {
const { home, root } = managedFixture(scratch);
const result = spawnSync("/bin/sh", ["-c", hostSetup], {
encoding: "utf8",
env: {
...process.env,
HOME: home,
INSTALL_MODE: "standalone",
// Only stock tools beyond the fakes: no brew, no tmux — and the fakes win.
PATH: `${scratch}:/usr/bin:/bin`,
HARNESS_TMUX_METADATA_URL: "https://cdn.example/manifest.json",
HARNESS_HOMEBREW_PREFIXES: join(scratch, "no-homebrew"),
},
});
expect(result.status).toBe(0);
expect(result.stdout).toContain("downloading tmux 9.9 (darwin-arm64)");
expect(result.stdout).toContain("tmux ready (tmux 9.9)");
const binary = join(home, ".harness", "runtime", root, "bin", "tmux");
expect(readFileSync(join(home, ".harness", "runtime", "current-tmux"), "utf8").trim()).toBe(binary);
expect(readlinkSync(join(home, ".local", "bin", "tmux"))).toBe(binary);
expect(readFileSync(join(scratch, "curl-invocations"), "utf8")).toContain("https://cdn.example/manifest.json");
} finally {
rmSync(scratch, { recursive: true, force: true });
}
}, 20_000);
it("refuses a managed tmux whose checksum does not match, and links nothing", () => {
const source = readFileSync(installer, "utf8");
const hostSetup = hostSetupOf(source);
const scratch = mkdtempSync(join(tmpdir(), "harness-mac-managed-bad-"));
try {
const { home } = managedFixture(scratch, true);
const result = spawnSync("/bin/sh", ["-c", hostSetup], {
encoding: "utf8",
env: {
...process.env,
HOME: home,
INSTALL_MODE: "standalone",
PATH: `${scratch}:/usr/bin:/bin`,
HARNESS_TMUX_METADATA_URL: "https://cdn.example/manifest.json",
HARNESS_HOMEBREW_PREFIXES: join(scratch, "no-homebrew"),
},
});
expect(result.status).toBe(22);
expect(result.stderr).toContain("checksum verification");
expect(() => readlinkSync(join(home, ".local", "bin", "tmux"))).toThrow();
expect(() => readFileSync(join(home, ".harness", "runtime", "current-tmux"))).toThrow();
} finally {
rmSync(scratch, { recursive: true, force: true });
}
}, 20_000);
it("falls back to the managed build when Homebrew cannot install tmux", () => {
const source = readFileSync(installer, "utf8");
const hostSetup = hostSetupOf(source);
const scratch = mkdtempSync(join(tmpdir(), "harness-mac-brew-broken-"));
try {
const { home, root } = managedFixture(scratch);
writeCommand(scratch, "brew", [`if [ "$1" = "shellenv" ]; then exit 0; fi`, "exit 1"]);
const result = spawnSync("/bin/sh", ["-c", hostSetup], {
encoding: "utf8",
env: {
...process.env,
HOME: home,
INSTALL_MODE: "standalone",
PATH: `${scratch}:/usr/bin:/bin`,
HARNESS_TMUX_METADATA_URL: "https://cdn.example/manifest.json",
HARNESS_HOMEBREW_PREFIXES: join(scratch, "no-homebrew"),
},
});
expect(result.status).toBe(0);
expect(result.stdout).toContain("No Homebrew tmux bottle for this Mac; using the managed build instead.");
expect(readlinkSync(join(home, ".local", "bin", "tmux"))).toContain(root);
} finally {
rmSync(scratch, { recursive: true, force: true });
}
}, 20_000);
it("host mode puts ~/.local/bin on PATH for new shells", () => {
const source = readFileSync(installer, "utf8");
const hostSetup = hostSetupOf(source);
const scratch = mkdtempSync(join(tmpdir(), "harness-host-rc-"));
try {
const { home } = managedFixture(scratch);
const result = spawnSync("/bin/sh", ["-c", hostSetup], {
encoding: "utf8",
env: {
...process.env,
HOME: home,
SHELL: "/bin/zsh",
INSTALL_MODE: "host",
PATH: `${scratch}:/usr/bin:/bin`,
HARNESS_TMUX_METADATA_URL: "https://cdn.example/manifest.json",
HARNESS_HOMEBREW_PREFIXES: join(scratch, "no-homebrew"),
},
});
expect(result.status).toBe(0);
expect(result.stdout).toContain("Host requirements ready");
expect(readFileSync(join(home, ".zshrc"), "utf8")).toContain('export PATH="$HOME/.local/bin:$PATH"');
} finally {
rmSync(scratch, { recursive: true, force: true });
}
}, 20_000);
it("host mode stops after the host requirements", () => {
const source = readFileSync(installer, "utf8");
const hostSetup = hostSetupOf(source);
const scratch = mkdtempSync(join(tmpdir(), "harness-host-mode-"));
try {
writeCommand(scratch, "uname", ["printf 'Darwin\\n'"]);
writeCommand(scratch, "tmux", ["printf 'tmux 3.6\\n'"]);
const result = spawnSync("/bin/sh", ["-c", `${hostSetup}\necho REACHED-NODE-STEP`], {
encoding: "utf8",
env: { ...process.env, INSTALL_MODE: "host", PATH: scratch },
});
expect(result.status).toBe(0);
expect(result.stdout).toContain("Host requirements ready");
expect(result.stdout).not.toContain("REACHED-NODE-STEP");
} finally {
rmSync(scratch, { recursive: true, force: true });
}
});
it("installs nothing on a Linux host that already runs tmux and ps", () => {
const source = readFileSync(installer, "utf8");
const hostSetup = hostSetupOf(source);
const scratch = mkdtempSync(join(tmpdir(), "harness-linux-ready-"));
const invoked = join(scratch, "apt-invoked");
try {
writeLinuxHostCommands(scratch);
writeCommand(scratch, "id", ["printf '0\\n'"]);
writeCommand(scratch, "uname", ["printf 'Linux\\n'"]);
writeCommand(scratch, "tmux", ["printf 'tmux 3.6\\n'"]);
// curl is a download tool, not a host requirement: its absence is no business of step 1.
writeCommand(scratch, "apt-get", [`: > '${invoked}'`, "exit 99"]);
const result = spawnSync("/bin/sh", ["-c", hostSetup], {
encoding: "utf8",
env: {
...process.env,
INSTALL_MODE: "standalone",
DISPLAY: "",
WAYLAND_DISPLAY: "",
PATH: scratch,
},
});
expect(result.status).toBe(0);
expect(result.stdout).toContain("tmux ready");
expect(() => readFileSync(invoked, "utf8")).toThrow();
} finally {
rmSync(scratch, { recursive: true, force: true });
}
});
it("installs the download tools only when the runtime is downloaded", () => {
const source = readFileSync(installer, "utf8");
// The check lives inside the download branch, after managed-runtime reuse is ruled out.
const download = source.indexOf('if [ -z "$NODE_BIN" ]; then\n\n # Fetching');
const reuse = source.indexOf('if [ -z "$NODE_BIN" ] && [ -r "$CURRENT_NODE_FILE" ]');
expect(reuse).toBeGreaterThan(-1);
expect(download).toBeGreaterThan(reuse);
expect(source.slice(0, download)).not.toContain("require_command curl");
const downloadTools = downloadToolsOf(source);
const scratch = mkdtempSync(join(tmpdir(), "harness-download-tools-"));
const invocations = join(scratch, "apt-invocations");
const fakeCurl = join(scratch, "curl");
try {
for (const command of ["tar", "sed", "awk", "sha256sum"]) {
writeCommand(scratch, command, ["exit 0"]);
}
writeCommand(scratch, "id", ["printf '0\\n'"]);
writeCommand(scratch, "uname", ["printf 'Linux\\n'"]);
writeCommand(scratch, "apt-get", [
`printf '%s\\n' "$*" >> '${invocations}'`,
`printf '%s\\n' '#!/bin/sh' 'exit 0' > '${fakeCurl}'`,
`/bin/chmod 700 '${fakeCurl}'`,
]);
const result = spawnSync("/bin/sh", ["-c", downloadTools], {
encoding: "utf8",
env: { ...process.env, PATH: scratch },
});
expect(result.status).toBe(0);
expect(readFileSync(invocations, "utf8")).toBe("install -y curl\n");
expect(result.stdout).toContain("tools needed to download the runtime");
} finally {
rmSync(scratch, { recursive: true, force: true });
}
});
it("installs tmux through sudo without refreshing usable package indexes", () => {
const source = readFileSync(installer, "utf8");
const tmuxStep = hostSetupOf(source);
const scratch = mkdtempSync(join(tmpdir(), "harness-tmux-user-"));
const invocation = join(scratch, "sudo-invocation");
const fakeTmux = join(scratch, "tmux");
try {
writeLinuxHostCommands(scratch);
writeCommand(scratch, "id", ["printf '1000\\n'"]);
writeCommand(scratch, "uname", ["printf 'Linux\\n'"]);
writeCommand(scratch, "apt-get", ["exit 99"]);
writeCommand(scratch, "sudo", [
`printf '%s\\n' "$*" > '${invocation}'`,
`printf '%s\\n' '#!/bin/sh' 'printf "tmux 3.6\\\\n"' > '${fakeTmux}'`,
`/bin/chmod 700 '${fakeTmux}'`,
]);
const result = spawnSync("/bin/sh", ["-c", tmuxStep], {
encoding: "utf8",
env: {
...process.env,
INSTALL_MODE: "standalone",
DISPLAY: "",
WAYLAND_DISPLAY: "",
PATH: scratch,
},
});
expect(result.status).toBe(0);
expect(readFileSync(invocation, "utf8")).toBe("apt-get install -y tmux\n");
expect(result.stdout).toContain("tmux ready");
} finally {
rmSync(scratch, { recursive: true, force: true });
}
});
it("installs as root without sudo and retries after a failed index refresh", () => {
const source = readFileSync(installer, "utf8");
const tmuxStep = hostSetupOf(source);
const scratch = mkdtempSync(join(tmpdir(), "harness-tmux-root-"));
const invocations = join(scratch, "apt-invocations");
const firstAttempt = join(scratch, "first-attempt");
const fakeTmux = join(scratch, "tmux");
try {
writeLinuxHostCommands(scratch);
writeCommand(scratch, "id", ["printf '0\\n'"]);
writeCommand(scratch, "uname", ["printf 'Linux\\n'"]);
writeCommand(scratch, "apt-get", [
`printf '%s\\n' "$*" >> '${invocations}'`,
`if [ "$1" = "update" ]; then exit 77; fi`,
`if [ ! -f '${firstAttempt}' ]; then : > '${firstAttempt}'; exit 1; fi`,
`printf '%s\\n' '#!/bin/sh' 'printf "tmux 3.6\\\\n"' > '${fakeTmux}'`,
`/bin/chmod 700 '${fakeTmux}'`,
]);
const result = spawnSync("/bin/sh", ["-c", tmuxStep], {
encoding: "utf8",
env: {
...process.env,
INSTALL_MODE: "standalone",
DISPLAY: "",
WAYLAND_DISPLAY: "",
PATH: scratch,
},
});
expect(result.status).toBe(0);
expect(readFileSync(invocations, "utf8")).toBe(
"install -y tmux\nupdate\ninstall -y tmux\n",
);
expect(result.stdout).toContain("tmux ready");
} finally {
rmSync(scratch, { recursive: true, force: true });
}
});
it("requires only the active Linux desktop clipboard helper before Node", () => {
const source = readFileSync(installer, "utf8");
const wayland = source.indexOf('clipboard_command="wl-copy"');
const x11 = source.indexOf('clipboard_command="xclip"');
const nodeStep = source.indexOf("# 2. Resolve the Node");
expect(wayland).toBeGreaterThan(-1);
expect(x11).toBeGreaterThan(wayland);
expect(nodeStep).toBeGreaterThan(x11);
expect(source).toContain('if [ -n "${WAYLAND_DISPLAY:-}" ]; then');
expect(source).toContain('elif [ -n "${DISPLAY:-}" ]; then');
expect(source).toContain('exit 23');
expect(source).not.toContain("install_with_apt xclip wl-clipboard");
});
it("installs xclip for X11 and verifies it", () => {
const source = readFileSync(installer, "utf8");
const hostSetup = hostSetupOf(source);
const scratch = mkdtempSync(join(tmpdir(), "harness-xclip-root-"));
const invocations = join(scratch, "apt-invocations");
const fakeXclip = join(scratch, "xclip");
try {
writeLinuxHostCommands(scratch);
writeCommand(scratch, "id", ["printf '0\\n'"]);
writeCommand(scratch, "uname", ["printf 'Linux\\n'"]);
writeCommand(scratch, "tmux", ["printf 'tmux 3.6\\n'"]);
writeCommand(scratch, "apt-get", [
`printf '%s\\n' "$*" >> '${invocations}'`,
`printf '%s\\n' '#!/bin/sh' 'exit 0' > '${fakeXclip}'`,
`/bin/chmod 700 '${fakeXclip}'`,
]);
const result = spawnSync("/bin/sh", ["-c", hostSetup], {
encoding: "utf8",
env: {
...process.env,
INSTALL_MODE: "standalone",
DISPLAY: ":0",
WAYLAND_DISPLAY: "",
PATH: scratch,
},
});
expect(result.status).toBe(0);
expect(readFileSync(invocations, "utf8")).toBe("install -y xclip\n");
expect(result.stdout).toContain("Linux image clipboard ready (xclip)");
} finally {
rmSync(scratch, { recursive: true, force: true });
}
});
it("does not install clipboard packages on a headless Linux host", () => {
const source = readFileSync(installer, "utf8");
const hostSetup = hostSetupOf(source);
const scratch = mkdtempSync(join(tmpdir(), "harness-headless-root-"));
const invoked = join(scratch, "apt-invoked");
try {
writeLinuxHostCommands(scratch);
writeCommand(scratch, "id", ["printf '0\\n'"]);
writeCommand(scratch, "uname", ["printf 'Linux\\n'"]);
writeCommand(scratch, "tmux", ["printf 'tmux 3.6\\n'"]);
writeCommand(scratch, "apt-get", [`: > '${invoked}'`, "exit 99"]);
const result = spawnSync("/bin/sh", ["-c", hostSetup], {
encoding: "utf8",
env: {
...process.env,
INSTALL_MODE: "standalone",
DISPLAY: "",
WAYLAND_DISPLAY: "",
PATH: scratch,
},
});
expect(result.status).toBe(0);
expect(result.stdout).toContain("native image clipboard is not applicable");
expect(() => readFileSync(invoked, "utf8")).toThrow();
} finally {
rmSync(scratch, { recursive: true, force: true });
}
});
it("fails before Node when the active Wayland helper cannot be installed", () => {
const source = readFileSync(installer, "utf8");
const hostSetup = hostSetupOf(source);
const scratch = mkdtempSync(join(tmpdir(), "harness-wayland-fail-"));
try {
writeLinuxHostCommands(scratch);
writeCommand(scratch, "id", ["printf '0\\n'"]);
writeCommand(scratch, "uname", ["printf 'Linux\\n'"]);
writeCommand(scratch, "tmux", ["printf 'tmux 3.6\\n'"]);
writeCommand(scratch, "apt-get", ["exit 88"]);
const result = spawnSync("/bin/sh", ["-c", hostSetup], {
encoding: "utf8",
env: {
...process.env,
INSTALL_MODE: "standalone",
DISPLAY: ":0",
WAYLAND_DISPLAY: "wayland-0",
PATH: scratch,
},
});
expect(result.status).toBe(23);
expect(result.stderr).toContain("Could not install wl-clipboard");
expect(result.stderr).not.toContain("xclip");
} finally {
rmSync(scratch, { recursive: true, force: true });
}
}, 20_000); // Several real shell/package-manager processes, as in the other installer integration checks.
// ── the managed grid ──────────────────────────────────────────────────────────────────────────
//
// The grid CLI the release PINS, laid down beside Node and tmux — but unlike them, optional: the
// harness works without it, the daemon follows the pin on every start, so this step may fail and
// the install still succeeds. And never linked into ~/.local/bin: that path is grid's own
// installer's (uv's, on a Mac); the daemon puts the managed grid on an agent pane's PATH itself.
// The helpers plus the grid step alone, as one runnable unit.
const gridStepOf = (source: string) =>
source.slice(source.indexOf('METADATA_URL="${HARNESS_METADATA_URL'), source.indexOf("# 1. Host requirements")) +
source.slice(source.indexOf("# 3b. The managed grid"), source.indexOf("# 3c. hn's binary"));
it("installs the managed grid after the CLI and before PATH, as a step the install can survive", () => {
const source = readFileSync(installer, "utf8");
const cliStep = source.indexOf("# 3. Fetch manifest");
const gridStep = source.indexOf("# 3b. The managed grid");
const pathStep = source.indexOf("# 4. Ensure ~/.local/bin");
expect(cliStep).toBeGreaterThan(0);
expect(gridStep).toBeGreaterThan(cliStep);
expect(pathStep).toBeGreaterThan(gridStep);
expect(source).toContain('GRID_METADATA_URL="${HARNESS_GRID_METADATA_URL:-');
expect(source).toContain('CURRENT_GRID_FILE="$RUNTIME_DIR/current-grid"');
// Optional, by construction: the call is guarded, and the function returns instead of exiting.
expect(source.slice(gridStep, pathStep)).toMatch(/install_managed_grid \|\|/);
const fn = source.slice(source.indexOf("install_managed_grid() {"), source.indexOf("# 1. Host requirements"));
expect(fn).not.toContain("exit ");
expect(fn).not.toContain("ln -s");
});
const gridFixture = (scratch: string, tamperSha = false) => {
const home = join(scratch, "home");
const root = "grid-9.9-darwin-arm64";
const stage = join(scratch, "stage", root, "bin");
mkdirSync(stage, { recursive: true });
writeCommand(stage, "grid", ["printf 'grid 9.9\\n'"]);
const archive = join(scratch, `${root}.tar.gz`);
spawnSync("tar", ["-czf", archive, "-C", join(scratch, "stage"), root]);
const sha = spawnSync("shasum", ["-a", "256", archive], { encoding: "utf8" }).stdout.split(" ")[0];
writeFileSync(join(scratch, "manifest.json"), JSON.stringify({
grid: {
"darwin-arm64": {
version: "9.9",
url: "https://cdn.example/grid.tar.gz",
sha256: tamperSha ? "0".repeat(64) : sha,
size: 1,
archiveRoot: root,
},
},
}, null, 2));
writeCommand(scratch, "curl", [
`printf '%s\\n' "$*" >> '${join(scratch, "curl-invocations")}'`,
`case "$*" in *"-o "*) cp '${archive}' "$4" ;; *) cat '${join(scratch, "manifest.json")}' ;; esac`,
]);
writeCommand(scratch, "uname", [`if [ "$1" = "-m" ]; then printf 'arm64\\n'; else printf 'Darwin\\n'; fi`]);
mkdirSync(home, { recursive: true });
return { home, root };
};
const runGridStep = (scratch: string, home: string, mode: string) =>
spawnSync("/bin/sh", ["-c", gridStepOf(readFileSync(installer, "utf8"))], {
encoding: "utf8",
env: {
...process.env,
HOME: home,
INSTALL_MODE: mode,
PATH: `${scratch}:/usr/bin:/bin`,
HARNESS_GRID_METADATA_URL: "https://cdn.example/manifest.json",
},
});
it("leaves grid to its first use on the desktop app's first run", () => {
const scratch = mkdtempSync(join(tmpdir(), "harness-grid-desktop-"));
try {
const { home } = gridFixture(scratch);
const result = runGridStep(scratch, home, "desktop");
expect(result.stdout).not.toContain("Installing the managed grid");
expect(existsSync(join(home, ".harness", "runtime", "current-grid"))).toBe(false);
expect(existsSync(join(scratch, "curl-invocations"))).toBe(false);
} finally {
rmSync(scratch, { recursive: true, force: true });
}
});
it("downloads, verifies and records the managed grid read-only, and links nothing", () => {
const scratch = mkdtempSync(join(tmpdir(), "harness-grid-managed-"));
try {
const { home, root } = gridFixture(scratch);
const result = runGridStep(scratch, home, "standalone");
expect(result.status).toBe(0);
expect(result.stdout).toContain("downloading grid 9.9 (darwin-arm64)");
expect(result.stdout).toContain(`installed grid 9.9 → ${join(home, ".harness", "runtime", root)}`);
const binary = join(home, ".harness", "runtime", root, "bin", "grid");
expect(readFileSync(join(home, ".harness", "runtime", "current-grid"), "utf8").trim()).toBe(binary);
// `grid update` is a rename INTO bin/; a bin/ it cannot write to is what makes that fail loudly.
expect(statSync(binary).mode & 0o777).toBe(0o555);
expect(statSync(join(home, ".harness", "runtime", root, "bin")).mode & 0o777).toBe(0o555);
expect(existsSync(join(home, ".local", "bin", "grid"))).toBe(false);
expect(readFileSync(join(scratch, "curl-invocations"), "utf8")).toContain("https://cdn.example/manifest.json");
} finally {
// The read-only bin/ the step lays down cannot be emptied as it is; give it back before the sweep.
try { chmodSync(join(scratch, "home", ".harness", "runtime", "grid-9.9-darwin-arm64", "bin"), 0o755); } catch { /* never laid down */ }
rmSync(scratch, { recursive: true, force: true });
}
}, 20_000);
it("survives a grid whose checksum does not match: says so, records nothing, and the install goes on", () => {
const scratch = mkdtempSync(join(tmpdir(), "harness-grid-tampered-"));
try {
const { home } = gridFixture(scratch, true);
const result = runGridStep(scratch, home, "standalone");
expect(result.status).toBe(0);
expect(result.stderr).toContain("checksum verification");
expect(result.stdout).toContain("set up the first time a grid feature is used");
expect(existsSync(join(home, ".harness", "runtime", "current-grid"))).toBe(false);
expect(readdirSync(join(home, ".harness", "runtime")).filter((n) => n.startsWith(".grid-staging-"))).toEqual([]);
} finally {
rmSync(scratch, { recursive: true, force: true });
}
}, 20_000);
it("says which platform has no managed grid, fetches nothing, and the install goes on", () => {
const scratch = mkdtempSync(join(tmpdir(), "harness-grid-platform-"));
try {
const { home } = gridFixture(scratch);
writeCommand(scratch, "uname", [`if [ "$1" = "-m" ]; then printf 'riscv64\\n'; else printf 'Linux\\n'; fi`]);
const result = runGridStep(scratch, home, "standalone");
expect(result.status).toBe(0);
expect(result.stderr).toContain("No managed grid is published for Linux/riscv64");
expect(existsSync(join(scratch, "curl-invocations"))).toBe(false);
expect(existsSync(join(home, ".harness", "runtime", "current-grid"))).toBe(false);
} finally {
rmSync(scratch, { recursive: true, force: true });
}
}, 20_000);
it("fetches no grid in host mode, which installs no CLI either", () => {
const scratch = mkdtempSync(join(tmpdir(), "harness-grid-host-"));
try {
const { home } = gridFixture(scratch);
const result = runGridStep(scratch, home, "host");
expect(result.status).toBe(0);
expect(existsSync(join(scratch, "curl-invocations"))).toBe(false);
expect(existsSync(join(home, ".harness", "runtime", "current-grid"))).toBe(false);
} finally {
rmSync(scratch, { recursive: true, force: true });
}
}, 20_000);
it("desktop mode skips all host package and tmux work", () => {
const source = readFileSync(installer, "utf8");
const hostSetup = hostSetupOf(source);
const scratch = mkdtempSync(join(tmpdir(), "harness-desktop-mode-"));
const invoked = join(scratch, "host-command-invoked");
try {
for (const command of ["uname", "sudo", "apt-get", "tmux", "brew"]) {
writeCommand(scratch, command, [`: > '${invoked}'`, "exit 99"]);
}
const result = spawnSync("/bin/sh", ["-c", hostSetup], {
encoding: "utf8",
env: { ...process.env, INSTALL_MODE: "desktop", PATH: scratch },
});
expect(result.status).toBe(0);
expect(result.stdout).toContain("Desktop mode");
expect(() => readFileSync(invoked, "utf8")).toThrow();
} finally {
rmSync(scratch, { recursive: true, force: true });
}
});
});
describe("scripts/install.sh: hn", () => {
// The constants and helpers (install_hn among them), then step 3c alone.
const hnStepOf = (source: string) =>
source.slice(source.indexOf('METADATA_URL="${HARNESS_METADATA_URL'), source.indexOf("# 1. Host requirements")) +
source.slice(source.indexOf("# 3c. hn's binary"), source.indexOf("# 4. Ensure ~/.local/bin"));
it("installs hn after the grid and before PATH, as a step the install can survive", () => {
const source = readFileSync(installer, "utf8");
const grid = source.indexOf("# 3b. The managed grid");
const hn = source.indexOf("# 3c. hn's binary");
const path = source.indexOf("# 4. Ensure ~/.local/bin");
expect(hn).toBeGreaterThan(grid);
expect(path).toBeGreaterThan(hn);
expect(source.slice(hn, path)).toMatch(/install_hn \|\|/);
const fn = source.slice(source.indexOf("install_hn() {"), source.indexOf("install_managed_grid() {"));
expect(fn).not.toContain("exit ");
// Where `harness tui` looks for the binary (cli/src/tui/index.ts), and release-tui.yml's manifest.
expect(source).toContain('TUI_BIN="$HOME/.harness/bin/harness-tui"');
expect(source).toContain("harness/tui/metadata.json");
});
const hnFixture = (scratch: string, { tamper = false, runs = true } = {}) => {
const home = join(scratch, "home");
mkdirSync(home, { recursive: true });
const binary = join(scratch, "harness-tui-darwin-arm64");
writeFileSync(binary, runs ? "#!/bin/sh\necho 'hn 0.1.0 (tmux 3.5a)'\n" : "#!/bin/sh\nexit 1\n");
chmodSync(binary, 0o755);
const sha = spawnSync("shasum", ["-a", "256", binary], { encoding: "utf8" }).stdout.split(" ")[0];
// As release-tui.yml writes it: jq's pretty print, one build per platform.
writeFileSync(join(scratch, "manifest.json"), JSON.stringify({
version: "0.1.0",
builds: {
"darwin-x64": { url: "https://cdn.example/harness-tui-darwin-x64", sha256: "1".repeat(64) },
"darwin-arm64": { url: "https://cdn.example/harness-tui-darwin-arm64", sha256: tamper ? "0".repeat(64) : sha },
},
}, null, 2));
writeCommand(scratch, "curl", [
`printf '%s\\n' "$*" >> '${join(scratch, "curl-invocations")}'`,
`case "$*" in *"-o "*) cp '${binary}' "$4" ;; *) cat '${join(scratch, "manifest.json")}' ;; esac`,
]);
writeCommand(scratch, "uname", [`if [ "$1" = "-m" ]; then printf 'arm64\\n'; else printf 'Darwin\\n'; fi`]);
return { home, tui: join(home, ".harness", "bin", "harness-tui") };
};
const runHnStep = (scratch: string, home: string, mode: string) =>
spawnSync("/bin/sh", ["-c", hnStepOf(readFileSync(installer, "utf8"))], {
encoding: "utf8",
env: { ...process.env, HOME: home, INSTALL_MODE: mode, PATH: `${scratch}:/usr/bin:/bin`, HARNESS_TUI_MANIFEST_URL: "https://cdn.example/manifest.json" },
});
it("downloads this computer's build, verifies it and installs it where `harness tui` finds it", () => {
const scratch = mkdtempSync(join(tmpdir(), "harness-hn-"));
try {
const { home, tui } = hnFixture(scratch);
const result = runHnStep(scratch, home, "standalone");
expect(result.status).toBe(0);
expect(result.stdout).toContain("downloading hn 0.1.0 (darwin-arm64)");
expect(result.stdout).toContain(`installed hn 0.1.0 → ${tui}`);
expect(statSync(tui).mode & 0o111).not.toBe(0);
expect(spawnSync(tui, ["--version"], { encoding: "utf8" }).stdout).toContain("hn 0.1.0");
expect(readFileSync(join(scratch, "curl-invocations"), "utf8")).toContain("harness-tui-darwin-arm64");
} finally {
rmSync(scratch, { recursive: true, force: true });
}
}, 20_000);
it("survives a download whose checksum does not match: says so, installs nothing, and the install goes on", () => {
const scratch = mkdtempSync(join(tmpdir(), "harness-hn-tampered-"));
try {
const { home, tui } = hnFixture(scratch, { tamper: true });
const result = runHnStep(scratch, home, "standalone");
expect(result.status).toBe(0);
expect(result.stderr).toContain("checksum verification");
expect(result.stdout).toContain("hn will download itself the first time you run it");
expect(existsSync(tui)).toBe(false);
expect(readdirSync(join(home, ".harness", "bin")).filter((n) => n.endsWith(".tmp"))).toEqual([]);
} finally {
rmSync(scratch, { recursive: true, force: true });
}
}, 20_000);
it("keeps no binary that does not run on this computer", () => {
const scratch = mkdtempSync(join(tmpdir(), "harness-hn-broken-"));
try {
const { home, tui } = hnFixture(scratch, { runs: false });
const result = runHnStep(scratch, home, "standalone");
expect(result.status).toBe(0);
expect(result.stderr).toContain("hn does not run on this computer");
expect(existsSync(tui)).toBe(false);
} finally {
rmSync(scratch, { recursive: true, force: true });
}
}, 20_000);
it("fetches nothing in desktop mode (its first `hn` does) or host mode (no CLI)", () => {
for (const mode of ["desktop", "host"]) {
const scratch = mkdtempSync(join(tmpdir(), `harness-hn-${mode}-`));
try {
const { home, tui } = hnFixture(scratch);
const result = runHnStep(scratch, home, mode);
expect(result.status).toBe(0);
expect(existsSync(join(scratch, "curl-invocations"))).toBe(false);
expect(existsSync(tui)).toBe(false);
} finally {
rmSync(scratch, { recursive: true, force: true });
}
}
}, 20_000);
// Step 3 for real: the Node that writes the launchers, against a local manifest server.
const runCliStep = async (home: string) => {
const { createServer } = await import("node:http");
const { createHash } = await import("node:crypto");
const { spawn } = await import("node:child_process");
const files: Record<string, string> = { "/cli.js": "console.log('cli')\n", "/notify.mjs": "export {}\n" };
const sha = (text: string) => createHash("sha256").update(text).digest("hex");
const server = createServer((req, res) => {
const base = `http://127.0.0.1:${(server.address() as { port: number }).port}`;
if (req.url === "/manifest.json") {
res.end(JSON.stringify({ cli: { version: "9.9.9", cli: { url: `${base}/cli.js`, sha256: sha(files["/cli.js"]) }, notify: { url: `${base}/notify.mjs`, sha256: sha(files["/notify.mjs"]) } } }));
} else if (files[req.url ?? ""]) res.end(files[req.url ?? ""]);
else { res.statusCode = 404; res.end() }
});
await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
const port = (server.address() as { port: number }).port;
const source = readFileSync(installer, "utf8");
const js = source.slice(source.indexOf("<<'HARNESSJS'\n") + "<<'HARNESSJS'\n".length, source.indexOf("\nHARNESSJS\n"));
const child = spawn(process.execPath, [], { env: { ...process.env, HOME: home, HARNESS_METADATA_URL: `http://127.0.0.1:${port}/manifest.json`, HARNESS_KEY: "cli", HARNESS_NODE_BINARY: "/opt/harness node/bin/node" } });
let out = "";
child.stdout.on("data", (d) => { out += d });
child.stderr.on("data", (d) => { out += d });
child.stdin.end(js);
const code = await new Promise<number | null>((resolve) => child.on("close", resolve));
server.close();
return { code, out };
};
it("writes `hn` beside `harness`, following its runtime and update policy", async () => {
const scratch = mkdtempSync(join(tmpdir(), "harness-hn-launcher-"));
try {
const home = join(scratch, "home");
mkdirSync(home, { recursive: true });
const { code, out } = await runCliStep(home);
expect(code).toBe(0);
expect(out).toContain("installed harness 9.9.9");
const cli = join(home, ".harness", "cli", "cli.js");
expect(readFileSync(join(home, ".local", "bin", "hn"), "utf8")).toBe(`#!/bin/sh\nexec '${join(home, ".local", "bin", "harness")}' tui "$@"\n`);
expect(readFileSync(join(home, ".local", "bin", "harness"), "utf8")).toBe(`#!/bin/sh\nexec '/opt/harness node/bin/node' '${cli}' "$@"\n`);
expect(statSync(join(home, ".local", "bin", "hn")).mode & 0o111).not.toBe(0);
} finally {
rmSync(scratch, { recursive: true, force: true });
}
}, 20_000);
it("leaves someone else's `hn` alone and says how to run Harness's", async () => {
const scratch = mkdtempSync(join(tmpdir(), "harness-hn-theirs-"));
try {
const home = join(scratch, "home");
mkdirSync(join(home, ".local", "bin"), { recursive: true });
writeFileSync(join(home, ".local", "bin", "hn"), "#!/bin/sh\necho hacker news\n", { mode: 0o755 });
const { code, out } = await runCliStep(home);
expect(code).toBe(0);
expect(readFileSync(join(home, ".local", "bin", "hn"), "utf8")).toBe("#!/bin/sh\necho hacker news\n");
expect(out).toContain("Kept existing");
expect(out).toContain("use harness tui");
} finally {
rmSync(scratch, { recursive: true, force: true });
}
}, 20_000);
it.each(['native symlink', 'dangling symlink', 'unrelated wrapper'])("preserves an existing %s even when it contains .harness", async kind => {
const scratch = mkdtempSync(join(tmpdir(), "harness-hn-preserved-"));
try {
const home = join(scratch, "home");
const bin = join(home, ".local", "bin");
const hn = join(bin, "hn");
const target = join(scratch, "old-hn");
mkdirSync(bin, { recursive: true });
const bytes = kind === 'unrelated wrapper' ? Buffer.from('#!/bin/sh\necho "$HOME/.harness"\n') : Buffer.from('\x7fELF native .harness bytes');
if (kind === 'unrelated wrapper') writeFileSync(hn, bytes);
else {
if (kind === 'native symlink') writeFileSync(target, bytes, { mode: 0o755 });
symlinkSync(target, hn);
}
const { code, out } = await runCliStep(home);
expect(code).toBe(0);
expect(out).toContain('harness tui --install');
if (kind === 'unrelated wrapper') expect(readFileSync(hn)).toEqual(bytes);
else {
expect(lstatSync(hn).isSymbolicLink()).toBe(true);
expect(readlinkSync(hn)).toBe(target);
if (kind === 'native symlink') expect(readFileSync(target)).toEqual(bytes);
else expect(existsSync(target)).toBe(false);
}
expect(readdirSync(bin).sort()).toEqual(['harness', 'hn']);
} finally { rmSync(scratch, { recursive: true, force: true }); }
}, 20_000);
});
describe("scripts/install.sh: OpenCode for hn's first window", () => {
// The constants (NEW_COMPUTER among them), then step 3d alone.
const openCodeStepOf = (source: string) =>
source.slice(source.indexOf('METADATA_URL="${HARNESS_METADATA_URL'), source.indexOf("# Shared by every download")) +
source.slice(source.indexOf("# 4b. OpenCode"), source.indexOf("# 5. Final verification"));
// OpenCode's own installer, as served: a script for bash that puts the binary in ~/.opencode/bin.
const run = (mode: string, { agent = "", installs = true, attended = true } = {}) => {
const scratch = mkdtempSync(join(tmpdir(), "harness-opencode-"));
try {
const home = join(scratch, "home");
mkdirSync(home, { recursive: true });
if (agent) mkdirSync(join(home, agent), { recursive: true });
writeCommand(scratch, "curl", [
`printf '%s\\n' "$*" >> '${join(scratch, "curl-invocations")}'`,
installs
? `printf '%s\\n' 'mkdir -p "$HOME/.opencode/bin"' 'printf "#!/bin/sh\\n" > "$HOME/.opencode/bin/opencode"' 'chmod +x "$HOME/.opencode/bin/opencode"'`
: "exit 7",
]);
const result = spawnSync("/bin/sh", ["-c", openCodeStepOf(readFileSync(installer, "utf8"))], {
encoding: "utf8",
env: { ...process.env, HOME: home, INSTALL_MODE: mode, PATH: `${scratch}:/usr/bin:/bin`, HARNESS_INSTALL_ATTENDED: attended ? "1" : "" },
});
let curl = "";
try { curl = readFileSync(join(scratch, "curl-invocations"), "utf8"); } catch { /* never asked */ }
const marked = existsSync(join(home, ".harness", "tui", "first-run"));
return { result, curl, marked, opencode: join(home, ".opencode", "bin", "opencode") };
} finally {
rmSync(scratch, { recursive: true, force: true });
}
};
it("downloads it on a computer with no agent and no Harness, with the CLI's recipe, into ~/.opencode/bin", () => {
const { result, curl, marked } = run("standalone");
expect(result.status).toBe(0);
expect(curl).toContain("https://opencode.ai/install");
expect(marked, "hn's first start opens OpenCode (tui/src/first_run.rs)").toBe(true);
expect(result.stdout).toContain("✓ OpenCode ready");
const source = readFileSync(installer, "utf8");
const step = source.indexOf("# 4b. OpenCode");
expect(source.slice(step, source.indexOf("# 5. Final verification"))).toContain("bash -s -- --no-modify-path");
// After ~/.local/bin is on PATH: stopping a slow download leaves a working PATH.
expect(step).toBeGreaterThan(source.indexOf("\nensure_path_rc\n"));
}, 20_000);
it("leaves it alone where there is an agent or Harness already, and to the app under --desktop", () => {
for (const agent of [".claude", ".codex", ".harness/cli", ".config/opencode"]) {
const { result, curl, marked } = run("standalone", { agent });
expect(result.status, agent).toBe(0);
expect(curl, agent).toBe("");
expect(marked, agent).toBe(false);
}
for (const mode of ["desktop", "host"]) {
const { curl, marked } = run(mode);
expect(curl, mode).toBe("");
expect(marked, mode).toBe(false);
}
// Nobody at a terminal (a Docker build, a provisioning script): no agent it did not ask for.
const unattended = run("standalone", { attended: false });
expect(unattended.curl).toBe("");
expect(unattended.marked).toBe(false);
}, 20_000);
it("survives a download that fails: says a pane will install it, and the install goes on", () => {
const { result } = run("standalone", { installs: false });
expect(result.status).toBe(0);
expect(result.stdout).toContain("OpenCode will be installed when hn first starts it");
}, 20_000);
});