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.

Harness Team account installs its own tmux when it has none it can run

bitcoinbuilder4528967d54bb
diff --git a/cli/src/superTabs/service.spec.ts b/cli/src/superTabs/service.spec.ts
index 76c7b4ed6..7af78539f 100644
--- a/cli/src/superTabs/service.spec.ts
+++ b/cli/src/superTabs/service.spec.ts
@@ -737,6 +737,29 @@ describe('the owner\'s subscriptions for the Harness Team account', () => {
})
})
+describe('the Harness Team account\'s own tmux', () => {
+ it('is looked at as the service connects, and not again once there or installed; a failure again later', async () => {
+ const quiet = { githubTokens: () => ({ start: vi.fn(), stop: vi.fn() }) as never, teamEngines: () => ({ start: vi.fn(), stop: vi.fn() }) as never,
+ teamRelay: () => ({ start: vi.fn(), stop: vi.fn(async () => {}) }) }
+ const installed = vi.fn(async () => 'installed' as const)
+ const service = superTabService(fakeCore(), { ...quiet, teamTmux: installed })
+ service.port.connected()
+ await Promise.resolve()
+ service.port.connected()
+ expect(installed).toHaveBeenCalledOnce()
+ const failed = vi.fn(async () => 'failed' as const)
+ const retried = superTabService(fakeCore(), { ...quiet, teamTmux: failed })
+ retried.port.connected()
+ await Promise.resolve()
+ retried.port.connected()
+ expect(failed).toHaveBeenCalledOnce()
+ vi.useFakeTimers({ now: Date.now() + 31 * 60_000 })
+ retried.port.connected()
+ vi.useRealTimers()
+ expect(failed).toHaveBeenCalledTimes(2)
+ })
+})
+
describe('the Harness Team account, offered by Desktop on this Mac', () => {
it('runs only for the local owner, for a moment the person is there, and says whether it started', async () => {
const offer = vi.fn(async (_reason: string, _shared: () => Promise<boolean>) => ({ state: 'started' as const }))
diff --git a/cli/src/superTabs/service.ts b/cli/src/superTabs/service.ts
index 2e460f649..bde6d4bdf 100644
--- a/cli/src/superTabs/service.ts
+++ b/cli/src/superTabs/service.ts
@@ -18,6 +18,12 @@ import { teamEngineReporter, type TeamEngineReporter } from '../team/engines.js'
import { AUTO_SETUP_REASONS, realTeamAutoSetup, type AutoSetupReason, type TeamAutoSetup } from '../team/autoSetup.js'
import { readTeamConfig } from '../team/config.js'
import { realTeamRelayPublisher, type TeamRelayPublisher } from '../team/relay.js'
+import { ensureTeamTmux, TMUX_MANIFEST_URL, tmuxRunsAt, untarGz, type TeamTmuxDeps, type TeamTmuxOutcome } from '../team/tmux.js'
+import { downloadVerified } from '../lib/selfUpdate.js'
+import { managedTmuxPath, tmuxInstallDirectories } from '../lib/tmuxOnPath.js'
+import { env as appEnv } from '../config/env.js'
+import { homedir, userInfo } from 'node:os'
+import { delimiter, isAbsolute, join } from 'node:path'
import { createOwnerSubscriptions } from '../lib/ownerSubscriptions.js'
import { startSubscriptionRelay } from '../lib/subscriptionRelay.js'
@@ -180,6 +186,8 @@ export interface SuperTabServiceOptions {
teamSetup?: () => Promise<Pick<TeamAutoSetup, 'offer' | 'decline'>>
/** Whether this daemon runs team work only (a Harness Team account, `harness team on`), for a spec. */
team?: () => boolean
+ /** The Harness Team account's own tmux (team/tmux.ts), for a spec. */
+ teamTmux?: () => Promise<TeamTmuxOutcome>
/** The owner's subscriptions for the Harness Team account (team/relay.ts), for a spec. */
teamRelay?: () => Pick<TeamRelayPublisher, 'start' | 'stop'>
}
@@ -230,12 +238,22 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =
() => startSubscriptionRelay({ owner: createOwnerSubscriptions(), log: line => console.log(`[team] relay · ${line}`) }),
() => readTeamConfig(), options.team ?? (() => readAuthSession()?.kind === 'team'), line => console.log(`[team] ${line}`))))()
let autoSetup: Promise<Pick<TeamAutoSetup, 'offer' | 'decline'>> | null = null
+ // In the Harness Team account: a tmux of its own when it has none it can run (team/tmux.ts). Looked at as it connects,
+ // and a failed install again half an hour later.
+ let tmuxCheckedAt = -Infinity
+ const ensureTmux = options.teamTmux ?? (() => ensureTeamTmux(realTeamTmuxDeps()))
+ const checkTmux = () => {
+ if (Date.now() - tmuxCheckedAt < 30 * 60_000) return
+ tmuxCheckedAt = Date.now()
+ void ensureTmux().then(outcome => { if (outcome === 'present' || outcome === 'installed' || outcome === 'not-team') tmuxCheckedAt = Infinity })
+ }
const disconnect = () => { preparations.clear(); host?.stop(); host = null; held = null; book?.stop(); book = null; bookMachine = null; swarmCards?.want(false); swarmCards = null; cardsMachine = null; tokens.stop(); engines.stop() }
const port = {
connected: () => {
tokens.start()
engines.start()
relay.start()
+ checkTmux()
// A daemon that runs team work only is there for its Swarms: its host runs from its first connection. Its Mac's daemon adds
// a Harness Team account to a Swarm without waking it (host.ts joinTeams), and a host that never ran reports no privacy
// check, so the Swarm read the account as offline and never sent it a teammate's work (third VM run).
@@ -466,3 +484,28 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =
}
return { requests, port }
}
+
+/** The team daemon's own: its account, its PATH and Homebrew's places, the published manifest (team/tmux.ts). */
+function realTeamTmuxDeps(): TeamTmuxDeps {
+ return {
+ team: () => { try { return readTeamConfig()?.user === userInfo().username } catch { return false } },
+ platform: process.platform,
+ arch: process.arch,
+ candidates: () => {
+ const managed = managedTmuxPath()
+ const dirs = [...(process.env.PATH ?? '').split(delimiter).filter(isAbsolute), ...tmuxInstallDirectories()]
+ return [...(managed ? [managed] : []), ...dirs.map(dir => join(dir, 'tmux'))].filter(path => existsSync(path))
+ },
+ runs: tmuxRunsAt,
+ manifest: async () => {
+ const reply = await fetch(process.env.HARNESS_TMUX_METADATA_URL || TMUX_MANIFEST_URL, { signal: AbortSignal.timeout(30_000) })
+ if (!reply.ok) throw new Error(`the tmux manifest answered HTTP ${reply.status}`)
+ return reply.json()
+ },
+ download: (build) => downloadVerified({ url: build.url, sha256: build.sha256, ...(build.size ? { size: build.size } : {}) }),
+ untar: untarGz,
+ runtimeDir: appEnv.ADAPTER_RUNTIME_DIR,
+ binDir: join(homedir(), '.local', 'bin'),
+ log: (line) => console.log(`[team] ${line}`),
+ }
+}
diff --git a/cli/src/team/tmux.spec.ts b/cli/src/team/tmux.spec.ts
new file mode 100644
index 000000000..a41321403
--- /dev/null
+++ b/cli/src/team/tmux.spec.ts
@@ -0,0 +1,83 @@
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { ensureTeamTmux, tmuxBuildFor, untarGz, type TeamTmuxDeps } from './tmux.js'
+
+const SHA = 'a'.repeat(64)
+const manifest = { tmux: {
+ 'darwin-arm64': { version: '3.7c', url: 'https://example.com/tmux-arm64.tar.gz', sha256: SHA, size: 9, archiveRoot: 'tmux-3.7c-darwin-arm64' },
+ 'darwin-x64': { version: '3.7c', url: 'https://example.com/tmux-x64.tar.gz', sha256: SHA, archiveRoot: 'tmux-3.7c-darwin-x64' },
+} }
+const cleanup: string[] = []
+afterEach(() => { for (const dir of cleanup.splice(0)) rmSync(dir, { recursive: true, force: true }) })
+
+/** A .tar.gz holding [root]/bin/tmux, made with the system's tar. */
+function archive(root: string, withBinary = true): Buffer {
+ const dir = mkdtempSync(join(tmpdir(), 'tmux-archive-'))
+ cleanup.push(dir)
+ mkdirSync(join(dir, root, 'bin'), { recursive: true })
+ if (withBinary) writeFileSync(join(dir, root, 'bin', 'tmux'), '#!/bin/sh\necho tmux 3.7c\n', { mode: 0o755 })
+ execFileSync('/usr/bin/tar', ['-czf', join(dir, 'out.tar.gz'), '-C', dir, root])
+ return readFileSync(join(dir, 'out.tar.gz'))
+}
+
+function deps(over: Partial<TeamTmuxDeps> = {}) {
+ const home = mkdtempSync(join(tmpdir(), 'team-tmux-'))
+ cleanup.push(home)
+ const d: TeamTmuxDeps = {
+ team: () => true, platform: 'darwin', arch: 'arm64', candidates: () => ['/opt/homebrew/bin/tmux'],
+ runs: vi.fn(async (binary: string) => binary.startsWith(home)), manifest: async () => manifest,
+ download: vi.fn(async () => archive('tmux-3.7c-darwin-arm64')), untar: untarGz,
+ runtimeDir: join(home, '.harness', 'runtime'), binDir: join(home, '.local', 'bin'), log: vi.fn(), ...over,
+ }
+ return { d, home }
+}
+
+describe('the Harness Team account\'s own tmux', () => {
+ it('reads this Mac\'s build from the published manifest, and nothing that is not one', () => {
+ expect(tmuxBuildFor(manifest, 'darwin', 'arm64')).toMatchObject({ version: '3.7c', archiveRoot: 'tmux-3.7c-darwin-arm64', size: 9 })
+ expect(tmuxBuildFor(manifest, 'darwin', 'x64')).not.toHaveProperty('size')
+ for (const [m, platform, arch] of [[manifest, 'linux', 'x64'], [manifest, 'darwin', 'ia32'], [null, 'darwin', 'arm64'],
+ [{ tmux: { 'darwin-arm64': { ...manifest.tmux['darwin-arm64'], url: 'http://plain.example/t.tar.gz' } } }, 'darwin', 'arm64'],
+ [{ tmux: { 'darwin-arm64': { ...manifest.tmux['darwin-arm64'], sha256: 'nope' } } }, 'darwin', 'arm64'],
+ [{ tmux: { 'darwin-arm64': { ...manifest.tmux['darwin-arm64'], archiveRoot: '../escape' } } }, 'darwin', 'arm64'],
+ ] as Array<[unknown, NodeJS.Platform, string]>) expect(tmuxBuildFor(m, platform, arch)).toBeNull()
+ })
+
+ it('installs the managed build in its own home when it has no tmux it can run, where the daemon looks for it', async () => {
+ const { d, home } = deps()
+ expect(await ensureTeamTmux(d)).toBe('installed')
+ const binary = join(home, '.harness', 'runtime', 'tmux-3.7c-darwin-arm64', 'bin', 'tmux')
+ expect(readFileSync(join(home, '.harness', 'runtime', 'current-tmux'), 'utf8')).toBe(`${binary}\n`)
+ expect(readlinkSync(join(home, '.local', 'bin', 'tmux'))).toBe(binary)
+ expect(d.log).toHaveBeenCalledWith(expect.stringContaining('installed tmux 3.7c'))
+ // Already there (a tmux link from before replaced): nothing downloaded again.
+ expect(await ensureTeamTmux({ ...d, candidates: () => [] })).toBe('installed')
+ expect(d.download).toHaveBeenCalledOnce()
+ expect(existsSync(join(home, '.harness', 'runtime', `.tmux-staging-${process.pid}`))).toBe(false)
+ })
+
+ it('leaves alone an account that is not the team account, or one whose tmux runs', async () => {
+ expect(await ensureTeamTmux(deps({ team: () => false }).d)).toBe('not-team')
+ const { d } = deps({ runs: async () => true })
+ expect(await ensureTeamTmux(d)).toBe('present')
+ expect(d.download).not.toHaveBeenCalled()
+ })
+
+ it('says so when no build is published for this Mac, and fails without throwing', async () => {
+ expect(await ensureTeamTmux(deps({ arch: 'ia32' }).d)).toBe('unsupported')
+ const noBinary = deps({ download: async () => archive('tmux-3.7c-darwin-arm64', false) })
+ expect(await ensureTeamTmux(noBinary.d)).toBe('failed')
+ expect(noBinary.d.log).toHaveBeenCalledWith(expect.stringContaining('has no tmux-3.7c-darwin-arm64/bin/tmux'))
+ const broken = deps({ untar: async () => { throw new Error('could not unpack') } })
+ expect(await ensureTeamTmux(broken.d)).toBe('failed')
+ const silent = deps({ runs: async () => false })
+ expect(await ensureTeamTmux(silent.d)).toBe('failed')
+ expect(silent.d.log).toHaveBeenCalledWith(expect.stringContaining('does not run here'))
+ const odd = deps({ manifest: async () => { throw 'offline' } })
+ expect(await ensureTeamTmux(odd.d)).toBe('failed')
+ expect(odd.d.log).toHaveBeenCalledWith('team: could not install tmux for the Harness Team account: offline')
+ })
+})
diff --git a/cli/src/team/tmux.ts b/cli/src/team/tmux.ts
new file mode 100644
index 000000000..d36f24f39
--- /dev/null
+++ b/cli/src/team/tmux.ts
@@ -0,0 +1,104 @@
+/**
+ * The Harness Team account's own tmux, installed by its own daemon, in its own home.
+ *
+ * Every agent runs in tmux. Setup gives the team account its owner's managed tmux when the owner has one; otherwise it
+ * counted on Homebrew's, at /opt/homebrew or /usr/local. A Homebrew another account cannot read (mode 700/770 on a Mac
+ * on 2026-10-27) left the team account with no tmux it could run, and every start there failed with TMUX_UNAVAILABLE,
+ * the update its owner's daemon asked for included. So the team daemon, which nobody signs in to or installs for,
+ * installs Harness's managed tmux itself when it has none it can run: the same checksum-verified build, in the same
+ * place, as `install.sh` puts it for a person (`install_managed_tmux`), which the daemon's tmux lookup already reads
+ * (lib/tmuxOnPath.ts `managedTmuxPath`). No password: it writes only its own home.
+ */
+import { execFile } from 'node:child_process'
+import { existsSync, mkdirSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** The managed tmux's manifest, as `install.sh` reads it (`TMUX_METADATA_URL`). */
+export const TMUX_MANIFEST_URL = 'https://storage.googleapis.com/s3-autonomous-upgrade-3/harness/runtime/tmux/metadata.json'
+
+export interface TmuxBuild { version: string; url: string; sha256: string; size?: number; archiveRoot: string }
+
+export type TeamTmuxOutcome = 'not-team' | 'present' | 'installed' | 'unsupported' | 'failed'
+
+export interface TeamTmuxDeps {
+ /** Whether this daemon is a Mac's Harness Team account. */
+ team(): boolean
+ platform: NodeJS.Platform
+ arch: string
+ /** The tmux binaries this daemon would find (managed, on PATH, Homebrew's): any that runs is enough. */
+ candidates(): string[]
+ runs(binary: string): Promise<boolean>
+ manifest(): Promise<unknown>
+ /** The archive's bytes, checked against its sha256 (lib/selfUpdate.ts `downloadVerified`). */
+ download(build: TmuxBuild): Promise<Buffer>
+ /** Unpacks a .tar.gz into a folder. */
+ untar(archive: string, into: string): Promise<void>
+ /** `~/.harness/runtime` and `~/.local/bin` of this account. */
+ runtimeDir: string
+ binDir: string
+ log(line: string): void
+}
+
+/** The manifest's build for this Mac (`install.sh` `manifest_platform`), or null. */
+export function tmuxBuildFor(manifest: unknown, platform: NodeJS.Platform, arch: string): TmuxBuild | null {
+ if (platform !== 'darwin') return null
+ const key = `darwin-${arch === 'arm64' ? 'arm64' : arch === 'x64' ? 'x64' : ''}`
+ const entry = (manifest as { tmux?: Record<string, unknown> } | null)?.tmux?.[key] as Record<string, unknown> | undefined
+ if (!entry) return null
+ const { version, url, sha256, archiveRoot, size } = entry
+ if (typeof version !== 'string' || typeof url !== 'string' || !url.startsWith('https://') || typeof sha256 !== 'string'
+ || !/^[0-9a-f]{64}$/i.test(sha256) || typeof archiveRoot !== 'string' || !/^[A-Za-z0-9._-]{1,128}$/.test(archiveRoot)) return null
+ return { version, url, sha256, archiveRoot, ...(typeof size === 'number' ? { size } : {}) }
+}
+
+/** Installs the managed tmux in the team account when it has none it can run. Never throws. */
+export async function ensureTeamTmux(deps: TeamTmuxDeps): Promise<TeamTmuxOutcome> {
+ try {
+ if (!deps.team()) return 'not-team'
+ for (const binary of deps.candidates()) if (await deps.runs(binary)) return 'present'
+ const build = tmuxBuildFor(await deps.manifest(), deps.platform, deps.arch)
+ if (!build) {
+ deps.log(`team: no managed tmux is published for ${deps.platform}-${deps.arch}; teammates' agents cannot start here`)
+ return 'unsupported'
+ }
+ const target = join(deps.runtimeDir, build.archiveRoot)
+ const binary = join(target, 'bin', 'tmux')
+ if (!existsSync(binary)) {
+ mkdirSync(deps.runtimeDir, { recursive: true, mode: 0o700 })
+ const staging = join(deps.runtimeDir, `.tmux-staging-${process.pid}`)
+ rmSync(staging, { recursive: true, force: true })
+ mkdirSync(staging, { recursive: true, mode: 0o700 })
+ try {
+ const archive = join(staging, 'tmux.tar.gz')
+ writeFileSync(archive, await deps.download(build), { mode: 0o600 })
+ await deps.untar(archive, staging)
+ if (!existsSync(join(staging, build.archiveRoot, 'bin', 'tmux'))) throw new Error(`the tmux archive has no ${build.archiveRoot}/bin/tmux`)
+ rmSync(target, { recursive: true, force: true })
+ renameSync(join(staging, build.archiveRoot), target)
+ } finally {
+ rmSync(staging, { recursive: true, force: true })
+ }
+ }
+ if (!await deps.runs(binary)) throw new Error(`the managed tmux does not run here: ${binary}`)
+ // What the daemon's lookup reads, and the link a shell in this account finds first, as install.sh writes them.
+ writeFileSync(join(deps.runtimeDir, 'current-tmux'), `${binary}\n`, { mode: 0o600 })
+ mkdirSync(deps.binDir, { recursive: true })
+ rmSync(join(deps.binDir, 'tmux'), { force: true })
+ symlinkSync(binary, join(deps.binDir, 'tmux'))
+ deps.log(`team: installed tmux ${build.version} for the Harness Team account → ${target}`)
+ return 'installed'
+ } catch (error) {
+ deps.log(`team: could not install tmux for the Harness Team account: ${error instanceof Error ? error.message : String(error)}`)
+ return 'failed'
+ }
+}
+
+/** Whether [binary] runs and says it is tmux. */
+export const tmuxRunsAt = (binary: string) => new Promise<boolean>((resolve) => {
+ execFile(binary, ['-V'], { timeout: 5_000 }, (error, stdout) => resolve(!error && /^tmux \S+/.test(String(stdout).trim())))
+})
+
+/** Unpacks with the system's tar, as install.sh does. */
+export const untarGz = (archive: string, into: string) => new Promise<void>((resolve, reject) => {
+ execFile('/usr/bin/tar', ['-xzf', archive, '-C', into], { timeout: 60_000 }, (error) => error ? reject(new Error(`could not unpack ${archive}`)) : resolve())
+})