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.

Agents get short harness super-tab commands in delivered Swarm messages (#1581)

0xken15941fef66759b
diff --git a/cli/src/lib/tmuxOnPath.ts b/cli/src/lib/tmuxOnPath.ts
index 5689f8b1a..5f273b5d3 100644
--- a/cli/src/lib/tmuxOnPath.ts
+++ b/cli/src/lib/tmuxOnPath.ts
@@ -136,7 +136,7 @@ export async function resolveViaLoginShell(
}
/** One question to one shell: where is `command`? Null unless it answers with an absolute path. */
-function probe(shellPath: string, args: readonly string[], command: string): Promise<string | null> {
+export function probe(shellPath: string, args: readonly string[], command: string): Promise<string | null> {
return new Promise<string | null>((resolve) => {
execFile(
shellPath,
diff --git a/cli/src/superTabs/host.spec.ts b/cli/src/superTabs/host.spec.ts
index 2237463b4..edf66dd7e 100644
--- a/cli/src/superTabs/host.spec.ts
+++ b/cli/src/superTabs/host.spec.ts
@@ -431,6 +431,43 @@ it('confirms a stopped assignment only with fresh native evidence, including aft
expect(proof).toHaveLength(1)
})
+describe('the super-tab command in delivered input', () => {
+ it('names the short command in every line that names a command, and asks for it once while the input is held', async () => {
+ const t = setup({ replyTo: 'earlier' })
+ const agentCommand = vi.fn(async () => 'harness super-tab')
+ const host = new SuperTabHost(t.core, 'machine-1', { log: vi.fn(), agentCommand }); hosts.push(host)
+ await host.tick()
+ const text = String(vi.mocked(t.core.turns.deliver).mock.calls[0]?.[1])
+ expect(text).toContain(`Read its state: harness super-tab --tab 'tab' --agent 'agent' status`)
+ expect(text).toContain(`harness super-tab --tab 'tab' --agent 'agent' message 'lead' 'earlier'`)
+ expect(text).toContain(`harness super-tab --tab 'tab' --agent 'agent' route GROUP JSON`)
+ expect(text).not.toContain('--port')
+ t.event('rejected', 'team_waiting_busy')
+ await host.tick()
+ expect(t.core.turns.deliver).toHaveBeenCalledTimes(2)
+ expect(agentCommand).toHaveBeenCalledTimes(1)
+ expect(agentCommand).toHaveBeenCalledWith(t.core, 'machine-1')
+ })
+ it('falls back to the full command when the lookup fails, and does not ask again', async () => {
+ const t = setup()
+ const agentCommand = vi.fn(async () => { throw new Error('no shell') })
+ const host = new SuperTabHost(t.core, 'machine-1', { log: vi.fn(), agentCommand }); hosts.push(host)
+ await host.tick()
+ expect(String(vi.mocked(t.core.turns.deliver).mock.calls[0]?.[1]))
+ .toContain(`Read its state: ${t.core.daemon.command} super-tab --port ${t.core.daemon.port} --machine 'machine-1' --tab 'tab' --agent 'agent' status`)
+ t.event('rejected', 'team_waiting_busy')
+ await host.tick()
+ expect(agentCommand).toHaveBeenCalledTimes(1)
+ })
+ it('keeps the daemon\'s full command when nothing proves a shorter one works (no launcher is looked up in a spec)', async () => {
+ const t = setup()
+ const host = new SuperTabHost(t.core, 'machine-1', { log: vi.fn() }); hosts.push(host)
+ await host.tick()
+ expect(String(vi.mocked(t.core.turns.deliver).mock.calls[0]?.[1]))
+ .toContain(`Read its state: ${t.core.daemon.command} super-tab --port ${t.core.daemon.port} --machine 'machine-1' --tab 'tab' --agent 'agent' status`)
+ })
+})
+
describe('Super Tab attachments in delivered input', () => {
it('lists the downloaded files after the text and downloads them once while the terminal holds the input', async () => {
const file = { id: 'a1', name: 'screen.png', mime: 'image/png', size: 5, url: 'https://cdn.example.test/x/screen.png' }
diff --git a/cli/src/superTabs/host.ts b/cli/src/superTabs/host.ts
index d9ce46d6e..cdbbabaee 100644
--- a/cli/src/superTabs/host.ts
+++ b/cli/src/superTabs/host.ts
@@ -9,6 +9,9 @@ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from '
import { dirname, join } from 'node:path'
import type { CoreApi, TurnDelivery } from '../core/api.js'
import { shellQuote } from '../orchestrator/prompts.js'
+import { agentCommandPrefix, fullCommandPrefix } from './shortCommand.js'
+import { readAuthSession } from '../lib/authSession.js'
+import { computerId } from '../lib/daemonState.js'
import { noticeReason, WithheldDeliveries } from './withheld.js'
import { attentionOf } from './attention.js'
import { prepareContribution } from './contribution.js'
@@ -77,8 +80,12 @@ export interface SuperTabHostOptions {
observers?: typeof publishObservers
attachedFiles?: typeof attachedFiles
prepareContribution?: typeof prepareContribution
+ /** The `… super-tab` prefix agents are told to run (superTabs/shortCommand.ts), for a spec. */
+ agentCommand?: (core: CoreApi, machineId: string) => Promise<string>
}
+const defaultAgentCommand = (core: CoreApi, machineId: string) => agentCommandPrefix(core.daemon, machineId,
+ () => readAuthSession()?.machineId || computerId())
export const hostJournalFile = (dataDir: string, machineId: string) => join(dataDir, 'super-tabs', `host-${machineId}.json`)
/** How long after an add the roster may ask for another (a roster read may predate the add), and the first wait after a
* failed one. Each try probes every engine's account (about 14 login shells), so the wait doubles up to half an hour:
@@ -138,6 +145,9 @@ export class SuperTabHost {
private receiptsRunning: Promise<void> | null = null
private nextReceiptsAt = 0
private receiptCursor = 0
+ private readonly agentCommand: (core: CoreApi, machineId: string) => Promise<string>
+ /** Asked once, on the first delivery: the answer cannot change while this daemon runs (superTabs/shortCommand.ts). */
+ private prefix: Promise<string> | null = null
private configurationsRunning: Promise<void> | null = null
private nextConfigurationsAt = 0
private timer: ReturnType<typeof setTimeout> | null = null
@@ -156,6 +166,7 @@ export class SuperTabHost {
this.observers = options.observers ?? publishObservers
this.attachedFiles = options.attachedFiles ?? attachedFiles
this.prepareContribution = options.prepareContribution ?? prepareContribution
+ this.agentCommand = options.agentCommand ?? defaultAgentCommand
this.now = options.now ?? Date.now
this.write = options.write ?? writeJournal
this.log = options.log ?? (message => console.warn(`[super-tabs] ${message}`))
@@ -590,6 +601,8 @@ export class SuperTabHost {
files = downloaded.text
if (downloaded.complete) this.files.set(deliveryId, files)
}
+ this.prefix ??= this.agentCommand(this.core, this.machineId).catch(() => fullCommandPrefix(this.core.daemon, this.machineId))
+ const command = await this.prefix
if (this.stopped || this.journal.entries[deliveryId] !== entry) return
this.authorized.set(id, this.now() + 2_500)
if (!(await this.leases()) || this.stopped) { this.authorized.delete(id); return }
@@ -599,7 +612,7 @@ export class SuperTabHost {
entry.stage = 'submitting'
this.persist()
this.active.add(id)
- this.core.turns.deliver(entry.harnessId, this.prompt(entry, message, files), id)
+ this.core.turns.deliver(entry.harnessId, this.prompt(entry, message, files, command), id)
}
private async recordConfigurations(rows: unknown[]): Promise<void> {
@@ -614,8 +627,8 @@ export class SuperTabHost {
}
}
- private prompt(entry: Entry, message: Json, files: string): string {
- const command = `${this.core.daemon.command} super-tab --port ${this.core.daemon.port} --machine ${shellQuote(this.machineId)} --tab ${shellQuote(entry.tabId)} --agent ${shellQuote(entry.agentId)}`
+ private prompt(entry: Entry, message: Json, files: string, prefix: string): string {
+ const command = `${prefix} --tab ${shellQuote(entry.tabId)} --agent ${shellQuote(entry.agentId)}`
const group = message.conversationId as string
const reply = identifier(message.replyTo)
? `In reply to message ${message.replyTo}. Read it before interpreting the answer: ${command} message ${shellQuote(group)} ${shellQuote(message.replyTo)}\n\n`
diff --git a/cli/src/superTabs/shortCommand.spec.ts b/cli/src/superTabs/shortCommand.spec.ts
new file mode 100644
index 000000000..d7e487565
--- /dev/null
+++ b/cli/src/superTabs/shortCommand.spec.ts
@@ -0,0 +1,167 @@
+import { describe, expect, it, vi } from 'vitest'
+import { chmodSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { agentCommandPrefix, fullCommandPrefix, shellResolve, shellWords, windowsResolve, type ShortCommandDeps } from './shortCommand.js'
+
+// No spec here starts a shell, reads the developer's ~/.local/bin or touches port 18473: every lookup is a fake.
+const NODE = '/home/a/.harness/runtime/node-v22/bin/node', CLI = '/home/a/.harness/cli/cli.js'
+const full = `'${NODE}' '--max-semi-space-size=4' '--max-old-space-size=4096' '${CLI}'`
+const daemon = { command: full, port: 18473 }
+const today = `${full} super-tab --port 18473 --machine 'machine-1'`
+const defaultMachine = () => 'machine-1'
+const launcher = (node = NODE, cli = CLI) => `#!/bin/sh\nexec '${node}' '${cli}' "$@"\n`
+const PATH = '/home/a/.local/bin/harness'
+const fake = (files: Record<string, string>, env: NodeJS.ProcessEnv = {}): ShortCommandDeps => ({ resolve: async () => PATH, platform: 'darwin', env,
+ readFile: path => { if (!(path in files)) throw new Error('ENOENT'); return files[path] }, realpath: path => path })
+const prefix = (over: Partial<typeof daemon> = {}, machine = 'machine-1', deps = fake({ [PATH]: launcher() })) =>
+ agentCommandPrefix({ ...daemon, ...over }, machine, defaultMachine, deps)
+
+describe('the super-tab command an agent is told to run (macOS and Linux)', () => {
+ it('is `harness` when the launcher on the agent\'s PATH runs this daemon\'s Node and cli.js, with the default port and this machine left out', async () => {
+ expect(await prefix()).toBe('harness super-tab')
+ })
+ it('keeps --port when it is not the default, and --machine when it is not the one the CLI picks', async () => {
+ expect(await prefix({ port: 18999 })).toBe(`harness super-tab --port 18999 --machine 'machine-1'`)
+ expect(await prefix({}, "mach'ine")).toBe(`harness super-tab --machine 'mach'"'"'ine'`)
+ })
+ it.each(['PORT', 'ADAPTER_DATA_DIR', 'ADAPTER_CLI_DIR', 'HARNESS_AUTH_DIR', 'HARNESS_ENV_FILE', 'ADAPTER_COMPUTER_ID', 'ADAPTER_COMPUTER_ID_FILE'])(
+ 'keeps both flags when the daemon has its own %s, which the agent\'s shell does not have', async name => {
+ // An isolated daemon on the default port with the default machine id would otherwise send the agent to the wrong daemon.
+ expect(await prefix({}, 'machine-1', fake({ [PATH]: launcher() }, { [name]: '/isolated' }))).toBe(`harness super-tab --port 18473 --machine 'machine-1'`)
+ })
+ it('is today\'s full command when no `harness` is found, or the lookup fails', async () => {
+ expect(await prefix({}, 'machine-1', { ...fake({}), resolve: async () => null })).toBe(today)
+ expect(await prefix({}, 'machine-1', { ...fake({}), resolve: async () => { throw new Error('no shell') } })).toBe(today)
+ expect(await prefix({}, 'machine-1', fake({}))).toBe(today)
+ })
+ it('is the full command when the launcher runs another CLI, another Node, or is not the installer\'s script', async () => {
+ for (const text of [launcher(NODE, '/repo/dev/cli.js'), launcher('/usr/bin/node'), `#!/bin/sh\nexec '${NODE}' '${CLI}' "$@"\necho hi\n`,
+ `#!/bin/sh\nexec '${NODE}' '${CLI}' --inspect "$@"\n`, `#!/bin/bash\nexec '${NODE}' '${CLI}' "$@"\n`, 'x'.repeat(5000)]) {
+ expect(await prefix({}, 'machine-1', fake({ [PATH]: text }))).toBe(today)
+ }
+ })
+ it('is the full command when the daemon carries a flag other than V8 memory flags, or has no script', async () => {
+ const loader = { command: `'${NODE}' '--import' 'tsx' '${CLI}'`, port: 18473 }
+ expect(await prefix(loader)).toBe(`${loader.command} super-tab --port 18473 --machine 'machine-1'`)
+ expect(await prefix({ command: `'${NODE}'` })).toBe(`'${NODE}' super-tab --port 18473 --machine 'machine-1'`)
+ expect(await prefix({ command: '' })).toBe(' super-tab --port 18473 --machine \'machine-1\'')
+ })
+ it('is the full command when a path cannot be resolved', async () => {
+ expect(await prefix({}, 'machine-1', { ...fake({ [PATH]: launcher() }), realpath: () => { throw new Error('ENOENT') } })).toBe(today)
+ })
+ it('reads the installer\'s own quoting for a path with an apostrophe, and the double quotes the installed launcher uses', async () => {
+ const cli = "/home/o'neil/.harness/cli/cli.js"
+ const command = `'${NODE}' '--max-old-space-size=4096' '${cli.replace(/'/g, `'"'"'`)}'`
+ expect(await prefix({ command }, 'machine-1', fake({ [PATH]: launcher(NODE, cli.replace(/'/g, `'\\''`)) }))).toBe('harness super-tab')
+ expect(await prefix({}, 'machine-1', fake({ [PATH]: `#!/bin/sh\nexec "${NODE}" "${CLI}" "$@"\n` }))).toBe('harness super-tab')
+ })
+ it('names the full command the same way the host falls back to it', () => {
+ expect(fullCommandPrefix(daemon, 'machine-1')).toBe(today)
+ })
+})
+
+describe('the real files', () => {
+ it('is the full command with nothing handed in: specs start no shell', async () => {
+ expect(await agentCommandPrefix(daemon, 'machine-1', defaultMachine)).toBe(today)
+ })
+ it('reads the launcher from disk, and follows a symbolic link to the cli.js it runs', async () => {
+ const dir = mkdtempSync(join(tmpdir(), 'short-command-'))
+ try {
+ const real = join(dir, 'cli.js'), link = join(dir, 'link.js'), file = join(dir, 'harness')
+ writeFileSync(real, ''); symlinkSync(real, link)
+ writeFileSync(file, launcher(NODE, link))
+ const command = { command: `'${NODE}' '${real}'`, port: 18473 }
+ expect(await agentCommandPrefix(command, 'machine-1', defaultMachine, { platform: 'linux', env: {}, resolve: async () => file })).toBe('harness super-tab')
+ } finally { rmSync(dir, { recursive: true, force: true }) }
+ })
+})
+
+describe('the super-tab command an agent is told to run (Windows)', () => {
+ const EXE = 'C:\\Users\\a\\.harness\\bin\\harness.exe'
+ const win = (found: string | null, current: { cliJs: string } | null = { cliJs: 'C:\\Users\\a\\.harness\\cli\\1.0\\cli.js' }): ShortCommandDeps => ({
+ platform: 'win32', env: {}, resolve: async () => found, realpath: path => path, windowsCli: root => root === 'C:\\Users\\a\\.harness' ? current : null })
+ const command = { command: `'C:\\node.exe' '--max-old-space-size=4096' 'C:\\Users\\a\\.harness\\cli\\1.0\\cli.js'`, port: 18473 }
+ const windowsToday = fullCommandPrefix(command, 'machine-1')
+ const ask = (deps: ShortCommandDeps, over = {}) => agentCommandPrefix({ ...command, ...over }, 'machine-1', defaultMachine, deps)
+ it('is `harness` when bin\\harness.exe is the one that runs the CLI the daemon runs, with the default port and this machine left out', async () => {
+ expect(await ask(win(EXE))).toBe('harness super-tab')
+ })
+ it('keeps the non-default port, and matches the folder names without regard to case', async () => {
+ expect(await ask(win('C:\\Users\\a\\.harness\\bin\\HARNESS.EXE'), { port: 19000 })).toBe(`harness super-tab --port 19000 --machine 'machine-1'`)
+ })
+ it('is the full command when harness.exe is absent, is another program, or runs a different version', async () => {
+ expect(await ask(win(null))).toBe(windowsToday)
+ expect(await ask(win('C:\\tools\\harness.cmd'))).toBe(windowsToday)
+ expect(await ask(win(EXE, { cliJs: 'C:\\Users\\a\\.harness\\cli\\2.0\\cli.js' }))).toBe(windowsToday)
+ expect(await ask(win(EXE, null))).toBe(windowsToday)
+ expect(await ask(win('D:\\other\\bin\\harness.exe'))).toBe(windowsToday)
+ })
+ it('is the full command when the install cannot be read', async () => {
+ expect(await ask({ ...win(EXE), realpath: () => { throw new Error('EACCES') } })).toBe(windowsToday)
+ })
+ it('asks the real layout reader when none is handed in, and stays full when that install does not exist', async () => {
+ const { windowsCli, ...deps } = win('C:\\no\\such\\bin\\harness.exe')
+ expect(windowsCli).toBeTypeOf('function')
+ expect(await ask(deps)).toBe(windowsToday)
+ })
+ it('looks `harness` up on PATH when no lookup is handed in', async () => {
+ expect(await ask({ platform: 'win32', env: { PATH: 'C:\\no\\such' }, exists: () => false, realpath: p => p })).toBe(windowsToday)
+ })
+})
+
+describe('windowsResolve', () => {
+ const exists = (...files: string[]) => (path: string) => files.includes(path)
+ it('is harness.exe in the first PATH folder that has any form of harness', () => {
+ expect(windowsResolve({ PATH: 'C:\\a;C:\\b' }, exists('C:\\a\\harness.exe', 'C:\\b\\harness.ps1'))).toBe('C:\\a\\harness.exe')
+ expect(windowsResolve({ Path: 'C:\\a;;C:\\b' }, exists('C:\\b\\harness.exe'))).toBe('C:\\b\\harness.exe')
+ })
+ it.each(['harness.ps1', 'harness.cmd', 'harness.bat'])('is null when an earlier folder has only %s, which would run instead of the exe', name => {
+ expect(windowsResolve({ PATH: `C:\\a;C:\\b` }, exists(`C:\\a\\${name}`, 'C:\\b\\harness.exe'))).toBeNull()
+ })
+ it('is null when nothing is found, or there is no PATH', () => {
+ expect(windowsResolve({ PATH: 'C:\\a' }, exists())).toBeNull()
+ expect(windowsResolve({}, exists())).toBeNull()
+ expect(windowsResolve({ PATH: 'C:\\no\\such\\folder' })).toBeNull()
+ })
+})
+
+describe('shellWords', () => {
+ it('splits a POSIX line the way the installers quote it', () => {
+ expect(shellWords(`exec 'a b' "c d" e\\ f 'it'\\''s' ""`)).toEqual(['exec', 'a b', 'c d', 'e f', "it's", ''])
+ expect(shellWords('x\\')).toEqual(['x\\'])
+ expect(shellWords(`a'b'"c" \\d`)).toEqual(['abc', 'd'])
+ })
+})
+
+describe('the lookup in the agent\'s shell', () => {
+ // Stand-in shells in a temp folder: the developer's own is never started. `-lic` is the interactive login ask, `-lc` the plain one.
+ const standIn = async (interactive: string, plain: string) => {
+ const dir = mkdtempSync(join(tmpdir(), 'short-shell-'))
+ const shell = join(dir, 'zsh')
+ writeFileSync(shell, ['#!/bin/sh', 'case "$1" in', `-lic) printf 'banner\\n\\n%s\\n' '${interactive}';;`, `-lc) printf '%s\\n' '${plain}';;`, 'esac', ''].join('\n'))
+ chmodSync(shell, 0o755)
+ try { return await shellResolve(shell) } finally { rmSync(dir, { recursive: true, force: true }) }
+ }
+ it('is the file both the interactive login shell and the plain login shell find', async () => {
+ expect(await standIn('/stand/in/harness', '/stand/in/harness')).toBe('/stand/in/harness')
+ })
+ it('is null when they disagree, when the plain one finds nothing, or the interactive one does', async () => {
+ expect(await standIn('/usr/local/bin/harness', '/stand/in/harness')).toBeNull()
+ expect(await standIn('/stand/in/harness', '')).toBeNull()
+ expect(await standIn('alias harness=x', '/stand/in/harness')).toBeNull()
+ })
+ it('is null when specs run: no shell is started', async () => {
+ expect(await shellResolve()).toBeNull()
+ })
+ it('takes the account\'s shell when none is handed in outside the specs', async () => {
+ const dir = mkdtempSync(join(tmpdir(), 'short-shell-'))
+ try {
+ const shell = join(dir, 'zsh')
+ writeFileSync(shell, `#!/bin/sh\nprintf '/stand/in/harness\\n'\n`)
+ chmodSync(shell, 0o755)
+ vi.stubEnv('NODE_ENV', 'production'); vi.stubEnv('SHELL', shell)
+ expect(await shellResolve()).toBe('/stand/in/harness')
+ } finally { vi.unstubAllEnvs(); rmSync(dir, { recursive: true, force: true }) }
+ })
+})
diff --git a/cli/src/superTabs/shortCommand.ts b/cli/src/superTabs/shortCommand.ts
new file mode 100644
index 000000000..2a78c3151
--- /dev/null
+++ b/cli/src/superTabs/shortCommand.ts
@@ -0,0 +1,127 @@
+/**
+ * The `super-tab` command an agent is told to run, as short as it can be and still work.
+ *
+ * Every delivered message names this command five or six times. Spelled out it is the daemon's Node, its V8 flags, its
+ * cli.js, `--port` and `--machine`, which cost the agent context and read badly. The installers put a `harness` launcher
+ * on PATH (`~/.local/bin/harness` on a Mac or Linux, `bin\harness.exe` on Windows) that runs the same CLI, so `harness
+ * super-tab …` does the same thing, but only when that launcher is the one this daemon runs. A launcher left by another
+ * build, a development checkout, or a folder that is not on the agent's PATH would run the wrong CLI or none, so each of
+ * those keeps the full command. `--port` and `--machine` are dropped only when the CLI would choose the same values by
+ * itself (`whereFor` in agentClient/daemon.ts) in the agent's shell, which has none of the daemon's own environment: a
+ * tmux pane gets no PORT, ADAPTER_DATA_DIR or HARNESS_AUTH_DIR. So a daemon started with any of them (an isolated end-to-end
+ * daemon, `harness tui`) keeps both flags, or its agents would talk to the default daemon.
+ */
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import { win32 } from 'node:path'
+import { currentCli } from '../lib/windows/installLayout.js'
+import { probe, resolveViaLoginShell } from '../lib/tmuxOnPath.js'
+import { currentUserShell } from '../lib/userShell.js'
+import { shellQuote } from '../orchestrator/prompts.js'
+
+/** The port the CLI uses when nothing says otherwise (config/env.ts PORT). */
+const DEFAULT_PORT = 18473
+/** What moves the daemon (or the CLI's idea of it) off the defaults. The agent's shell does not have them. */
+const ISOLATING = ['PORT', 'ADAPTER_DATA_DIR', 'ADAPTER_CLI_DIR', 'HARNESS_AUTH_DIR', 'HARNESS_ENV_FILE', 'ADAPTER_COMPUTER_ID', 'ADAPTER_COMPUTER_ID_FILE']
+
+export interface ShortCommandDeps {
+ platform?: NodeJS.Platform
+ /** The daemon's environment. */
+ env?: NodeJS.ProcessEnv
+ /** The file an agent's shell runs for `harness`, or null: it is not there, or the answer is not a file. */
+ resolve?: () => Promise<string | null>
+ readFile?: (path: string) => string
+ exists?: (path: string) => boolean
+ realpath?: (path: string) => string
+ /** The CLI a Windows install's `cli\current` names. */
+ windowsCli?: (root: string) => { cliJs: string } | null
+}
+
+/** A POSIX shell word list: single and double quotes, and a backslash outside quotes. Enough for what the installers write. */
+export function shellWords(text: string): string[] {
+ const words: string[] = []
+ let word: string | null = null, quote = ''
+ for (let i = 0; i < text.length; i++) {
+ const c = text[i]
+ if (quote) { if (c === quote) quote = ''; else word += c; continue }
+ if (c === "'" || c === '"') { quote = c; word ??= ''; continue }
+ if (c === '\\' && i + 1 < text.length) { word = (word ?? '') + text[++i]; continue }
+ if (/\s/.test(c)) { if (word !== null) words.push(word); word = null; continue }
+ word = (word ?? '') + c
+ }
+ if (word !== null) words.push(word)
+ return words
+}
+
+/**
+ * What the agent's shell runs for `harness`: the person's own login shell, since a pane's PATH is what their startup files
+ * make it, and again as a plain login shell with no rc file, as the subshell of an agent's tool runs (`path_helper` can put
+ * /usr/local/bin ahead there). Both must give the same file, else null.
+ */
+export async function shellResolve(
+ // A spec must never start the developer's own shell (cli/AGENTS.md, rule 6).
+ shell: string | undefined = process.env.NODE_ENV === 'test' ? undefined : currentUserShell(),
+): Promise<string | null> {
+ if (!shell) return null
+ const [own, plain] = await Promise.all([resolveViaLoginShell('harness', shell), probe(shell, ['-lc'], 'harness')])
+ return own && own === plain ? own : null
+}
+
+/**
+ * `harness` as PowerShell and cmd find it: the first PATH folder holding any form of it decides. Only `harness.exe` is ours;
+ * a `harness.ps1` or `.cmd` earlier on PATH would be run instead of it.
+ */
+export function windowsResolve(env: NodeJS.ProcessEnv = process.env, exists: (path: string) => boolean = existsSync): string | null {
+ for (const dir of (env.PATH ?? env.Path ?? '').split(';').filter(Boolean)) {
+ for (const name of ['harness.exe', 'harness.cmd', 'harness.bat', 'harness.ps1']) {
+ const file = win32.join(dir, name)
+ if (exists(file)) return name === 'harness.exe' ? file : null
+ }
+ }
+ return null
+}
+
+/** Whether [launcher] is the installer's script and runs the same Node and cli.js as [words] (the daemon's command, split). */
+function runsSameCli(launcher: string, words: string[], deps: Required<Pick<ShortCommandDeps, 'readFile' | 'realpath'>>): boolean {
+ let exec: string[]
+ try {
+ const text = deps.readFile(launcher)
+ // Exactly what install.sh writes. Any other shape could do anything, so it is not trusted.
+ if (text.length > 4096 || !text.startsWith('#!/bin/sh\nexec ') || text.indexOf('\n', 15) !== text.length - 1) return false
+ exec = shellWords(text.slice(10))
+ } catch { return false }
+ const [node, script] = [words[0], words[words.length - 1]]
+ // Between them the daemon may carry only V8 memory flags; a loader or another flag changes what runs.
+ if (exec.length !== 4 || exec[3] !== '$@' || words.length < 2 || !words.slice(1, -1).every(w => w.startsWith('--max-'))) return false
+ try { return exec[1] === node && deps.realpath(exec[2]) === deps.realpath(script) } catch { return false }
+}
+
+/** What every delivery named before this file: the daemon's own command, spelled out. */
+export const fullCommandPrefix = (daemon: { command: string; port: number }, machineId: string): string =>
+ `${daemon.command} super-tab --port ${daemon.port} --machine ${shellQuote(machineId)}`
+
+/**
+ * `harness super-tab …` when it would run this daemon's CLI for the agent, else the daemon's full command; with the flags
+ * the CLI would not choose for itself. Costs a shell start, so the caller asks once and keeps the answer.
+ */
+export async function agentCommandPrefix(
+ daemon: { command: string; port: number }, machineId: string, defaultMachine: () => string, deps: ShortCommandDeps = {},
+): Promise<string> {
+ const platform = deps.platform ?? process.platform
+ const environment = deps.env ?? process.env
+ const words = shellWords(daemon.command)
+ const found = await (deps.resolve ?? (platform === 'win32' ? () => Promise.resolve(windowsResolve(environment, deps.exists)) : shellResolve))().catch(() => null)
+ const realpath = deps.realpath ?? realpathSync
+ let short = false
+ if (found && words.length) {
+ try {
+ if (platform === 'win32') {
+ // bin\harness.exe finds its install from its own folder (pty/src/command.rs): the CLI is the one `cli\current` names.
+ const cli = win32.basename(found).toLowerCase() === 'harness.exe' ? (deps.windowsCli ?? currentCli)(win32.dirname(win32.dirname(found))) : null
+ short = !!cli && realpath(cli.cliJs).toLowerCase() === realpath(words[words.length - 1]).toLowerCase()
+ } else short = runsSameCli(found, words, { readFile: deps.readFile ?? (p => readFileSync(p, 'utf8')), realpath })
+ } catch { short = false }
+ }
+ if (!short) return fullCommandPrefix(daemon, machineId)
+ const plain = daemon.port === DEFAULT_PORT && !ISOLATING.some(name => environment[name])
+ return `harness super-tab${plain ? '' : ` --port ${daemon.port}`}${plain && machineId === defaultMachine() ? '' : ` --machine ${shellQuote(machineId)}`}`
+}
diff --git a/cli/vitest.super-tabs.config.ts b/cli/vitest.super-tabs.config.ts
index 9160cfbdb..9e748c33c 100644
--- a/cli/vitest.super-tabs.config.ts
+++ b/cli/vitest.super-tabs.config.ts
@@ -4,7 +4,7 @@ import base from './vitest.config.js'
/** Super Tab routing v1 (docs/superpowers/specs/2026-10-19-super-tab-routing-v1-design.md): new files outside
* the core and services, which no other gate covers, held to 100% in every file. */
-const FILES = ['src/superTabs/route.ts', 'src/superTabs/routeCommand.ts']
+const FILES = ['src/superTabs/route.ts', 'src/superTabs/routeCommand.ts', 'src/superTabs/shortCommand.ts']
export default defineConfig({
test: {
...base.test,