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.

Find installed tmux for fresh macOS users (#507)

Deefcbde058bab4
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index d5134c04c..1f6a781e4 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -1517,7 +1517,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
console.error(`[tmux] unavailable: ${tmuxPath.reason} · install tmux and verify \`tmux -V\`,`
+ ' then restart — agents cannot be created or restored until then')
} else if (tmuxPath.state === 'adopted') {
- console.log(`[tmux] not on the daemon PATH · adopted ${tmuxPath.from} from the user's login shell`)
+ console.log(`[tmux] not on the daemon PATH · adopted ${tmuxPath.path} · ${tmuxPath.from}`)
}
}
// The desktop's pane colours, for tmux's `window-style` (lib/hostTheme.ts): the last ones the app
diff --git a/cli/src/lib/tmuxOnPath.spec.ts b/cli/src/lib/tmuxOnPath.spec.ts
index 3eb610732..a6056a543 100644
--- a/cli/src/lib/tmuxOnPath.spec.ts
+++ b/cli/src/lib/tmuxOnPath.spec.ts
@@ -3,7 +3,7 @@ import { tmpdir } from 'node:os'
import { delimiter, join } from 'node:path'
import { afterEach, describe, expect, it } from 'vitest'
import { TmuxBackend } from './tmuxBackend.js'
-import { ensureTmuxOnPath, managedTmuxPath, requireTmuxAvailable, resolveViaLoginShell } from './tmuxOnPath.js'
+import { ensureTmuxOnPath, managedTmuxPath, requireTmuxAvailable, resolveViaLoginShell, tmuxInstallDirectories } from './tmuxOnPath.js'
const dirs: string[] = []
const originalPath = process.env.PATH
@@ -167,7 +167,7 @@ PATH="${binDir}" exec /bin/sh -c "$@"
const emptyBin = scratch('tmux-onpath-empty-')
const env: NodeJS.ProcessEnv = { PATH: '/nonexistent-for-this-test' }
- const outcome = await ensureTmuxOnPath(env, fakeShell(emptyBin), noManagedTmux())
+ const outcome = await ensureTmuxOnPath(env, fakeShell(emptyBin), noManagedTmux(), [])
expect(outcome.state).toBe('absent')
expect(env.PATH).toBe('/nonexistent-for-this-test')
@@ -211,4 +211,48 @@ exit 0
state: 'succeeded', dispatch: 'executed', runtime: { backend: 'tmux', paneId: '%7' },
})
})
+
+ it('creates the first pane with an installed tmux absent from a fresh user’s shell', async () => {
+ const binDir = scratch('tmux-onpath-installed-')
+ writeFileSync(join(binDir, 'tmux'), `#!/bin/sh
+case "$1" in
+ -V) printf 'tmux 3.7c\\n' ;;
+ new-session) printf '%%0\\n' ;;
+esac
+`, { mode: 0o700 })
+ const runtimeDir = noManagedTmux()
+ process.env.PATH = '/nonexistent-for-this-test'
+ const backend = new TmuxBackend()
+ expect(await backend.create({ label: 'harness-first' })).toMatchObject({
+ state: 'failed', reason: 'tmux is unavailable',
+ })
+
+ // The installer found Homebrew in a known prefix. Neither the daemon nor
+ // this new OS user's login shell inherited the installer's temporary PATH.
+ const outcome = await ensureTmuxOnPath(process.env, '/nonexistent/shell', runtimeDir, [binDir])
+ expect(outcome).toMatchObject({ state: 'adopted', path: join(binDir, 'tmux') })
+ expect(await backend.create({ label: 'harness-first' })).toMatchObject({
+ state: 'succeeded', runtime: { backend: 'tmux', paneId: '%0' },
+ })
+ })
+
+ it('checks the user bin and both macOS Homebrew prefixes, but not Homebrew on Linux', () => {
+ expect(tmuxInstallDirectories({ HOME: '/Users/new-user' }, 'darwin')).toEqual([
+ '/Users/new-user/.local/bin', '/opt/homebrew/bin', '/usr/local/bin',
+ ])
+ expect(tmuxInstallDirectories({ HOME: '/home/new-user' }, 'linux')).toEqual(['/home/new-user/.local/bin'])
+ expect(tmuxInstallDirectories({ HARNESS_BIN_DIR: '/custom/bin', HARNESS_HOMEBREW_PREFIXES: '/custom/brew' }, 'darwin'))
+ .toEqual(['/custom/bin', '/custom/brew/bin'])
+ })
+
+ it('skips a broken install candidate and adopts the next runnable tmux', async () => {
+ const broken = scratch('tmux-onpath-broken-')
+ writeFileSync(join(broken, 'tmux'), '#!/bin/sh\nexit 1\n', { mode: 0o700 })
+ const working = scratch('tmux-onpath-working-')
+ writeFileSync(join(working, 'tmux'), '#!/bin/sh\nprintf "tmux 3.7c\\n"\n', { mode: 0o700 })
+ const env: NodeJS.ProcessEnv = { PATH: '/nonexistent' }
+ expect(await ensureTmuxOnPath(env, '/nonexistent/shell', noManagedTmux(), [broken, working]))
+ .toMatchObject({ state: 'adopted', path: join(working, 'tmux') })
+ expect(env.PATH?.split(delimiter)[0]).toBe(working)
+ })
})
diff --git a/cli/src/lib/tmuxOnPath.ts b/cli/src/lib/tmuxOnPath.ts
index 9a1956cad..2588646a8 100644
--- a/cli/src/lib/tmuxOnPath.ts
+++ b/cli/src/lib/tmuxOnPath.ts
@@ -14,6 +14,7 @@
*/
import { execFile } from 'node:child_process'
import { accessSync, constants, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
import { delimiter, dirname, isAbsolute, join, sep } from 'node:path'
import { env as appEnv } from '../config/env.js'
import { binaryOnPath } from './binaryOnPath.js'
@@ -73,6 +74,28 @@ export function managedTmuxPath(runtimeDir: string = appEnv.ADAPTER_RUNTIME_DIR)
return null
}
+/** The same install locations Desktop checks, even before a new user's shell knows about them. */
+export function tmuxInstallDirectories(
+ env: NodeJS.ProcessEnv = process.env,
+ platform: NodeJS.Platform = process.platform,
+): string[] {
+ const userBin = env.HARNESS_BIN_DIR || join(env.HOME || homedir(), '.local', 'bin')
+ const brew = platform === 'darwin'
+ ? (env.HARNESS_HOMEBREW_PREFIXES ?? '/opt/homebrew /usr/local').split(/\s+/).filter(Boolean)
+ .map(prefix => join(prefix, 'bin'))
+ : []
+ return [userBin, ...brew].filter(isAbsolute)
+}
+
+/** A known location is only a fallback when its tmux actually runs on this computer. */
+function tmuxRuns(binary: string, env: NodeJS.ProcessEnv): Promise<boolean> {
+ return new Promise(resolve => {
+ execFile(binary, ['-V'], { env, timeout: 2_000 }, (error, stdout) => {
+ resolve(!error && /^tmux \S+/.test(String(stdout).trim()))
+ })
+ })
+}
+
/** Where the user's own interactive shell finds a command, which is not where the daemon looks. */
export async function resolveViaLoginShell(
command: string,
@@ -132,6 +155,7 @@ export async function ensureTmuxOnPath(
env: NodeJS.ProcessEnv = process.env,
shell: string | undefined = undefined,
runtimeDir: string = appEnv.ADAPTER_RUNTIME_DIR,
+ installDirectories: readonly string[] = tmuxInstallDirectories(env),
): Promise<TmuxPathOutcome> {
if (binaryOnPath('tmux', env)) return { state: 'present' }
// The user's own shell is asked first and the managed build is the fallback, in that order on
@@ -152,10 +176,21 @@ export async function ensureTmuxOnPath(
env.PATH = env.PATH ? `${dir}${delimiter}${env.PATH}` : dir
return { state: 'adopted', path: managed, from: 'managed runtime' }
}
+ // install.sh can find Homebrew and install tmux by temporarily evaluating `brew shellenv`.
+ // That PATH belongs only to the installer: a fresh macOS user's rc files do not inherit it.
+ // Desktop explicitly checks these locations too. Preserve the user's existing PATH/shell choice
+ // above, then verify the installed fallback without invoking Homebrew or changing shell profiles.
+ for (const dir of installDirectories) {
+ if (!isAbsolute(dir)) continue
+ const candidate = join(dir, 'tmux')
+ if (!binaryOnPath(candidate, env) || !await tmuxRuns(candidate, env)) continue
+ env.PATH = env.PATH ? `${dir}${delimiter}${env.PATH}` : dir
+ return { state: 'adopted', path: candidate, from: 'standard install location' }
+ }
return {
state: 'absent',
reason: interactiveEngineShell(shell)
- ? 'the user\'s login shell does not resolve tmux either, and there is no managed tmux'
- : 'no usable login shell to ask, tmux is not on the daemon PATH, and there is no managed tmux',
+ ? 'tmux was not found on PATH, in the login shell, managed runtime, or standard install locations'
+ : 'no usable login shell, and tmux was not found on PATH, in the managed runtime, or standard install locations',
}
}
diff --git a/cli/src/scripts/install.spec.ts b/cli/src/scripts/install.spec.ts
index 8278bba5a..44d68004a 100644
--- a/cli/src/scripts/install.spec.ts
+++ b/cli/src/scripts/install.spec.ts
@@ -3,6 +3,8 @@ 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 } from "vitest";
+import { ensureTmuxOnPath, tmuxInstallDirectories } from "../lib/tmuxOnPath.js";
+import { TmuxBackend } from "../lib/tmuxBackend.js";
// 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");
@@ -288,6 +290,49 @@ describe("scripts/install.sh command contract", () => {
}
});
+ it("finds Homebrew tmux after the installer exits and creates the first harness pane", 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");
+ const originalPath = process.env.PATH;
+ 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);
+
+ // A child cannot export PATH back into its parent. Start the daemon with
+ // the original environment, as hn does in a fresh macOS user account.
+ process.env.PATH = daemonEnv.PATH;
+ expect(await new TmuxBackend().create({ label: "harness-first" })).toMatchObject({
+ state: "failed", reason: "tmux is unavailable",
+ });
+ expect(await ensureTmuxOnPath(daemonEnv, "/nonexistent/shell", join(home, ".harness/runtime"),
+ tmuxInstallDirectories(daemonEnv, "darwin"))).toMatchObject({ state: "adopted" });
+ process.env.PATH = daemonEnv.PATH;
+ expect(await new TmuxBackend().create({ label: "harness-first" })).toMatchObject({
+ state: "succeeded", runtime: { backend: "tmux", paneId: "%0" },
+ });
+ } finally {
+ process.env.PATH = originalPath;
+ rmSync(scratch, { recursive: true, force: true });
+ }
+ });
+
// 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) => {