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 type { NativeLaunch, NativeLaunchResult, NativeLaunchSource } from '../../engines/nativeLaunch.js'
/**
* Creating an agent (`agent_create`): open a fresh pane running the chosen engine in the chosen
* folder, as a domain-specific harness or a plain session, on a grid or the engine's own login, opening
* a conversation Harness did not start when asked — and refuse, before any pane opens, every launch
* that would not do what was asked. The pane is then watched until its engine is up.
*
* Moved verbatim out of `runForeground` (the core boundary, step 11: docs/design/2026-10-03-harnessd.md).
*/
import { agentTmpLaunch, buddyTmpEnv } from '../../lib/agentTmp.js'
import { realpathSync, statSync } from 'node:fs'
import { readdir, stat } from 'node:fs/promises'
import { dirname, join } from 'node:path'
import type { BackendSocket } from '../../backendSocket.js'
import type { ModelsPort, SwarmLaunch } from '../api.js'
import { MODEL_MANAGER_ID } from '../../dsh/builtinIds.js'
import { installedDsh } from '../../dsh/installed.js'
import { harnessEnvToClear, type DshAccount } from '../../dsh/launch.js'
import { dshPinnedPermissionMode } from '../../dsh/manifest.js'
import { incompatibleHarnessEngine } from '../../dsh/compatibility.js'
import type { DshThrough } from './dshThrough.js'
import * as opencodeLaunch from '../../engines/launchControl.js'
import { isTerminalEngine, type AgentEngine } from '../../engines/types.js'
import { engineLabel } from '../../lib/agentNames.js'
import { createAndRegisterPane } from '../../lib/createAgentPane.js'
import { enginePathOverride } from '../../lib/engineBin.js'
import { engineInstallRecipe } from '../../lib/engineInstall.js'
import {
buildEngineCommandArgv, buildEngineLaunchArgv, engineLaunchEnv, namedAgentArgs, permissionModeApproves, permissionModeFlags,
refusePermissionFlagIfUnsupported, supportsFirstPrompt, supportsNamedAgent, NamedAgentUnsupportedError,
} from '../../lib/engineLaunch.js'
import { setUpWithin } from '../../lib/setUpWithin.js'
import { agentLaunchArgs, joinedInstructions } from '../../lib/agentAttribution.js'
import { machineMcpLaunchArgs } from '../../lib/machineMcp.js'
import { writeGridConfigDir } from '../../lib/gridConfigDir.js'
import { describeGridLaunch, gridConfigHandOff, gridConflictingEnvToClear, type GridLaunchAnswer, type GridLaunchMachine, type GridLaunchRequest, type GridWebSearchStatus } from '../../lib/gridLaunchWire.js'
import { syncProfileHome } from '../../lib/connectors/agents.js'
import { Store as ConnectionsVault } from '../../lib/connectors/store.js'
import { profileEnvironment } from '../../lib/engineHomes.js'
import { DEFAULT_HARNESS_PERMISSION, freshHarnessEnvironment } from '../../lib/harnessDefaults.js'
import { buildHarnessSessionLabel } from '../../lib/harnessSessionLabel.js'
import type { LaunchAuthority, LaunchPreparation } from '../../lib/launchPreparation.js'
import type { publishGridConfigDir } from '../../lib/publishedGridConfig.js'
import { nativeHookLocations } from '../../engines/kit/nativeLocations.js'
import { engineHooks } from '../../engines/hooks.js'
import { folderTrust } from '../../engines/launchPrep.js'
import { projectsRoot } from '../../lib/projectFolder.js'
import { harnessMadeWorktree } from '../../lib/gitProject.js'
import { NativeFiles } from '../../engines/kit/nativeFiles.js'
import type { registry, RegisteredSession } from '../../lib/registry.js'
import { parseSwarmSkill } from '../../lib/savedSkill.js'
import type { TerminalBackend } from '../../lib/terminalBackend.js'
import { windowsLaunchRefusal } from '../../lib/windows/launch.js'
import { isWindowsHeldPane, windowsPaneLaunch } from '../../lib/windows/engineStart.js'
import { tmuxTooOldForSessionEnv } from '../../lib/tmuxVersion.js'
import { prepareInstructionWrites, scmLaunchEnv } from '../../scm/scmProjects.js'
import { mergedLaunchEnv } from './launchEnv.js'
import type { createPaneWatcher } from './newPane.js'
/** How long creating a Model Manager waits for grid to be set up before its workspace asks grid which
* grid is this account's. Short: the app gives the whole create 20s, and a first install takes minutes.
* Past it the set-up carries on, and the agent's own `harness grid setup` waits for it. */
const MODEL_MANAGER_GRID_WAIT_MS = 8_000
type CreateAgent = NonNullable<BackendSocket['onCreateAgent']>
export interface CreateAgentDeps {
publishConfig?: typeof publishGridConfigDir
native?: (engine: AgentEngine, source: NativeLaunchSource, authority: LaunchAuthority) => Promise<NativeLaunchResult>
/** The backend new panes are made on; null where none is configured or could be readied. */
createBackend: TerminalBackend | null
/** Recheck a backend missing at boot after its runtime has been installed. Healthy launches never call it. */
recoverBackend?: () => Promise<TerminalBackend | null>
/** What a launch answers when [createBackend] is null: the configured backend's own code (terminalBackend.ts
* `noBackendCode`); `TMUX_UNAVAILABLE`, as before, by default. */
noBackendCode?: string
registry: typeof registry
externalResume: CreateAgent
watchNewPane: ReturnType<typeof createPaneWatcher>
announceSession: (session: RegisteredSession) => void
attachDsh: (session: RegisteredSession) => void
prepareApiTools: (cwd: string | null | undefined, engine: string) => void
/** The hook server's port, which installed engine hooks post to. */
hookPort: number
/** Whether engine hooks are installed at all (DISABLE_HOOK_INSTALL). */
hooksDisabled: boolean
/** OpenCode's plugin, installed again before an OpenCode spawn (core/engines/hooks.ts
* `installOpencodePluginBeforeSpawn`): eager, independent of optional interpretation. */
installOpencodePlugin: (port: number) => Promise<boolean>
/** The facts about this machine a launch of `engine` needs (lib/gridLaunch.ts). */
gridLaunchMachine: (engine: AgentEngine, native?: NativeLaunch) => GridLaunchMachine | Promise<GridLaunchMachine>
/** A grid or saved-API launch, built by the models service (core/agents/launch.ts `gridLaunchThrough`): the core
* builds none itself, and a create on a grid while models is down is refused (GRID_UNAVAILABLE). */
buildGridLaunch: (request: GridLaunchRequest) => Promise<GridLaunchAnswer>
terminalHintMachineName: () => string
/** Whether a folder is being purged (PurgeAgentService.blocksFolder). */
blocksFolder: (cwd: string) => boolean | undefined
/** Grid set-up, when this daemon can do it: the models service's (core/api.ts `ModelsPort.ensure`), null
* while it is off. */
gridSetup: () => ModelsPort['ensure'] | null
privateGridName: () => Promise<string | null>
dshLaunch: Pick<DshThrough, 'materialize' | 'launch'>
/** The Swarm's part of a start with a Swarm role (superTabs/inCore/launch.ts); absent while the Swarm is off. */
swarmLaunch?: SwarmLaunch
}
/** A Git checkout directly in the projects root (a clone the desktop made there), or a worktree Harness made. */
async function swarmFolder(cwd: string): Promise<boolean> {
const root = projectsRoot()
if (dirname(cwd) === root) return stat(join(cwd, '.git')).then(info => info.isDirectory(), () => false)
return harnessMadeWorktree(cwd, root)
}
export function createAgentCreator({
native: inspectNative, publishConfig, createBackend: initialBackend, recoverBackend, noBackendCode = 'TMUX_UNAVAILABLE', registry, externalResume, watchNewPane, announceSession, attachDsh,
prepareApiTools, hookPort, hooksDisabled, installOpencodePlugin, gridLaunchMachine, buildGridLaunch, terminalHintMachineName, blocksFolder,
gridSetup, privateGridName, dshLaunch, swarmLaunch,
}: CreateAgentDeps) {
const prepare = async (input: Parameters<CreateAgent>[0], authority: LaunchAuthority, context?: { local: boolean }): Promise<LaunchPreparation<Awaited<ReturnType<CreateAgent>>>> => {
if (input.resumeSessionId) return { ok: true, dispatch: () => externalResume(input) }
const stale = () => ({ ok: false as const, error: 'LAUNCH_AUTHORITY_CHANGED', unavailable: 'launch', detail: 'Waiting for the original launch request’s authority.' })
if (!authority.current()) return stale()
if (input.swarmRole && !swarmLaunch) return { ok: false, error: 'SWARM_SKILL_FAILED', detail: 'The Swarm is off on this computer (HARNESS_SWARM).' }
let { engine, cwd, bypassPermission, permissionMode, grid, codexHome, claudeHome, dsh, prompt, name, agent, scmLaunchRecord, startedBy, parentAgentId, launchModel } = input
let createBackend = initialBackend
if (!createBackend && recoverBackend) {
createBackend = await recoverBackend()
if (!authority.current()) return stale()
}
if (!createBackend) return { ok: false, error: noBackendCode }
if (blocksFolder(cwd)) return { ok: false, error: 'WORKTREE_BUSY' }
const workspaceIdentity = () => { const info = statSync(cwd); return `${info.dev}:${info.ino}:${realpathSync(cwd)}` }
let originalWorkspace: string
try {
if (!statSync(cwd).isDirectory()) return { ok: false, error: 'CWD_NOT_FOUND' }
originalWorkspace = workspaceIdentity()
} catch {
return { ok: false, error: 'CWD_NOT_FOUND' }
}
// The local Desktop already made this workspace. Observe emptiness before any
// preparation writes, but grant trust only after its dependencies are ready.
const trustEmptyProject = context?.local === true && !dsh && dirname(cwd) === projectsRoot()
&& await readdir(cwd).then(names => names.length === 0, () => false)
// A Swarm agent's folder has content: the desktop's New Swarm clones a GitHub project into the projects root, or makes
// a worktree of a local repository, itself, and sends the folder as a plain cwd. 2026-10-30: a Cmd+S Swarm's PM sat
// at Claude Code's "do you trust this folder?", which no Swarm view shows; it read Idle and every message to it was
// withheld. The person chose that repository for the Swarm in this window, so a Claude Code Swarm agent, in whatever mode
// its owner's settings give (task #4215), is trusted in a Git checkout directly in the projects root or a worktree Harness
// made, read from disk.
// Never from a relayed request, which could name any repository here. Codex's trust also sets defaults for the
// person's own sessions in that folder, so it stays theirs to give.
const trustSwarmFolder = !trustEmptyProject && context?.local === true && !dsh && engine === 'claude' && !!input.swarmRole
&& await swarmFolder(cwd)
if (!authority.current()) return stale()
// A harness can pin its permission mode (`dshPinnedPermissionMode`): the Grid harness starts model
// servers, which Codex's sandbox would start without a GPU. Pinned before anything reads the mode,
// and recorded on the row like a chosen one, so a relaunch keeps it.
const pinnedDsh = dsh ? installedDsh(dsh) : null
const pinnedMode = pinnedDsh ? dshPinnedPermissionMode(pinnedDsh.manifest) : null
if (pinnedMode && permissionModeFlags(engine, pinnedMode)) {
permissionMode = pinnedMode
bypassPermission = permissionModeApproves(pinnedMode)
}
const inspected = await inspectNative?.(engine, { ...input, permissionMode, bypassPermission }, authority)
// An engine that ran and failed, or whose install for this request failed, is refused with its own
// reason. Held, a creation retried every two seconds and could start, task and all, whenever the
// engine was repaired: a Codex installed with npm on a computer without Node (fresh Ubuntu VM,
// 2026-10-11) held for good, and `harness new` said only that it could not confirm. A relaunch,
// which nobody is waiting on, still holds.
if (inspected && !inspected.ok) return inspected.refusal ? { ok: false, error: inspected.refusal, detail: inspected.detail } : inspected
const native = inspected?.ok ? inspected.launch : undefined
if (engine === 'codex' && native) codexHome = nativeHookLocations(native.environment).CODEX_HOME
const current = () => authority.current() && (!native || native.current())
if (!current()) return stale()
if (native && agent && !supportsNamedAgent(engine, native.opencodeMajor)) {
return { ok: false, error: 'AGENT_UNSUPPORTED', detail: new NamedAgentUnsupportedError(engine).message }
}
// An engine too old for the flag this permission mode launches it with prints its help and
// exits; the wrapper then hands the pane to a shell, and what the person gets is a terminal
// full of help text with nothing anywhere saying why (openharness#285, opencode without
// `--auto`). Refuse before opening a pane — this is a launch somebody is waiting on, and Ask
// works today. Codex has been checked this way since it gained `--approve-for-me`; every other
// engine with a permission flag was not, and carried the same failure.
const refusal = await refusePermissionFlagIfUnsupported(engine, { permissionMode, bypassPermission }, undefined, native)
if (!current()) return stale()
if (refusal) {
console.warn(`[agent] create refused · ${engine} · ${refusal.detail}`)
return { ok: false, ...refusal }
}
// Native version and model control are eager; optional readers never decide whether a launch can proceed.
const opencode = engine === 'opencode' ? opencodeLaunch : null
// Harness-created sessions are easy to distinguish from a user's organic tmux sessions while
// retaining the engine and a collision-resistant creation suffix for diagnostics. Computed
// before the grid block because a file-configured engine keys its config directory on it.
// The `harness-` prefix is also discovery's whitelist for a pane nobody tagged (see `ownedHere` /
// `TmuxBackend.inventory()`): the panes this daemon creates carry its tag, which goes with them into
// any session the person moves them to.
const label = authority.label
// Prepare the harness workspace, then bind its session context to the selected engine.
// Missing packages or invalid runtimes refuse the launch before the agent is started.
let dshEnv: Record<string, string> | undefined
let dshArgs: string[] = []
/** A DSH's own name ("Blender"), which the agent is named after instead of its engine. */
let dshLabel: string | undefined
/** What the harness is told about the signed-in account (its private grid), not left to guess. */
let dshAccount: DshAccount = {}
const installed = dsh ? installedDsh(dsh) : undefined
if (dsh) {
if (!installed) return { ok: false, error: 'INVALID_DSH', detail: `${dsh} is not installed on this machine` }
if (installed.manifest.kind === 'viewer') return { ok: false, error: 'INVALID_DSH', detail: `${dsh} is a viewer package, not an agent` }
const refusal = incompatibleHarnessEngine(dsh, installed.manifest, engine)
if (refusal) {
return { ok: false, error: 'INVALID_DSH', detail: refusal }
}
if (!(await createBackend.capabilities()).sessionEnv) {
const detail = `${tmuxTooOldForSessionEnv('a new session')} — so ${installed.manifest.name} `
+ `could not tell ${engine} which harness it is. Upgrade tmux.`
console.warn(`[agent] create ${dsh} refused · ${detail}`)
return { ok: false, error: 'TMUX_TOO_OLD_FOR_DSH', detail }
}
}
// A grid is the user's answer to "where should this run", so every way of not honouring it is a
// refusal rather than a fallback — an agent silently started on the engine's own login spends the
// wrong account and looks identical to one that worked. Asked of models before a harness's workspace is
// laid out or trusted: a create refused here leaves the folder as it was.
const built = grid ? await buildGridLaunch({ engine, override: grid, machine: await gridLaunchMachine(engine, native) }) : null
if (!current()) return stale()
if (built && !built.ok) {
console.warn(`[agent] create ${engine} refused · ${built.detail}`)
return built
}
if (dsh) {
// Checked above: a harness that is not installed was refused before models was asked.
const harness = installed!
// The Model Manager is grid in use, however it was made (the Store, New Harness, `harness new`, the
// models picker): grid is set up before the workspace asks it which grid is this account's.
const ensureGrid = gridSetup()
if (harness.id === MODEL_MANAGER_ID && ensureGrid) {
const setUp = await setUpWithin(() => ensureGrid({ ownGrid: true }), MODEL_MANAGER_GRID_WAIT_MS)
if (setUp === 'pending') console.log(`[dsh] ${dsh} · grid is still being set up; the agent waits for it with \`harness grid setup\``)
}
try {
dshAccount = { privateGrid: await privateGridName().catch(() => null) }
if (!current()) return stale()
// Asked BEFORE the template goes in: afterwards every folder has content.
// Not there yet is empty; unreadable is not — trust is only ever granted on evidence.
const emptyBefore = await readdir(cwd).then((names) => names.length === 0,
(error: NodeJS.ErrnoException) => error.code === 'ENOENT')
if (!current()) return stale()
const materialized = await dshLaunch.materialize({ dsh, workspace: cwd, account: dshAccount, engine, key: label })
if (!current()) return stale()
if (!materialized.ok) {
if (materialized.unavailable) return materialized
throw new Error(materialized.detail)
}
for (const warning of materialized.warnings) console.warn(`[dsh] ${dsh} materialize · ${warning}`)
console.log(`[dsh] ${dsh} materialized ${cwd} · created ${materialized.created.length} · kept ${materialized.kept.length}`)
// The template just went into an EMPTY folder: everything in it is the harness's, and Claude Code
// need not ask. Laid into a folder that already held something — a clone, the person's own repo —
// it proves nothing about the rest, so trust stays the person's call (engines/kit/folderTrust.ts).
if (emptyBefore && materialized.created.some((item) => item.startsWith('template'))) {
try {
// In the agent's own profile when it has one: that config.toml is the one a Codex agent reads.
folderTrust(engine, engine === 'claude' ? claudeHome : codexHome)?.record(cwd)
} catch (error) { console.warn(`[dsh] pre-trust ${cwd} · ${error instanceof Error ? error.message : error}`) }
}
} catch (error) {
const detail = `could not prepare the workspace for ${dsh} · ${error instanceof Error ? error.message : error}`
console.warn(`[agent] create ${dsh} refused · ${detail}`)
return { ok: false, error: 'DSH_MATERIALIZE_FAILED', detail }
}
const prepared = await dshLaunch.launch({ dsh, workspace: cwd, engine, key: label, account: dshAccount })
if (!current()) return stale()
if (!prepared.ok) return { ok: false, error: prepared.error, detail: prepared.detail,
...(prepared.unavailable ? { unavailable: prepared.unavailable } : {}) }
dshEnv = prepared.launch.env
dshArgs = prepared.launch.args
dshLabel = harness.manifest.name
}
let gridLaunch: { env: Record<string, string>; args: string[]; webSearch: GridWebSearchStatus } | undefined
if (grid && built?.ok) {
if (!(await createBackend.capabilities()).sessionEnv) {
const detail = `${tmuxTooOldForSessionEnv('a new session')} — so ${engine} could not have been pointed at grid `
+ `${grid.networkName}. Upgrade tmux, or create this agent without a grid selected.`
console.warn(`[agent] create ${engine} refused · ${detail}`)
return { ok: false, error: 'TMUX_TOO_OLD_FOR_GRID', detail }
}
if (!current()) return stale()
gridLaunch = { env: { ...built.launch.env }, args: built.launch.args, webSearch: built.launch.webSearch }
// An engine whose provider lives in a file gets a directory this daemon owns, never the
// user's own dotfiles. The label is unique per creation, so two agents never share one.
if (built.launch.configDir) {
const { files, links } = built.launch.configDir
try {
const publication = native && publishConfig ? await publishConfig(label, files, links, current) : null
if (publication && !native?.retain?.(publication.proof)) return stale()
const dir = publication?.directory ?? await writeGridConfigDir(label, files, links)
const handOff = gridConfigHandOff(built.launch.configDir, dir)
Object.assign(gridLaunch.env, handOff.env)
gridLaunch.args = [...gridLaunch.args, ...handOff.args]
} catch (error) {
const detail = `could not write ${engine}'s grid configuration · ${error instanceof Error ? error.message : error}`
console.warn(`[agent] create ${engine} refused · ${detail}`)
return { ok: false, error: 'GRID_CONFIG_FAILED', detail, ...(native ? { unavailable: 'native' } : {}) }
}
}
// Named in the log because the pane itself gives nothing away: the engine looks exactly like a
// normally launched one. The key is never printed.
console.log(describeGridLaunch(engine, grid, built.launch.webSearch))
}
if (!current()) return stale()
if (trustEmptyProject || trustSwarmFolder) {
try {
// A clone or user edit can arrive while dependencies are being prepared.
// Trust only the same physical workspace, still empty at the write boundary (a Swarm agent's, still the same).
const files = new NativeFiles()
const empty = files.entries(cwd).length === 0
if (!current()) return stale()
if ((empty || trustSwarmFolder) && workspaceIdentity() === originalWorkspace) {
files.verify()
const environment = native ? { ...native.environment, ...gridLaunch?.env, ...dshEnv } : undefined
const profile = engine === 'codex' && environment ? nativeHookLocations(environment).CODEX_HOME : engine === 'claude' ? claudeHome : codexHome
folderTrust(engine, profile, environment)?.record(cwd)
}
} catch (error) { console.warn(`[agent] pre-trust ${cwd} · ${error instanceof Error ? error.message : error}`) }
}
if (native && !await native.prepareHooks(hooksDisabled ? 0 : hookPort, authority.current,
{ ...gridLaunch?.env, ...dshEnv }, gridLaunch ? gridConflictingEnvToClear(gridLaunch) : [])) return {
ok: false, error: 'NATIVE_LAUNCH_HELD', detail: 'Waiting to confirm the engine’s native hooks.', unavailable: 'native',
}
// Harness configuration can change the profile after executable discovery. Binding and Resume
// must retain the home the prepared child will actually use.
if (engine === 'codex' && native) codexHome = nativeHookLocations(native.environment).CODEX_HOME
// A Codex agent pointed at a profile OTHER than this machine's default reads hooks.json from
// THAT folder, not the one `harness login` already installed into — without this, such an agent
// fires no hook at all (no SessionStart/UserPromptSubmit/Stop) and never streams a single event.
// Idempotent, so paying this on every create against an already-set-up profile is free.
if (!native && codexHome && !hooksDisabled && !await engineHooks.codex.installIn(hookPort, codexHome)) return {
ok: false, error: 'NATIVE_LAUNCH_HELD', detail: 'Waiting to confirm Codex’s hooks in the selected profile.', unavailable: 'native',
}
// An agent on a profile home reads that home's MCP config, not the default's: it gets the connections there too.
const profileHome = engine === 'claude' ? claudeHome : engine === 'codex' ? codexHome : null
if (profileHome && (engine === 'claude' || engine === 'codex')) {
try { syncProfileHome(new ConnectionsVault(), engine, profileHome) }
catch (error) { console.warn(`[agent] connections for ${profileHome} · ${error instanceof Error ? error.message : error}`) }
}
// OpenCode may have upgraded from 1.x to 2.x while this daemon was running. Its new TUI must
// not discover our old server plugin; the cached version probe changes with the executable.
// Native installation is eager. A plugin is how this engine tells the daemon its session.
if (!native && engine === 'opencode' && !hooksDisabled && !await installOpencodePlugin(hookPort)) {
const detail = 'OpenCode\'s plugin installer could not be loaded'
console.warn(`[agent] create opencode refused · ${detail}`)
return { ok: false, error: 'ENGINE_UNAVAILABLE', detail }
}
// Do not start a second interactive login shell merely to ask whether the engine is installed.
// The pane's own shell performs the same check before exec, and installs only when necessary.
// This removes ~1s of shell startup from the click-to-terminal critical path.
const installIfMissing = enginePathOverride(engine) ? undefined : engineInstallRecipe(engine)
// Clearing the vendor credentials this launch does NOT set is part of pointing an agent at a
// grid, not an extra. An engine chooses its provider from whatever it can see, and an inherited
// key wins on its own terms — OpenCode picked Anthropic over a grid it had been handed, and said
// only `invalid x-api-key`. Nothing is cleared when no grid is in play: an agent on its own login
// is supposed to use exactly these variables.
// Another person's project work (superTabs/start.ts): git and gh use the Harness GitHub App's token for the task,
// never this machine owner's own GitHub login (lib/swarmGitHub.ts). Kept on the row's skill, so a relaunch keeps it.
let swarmGitHub: ReturnType<SwarmLaunch['github']> = null
if (swarmLaunch && input.swarmRole && input.swarmGitHub) {
try { swarmGitHub = swarmLaunch.github(label) }
catch (error) { return { ok: false, error: 'SWARM_SKILL_FAILED', detail: String(error) } }
}
const clearEnv = [...(gridLaunch ? gridConflictingEnvToClear(gridLaunch) : []), ...harnessEnvToClear(dshEnv), ...swarmGitHub?.clearEnv ?? []]
// The named agent takes the same argv slot on every relaunch (`buildLaunchOverrides` appends it
// from the row's `agent`, after the grid's and the DSH's argv, exactly as here). The engine was
// checked for a contract at the wire (AGENT_UNSUPPORTED, opencode v2 included), so this cannot throw.
// A harness another agent started says so in the pull requests it opens (lib/agentAttribution.ts), last, as every
// relaunch appends it (`buildLaunchOverrides`), and read from the person's settings where this launch reads them.
// What Harness tells the agent (its instructions, and the pull request line for one another agent started), last.
// A launch an older CLI saved to finish later (a pending intent) names its role in the wire's values (lead, dev, review):
// read as this release keeps it, so a Reviewer keeps its swarm-review file. Nothing else is one.
const swarmSkill = input.swarmRole ? parseSwarmSkill({ role: input.swarmRole, key: label, fallback: input.swarmFallback, mode: input.swarmSkillMode,
github: swarmGitHub ? true : undefined }) : undefined
// Its own words: the Swarm's skill code (and its refusal's text) stays out of the core's bundle (src/leanEntry.spec.ts).
if (input.swarmRole && !swarmSkill) return { ok: false, error: 'SWARM_SKILL_FAILED', detail: 'This launch names no Swarm role this Harness knows.' }
let swarmInstructions: string | undefined
if (swarmLaunch && swarmSkill) {
try { swarmInstructions = swarmLaunch.prepare(cwd, swarmSkill).instructions }
catch (error) { return { ok: false, error: 'SWARM_SKILL_FAILED', detail: String(error) } }
}
const told = agentLaunchArgs(engine, startedBy, { cwd, profile: codexHome, environment: native?.environment, ...(swarmInstructions ? { swarmInstructions } : {}) })
// The person's machine MCP servers (lib/machineMcp.ts, #1872), beside the grid's and their own: read at each launch,
// as every relaunch reads them again (`buildLaunchOverrides`). A Buddy's too: it launches like its owner's own session
// (task #2832).
const machineMcp = machineMcpLaunchArgs(engine, cwd)
// The agent's private temporary folder: its TMPDIR, and, for a Swarm agent, its one added working directory, so its owner's
// own settings ask nothing for its mktemp files (lib/agentTmp.ts, task #4395). A Buddy has its own folder.
const tmp = swarmSkill?.role === 'buddy' ? { env: buddyTmpEnv(engine, cwd), args: [] } : agentTmpLaunch(engine, swarmSkill)
const extraArgs = joinedInstructions(engine, [...tmp.args, ...(gridLaunch?.args ?? []), ...dshArgs, ...(agent ? namedAgentArgs(engine, agent, native ? native.opencodeMajor : opencode ? await opencode.opencodeMajorVersion() : null) : []), ...machineMcp, ...(swarmLaunch && swarmSkill ? swarmLaunch.args(engine) : []), ...told])
// The first prompt is a launch option only — never part of `extraArgs`, which the registry row
// carries into a relaunch (engineLaunch.ts, `firstPrompt`).
const firstPrompt = prompt
const launchOptions = { ...(native ? { native } : {}), bypassPermission, ...(permissionMode ? { permissionMode } : {}), extraArgs: extraArgs.length ? extraArgs : undefined, installIfMissing, clearEnv, cwd, harnessNode: dsh ? true : undefined, ...(firstPrompt ? { firstPrompt } : {}), ...(launchModel ? { launchModel } : {}), terminalHint: { machineName: terminalHintMachineName() } }
// Windows refuses a batch-file engine whose arguments cmd.exe would read (lib/windows/launch.ts), before any pane.
let command: string[], argv: string[]
try {
command = buildEngineCommandArgv(engine, launchOptions)
argv = buildEngineLaunchArgv(engine, launchOptions)
} catch (error) { return windowsLaunchRefusal(error) }
// A tmux route is enough to stream its screen. Register it before looking for a process so both
// loopback and relayed Desktop clients can attach while the login shell/installer is still busy.
// `tmuxBackend` exists whenever the CONFIG lists tmux — it is never a probe of the binary, so a
// daemon that cannot resolve `tmux` at all (a login context whose PATH lacks Homebrew's bin, the
// usual shape after a reboot) is reported as `TMUX_UNAVAILABLE` too, distinctly from a tmux that
// answered and refused (`SPAWN_FAILED`) — see createAgentPane.ts. Registration itself is retried
// there: a stale registry entry from a previous tmux-server generation occasionally collides with
// a freshly-minted pane id, and that collision clears on its own on the very next pane.
await prepareInstructionWrites(cwd)
if (!current()) return stale()
prepareApiTools(cwd, engine)
// Mutually exclusive with a grid (backendSocket.ts refuses the two together): a chosen Codex
// profile becomes the new session's CODEX_HOME (its session store's variable, lib/engineHomes.ts
// `profileEnvironment`), the same `-e` mechanism a grid's own env rides.
if (!current()) return stale()
return { ok: true, dispatch: async () => {
if (!current()) return stale()
const result = await createAndRegisterPane({
current, ...(native ? { nativeToken: native.token } : {}),
tmuxBackend: createBackend,
registry,
engine,
cwd,
sessionLabel: label,
argv,
// Windows: the workspace to start in and the shell the pane becomes after the engine (lib/windows/engineStart.ts).
paneLaunch: windowsPaneLaunch(engine, { ...launchOptions, held: isWindowsHeldPane(argv) }),
// Windows: the variables the argv's `/usr/bin/env` prefix carries elsewhere, last (engineLaunchEnv).
// The private temporary folder first, so the launch's own variables win over it (lib/agentTmp.ts).
env: mergedLaunchEnv(mergedLaunchEnv(tmp.env, freshHarnessEnvironment(engine, mergedLaunchEnv(mergedLaunchEnv(gridLaunch?.env ?? (codexHome ? profileEnvironment(engine, codexHome) : undefined), dshEnv),
mergedLaunchEnv(mergedLaunchEnv(scmLaunchEnv(scmLaunchRecord), swarmGitHub?.env), native?.environment)), !!grid,
permissionMode ?? (bypassPermission ? DEFAULT_HARNESS_PERMISSION : 'ask'))), engineLaunchEnv(engine, native)),
grid: grid ? { baseUrl: grid.baseUrl, model: grid.model ?? null } : null,
gridLaunchRecord: grid && gridLaunch ? { override: grid, webSearch: gridLaunch.webSearch } : null,
scmLaunchRecord: scmLaunchRecord ?? null,
...(launchModel ? { launchModel } : {}),
codexHome,
claudeHome,
dsh,
dshRuntime: dsh ? label : null,
...(swarmSkill ? { swarmSkill } : {}),
agent,
bypassPermission,
permissionMode,
defaultName: name,
label: dshLabel,
startedBy: startedBy ?? null,
parentAgentId: parentAgentId ?? null,
})
if (!result.ok) return { ok: false, error: result.error, detail: result.detail }
const { spawned, pending } = result
// A terminal is ready the moment its pane is: there is no engine process to wait for, and the
// shell exiting is the person closing it — so `remain-on-exit` comes off now, and the pane going
// away is what removes the row (reconciler `onRemoved`), exactly as for an engine that quit.
if (isTerminalEngine(engine)) {
await createBackend.releaseHold(spawned.runtime)
const ready = registry.setLaunch(pending.agentId, { state: 'ready' }) ?? pending
announceSession(ready)
console.log(`[agent] create terminal open · agent ${pending.agentId}`)
return { ok: true, session: ready }
}
announceSession(pending)
if (pending.dsh) attachDsh(pending)
void watchNewPane(engine, pending, spawned, command, installIfMissing, undefined)
console.log(`[agent] create pane open · ${engine} · agent ${pending.agentId}`)
return { ok: true, session: pending }
} }
}
const createAgent: CreateAgent = async input => {
const label = buildHarnessSessionLabel(input.engine)
const prepared = await prepare(input, { id: label, label, current: () => true, hold: () => {} })
return prepared.ok ? prepared.dispatch() : prepared
}
return Object.assign(createAgent, { prepare })
}