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.

50.4 KB
Raw Blame
/**
 * The requests that start an agent's process: `agent_create`, `agent_fork`, `agent_resume` and
 * `agent_restart`, and `agent_create_status`, which asks what became of one. A client that names its
 * request with a `creationId` gets a durable receipt (lib/agentCreationReceipt.ts): a transport retry
 * carrying the same id never starts a second process, and a lost answer can be asked for again. Such a
 * request is answered outside the connection's line, so a status check can pass a slow launch.
 *
 * Moved verbatim out of the socket's request switch (docs/design/2026-10-03-harnessd.md), with the
 * receipts the socket used to hold.
 */
import { readdir, rmdir } from 'node:fs/promises'
import { homedir } from 'node:os'
import { dirname, isAbsolute } from 'node:path'
import type { BackendSocket } from '../../backendSocket.js'
import type { Asker, SwarmLaunch } from '../api.js'
import { installedDsh } from '../../dsh/installed.js'
import { DSH_ID_RE, dshSupportedEngines } from '../../dsh/manifest.js'
import { homeIsAbsolute } from '../../engines/kit/homeAdoption.js'
import { folderTrust } from '../../engines/launchPrep.js'
import type { NativeLaunchResult, NativeLaunchSource } from '../../engines/nativeLaunch.js'
import * as opencodeLaunch from '../../engines/launchControl.js'
import { ENGINES, isTerminalEngine, type AgentEngine } from '../../engines/types.js'
import { parseLaunchArgs } from '../../lib/launchArgs.js'
import { AgentCreationReceiptError, creationFingerprint, validCreationId, type AgentCreationOutcome, type AgentCreationReceipts, type AgentCreationStatus, type CreationAuthority } from '../../lib/agentCreationReceipt.js'
import type { AgentFrame } from '../../lib/agentFrame.js'
import { engineLabel } from '../../lib/agentNames.js'
import {
  AGENT_NAME_RE, FirstPromptUnsupportedError, MAX_FIRST_PROMPT_CHARS, NamedAgentUnsupportedError, permissionModeApproves,
  permissionModeFlags, supportsFirstPrompt, supportsNamedAgent, unsupportedLaunchModelFlag,
} from '../../lib/engineLaunch.js'
import { parseGridLaunchOverride, type GridLaunchOverride } from '../../lib/gridLaunchWire.js'
import { parseLaunchModel } from '../../lib/launchModel.js'
import { parseNewAgentModel, type NewAgentModel } from '../../lib/newAgentModel.js'
import { parseProjectFolder, prepareProjectFolder, projectsRoot, ProjectFolderError, RepositoryAccessError, type ProjectFolder } from '../../lib/projectFolder.js'
import type { ScmLaunchRecord } from '../../scm/types.js'
import { parentAgentIdOf, type RegisteredSession } from '../../lib/registry.js'
import { roleFromWire, wireRole } from '../../lib/savedSkill.js'
import { buildHarnessSessionLabel } from '../../lib/harnessSessionLabel.js'
import type { LaunchAuthority, LaunchPreparation } from '../../lib/launchPreparation.js'
import { createPendingLaunches } from './pendingLaunches.js'
import type { GuestCreate } from './guestCreate.js'

/** Creates an agent (core/agents/create.ts). The orchestrator creates through the same one. */
export type CreateAgent = NonNullable<BackendSocket['onCreateAgent']>
/** Opens a NEW agent that starts with another one's whole history (core/agents/fork.ts); `level` says
 *  what it got: the engine's own fork, or a handoff message. */
export type ForkAgent = NonNullable<BackendSocket['onForkAgent']>
/** Stops an agent's live engine process and relaunches it in the SAME tmux pane, keeping the SAME
 *  agentId and (best-effort) resuming the same engine session. `resumed` says whether the relaunch
 *  actually resumed the prior conversation or had to fall back to a fresh one (core/agents/restart.ts). `launchArgs` are
 *  the owner's new launch words (an empty list clears them): the relaunch is built with them and saves them on the record
 *  only once the engine is back, so a refused or failed restart saves nothing. */
export type RestartAgent = (agentId: string, launchArgs?: string[]) => Promise<
  { ok: true; session: RegisteredSession; resumed: boolean }
  | { ok: false; error: string; detail?: string; reason?: string }
>
/** Resumes stopped work directly, or attaches if it is already running. Never replaces a live process
 *  and never falls back to a fresh conversation (core/agents/lifecycle.ts). */
export type ResumeAgent = (agentId: string, permissionMode?: string, launchArgs?: string[]) => ReturnType<RestartAgent>

export interface LaunchRequestDeps {
  /** The receipts of launches asked for with a `creationId`. */
  receipts: Pick<AgentCreationReceipts, 'run' | 'status' | 'createdLaunchModel' | 'creator' | 'has' | 'runIntent' | 'pendingIntents' | 'pendingIntent' | 'cancelIntent'>
  /** Each launch, read when a request comes in: null on a machine that cannot launch agents. */
  createAgent: () => CreateAgent | null
  prepareCreate?: (input: Parameters<CreateAgent>[0], authority: LaunchAuthority, context?: { local: boolean }) => Promise<LaunchPreparation<Awaited<ReturnType<CreateAgent>>>>
  /** The engine itself made ready, installed first when it is missing (engines/prepareNativeLaunch.ts): what a new
   *  project waits for before its folder is made. */
  prepareEngine?: (engine: CreateInput['engine'], source: NativeLaunchSource, authority: Pick<CreationAuthority, 'id' | 'current'>) => Promise<NativeLaunchResult>
  forkAgent: () => ForkAgent | null
  resumeAgent: () => ResumeAgent | null
  restartAgent: () => RestartAgent | null
  byAgent: (agentId: string) => RegisteredSession | undefined
  /** A stopped agent's saved row (the stopped-agents store): a resume may bring it back with new launch words. */
  stoppedAgent: (agentId: string) => RegisteredSession | undefined
  /** An agent's frame, as the socket builds it for every reply. */
  toProject: (s: RegisteredSession) => Promise<AgentFrame>
  /** Where a new agent on a grid model sends its inference: the models service's to resolve, on this
   *  machine (core/api.ts `ModelsPort.launchTarget`). Null or a rejection holds a durable model request;
   *  resolving the semantic choice may renew service-owned credentials, but never dispatches a launch. */
  modelTarget: (selection: NewAgentModel) => Promise<GridLaunchOverride | null>
  /** A guest's New Harness, as the guest's own OS user (core/agents/guestCreate.ts); null where there is none. */
  guestCreate?: () => GuestCreate | null
  /** Which Swarm roles and skill modes a start may ask for (superTabs/inCore/launch.ts); absent while the Swarm is off. */
  swarmLaunch?: Pick<SwarmLaunch, 'role' | 'mode'>
  /** Whether a `claudeHome` is a Claude profile of this machine (lib/claudeProfiles.ts claudeHomeOffered); absent, any is. */
  claudeHomeOffered?: (claudeHome: string) => boolean
}

type Reply = (result: Record<string, unknown>) => void
type CreateInput = Parameters<CreateAgent>[0]

export function createLaunchRequests({ receipts, createAgent, prepareCreate, prepareEngine, forkAgent, resumeAgent, restartAgent, byAgent, stoppedAgent, toProject, modelTarget, guestCreate, swarmLaunch, claudeHomeOffered }: LaunchRequestDeps) {
  const validateInstalled = async (input: CreateInput, known?: ReturnType<typeof installedDsh>): Promise<{ error: string; detail: string } | null> => {
    if (input.dsh) {
      const installed = known ?? installedDsh(input.dsh)
      if (!installed) return { error: 'INVALID_DSH', detail: `${input.dsh} is not installed on this machine` }
      if (installed.manifest.kind === 'viewer') return { error: 'INVALID_DSH', detail: `${input.dsh} is a viewer package, not an agent` }
      if (!dshSupportedEngines(installed.manifest).includes(input.engine)) return { error: 'INVALID_DSH',
        detail: `${input.dsh} supports ${dshSupportedEngines(installed.manifest).join(', ')}; ${input.engine} is not compatible` }
    }
    if (input.agent && !supportsNamedAgent(input.engine, input.engine === 'opencode' ? await opencodeLaunch.opencodeMajorVersion() : null)) {
      return { error: 'AGENT_UNSUPPORTED', detail: new NamedAgentUnsupportedError(input.engine).message }
    }
    return null
  }

  const executeCreate = async (input: CreateInput, projectFolder: ProjectFolder | null, local: boolean, invoke: CreateAgent, validated = false): Promise<AgentCreationOutcome> => {
    if (!validated) {
      const refusal = await validateInstalled(input)
      if (refusal) return { state: 'failed', ...refusal }
    }
    const { dsh, resumeSessionId } = input
    let preparedFolder: string | undefined
    /** A new project's folder, which this made empty: removed again if nothing starts in it. */
    let made: string | undefined
    let scmLaunchRecord: ScmLaunchRecord | null = null
    /** The SSH alias a clone got in through, which the apps tell the person: it is the account later pushes go as. */
    let clonedVia: { alias: string } | undefined
    if (projectFolder) {
      try {
        preparedFolder = await prepareProjectFolder(projectFolder, { label: (dsh ? installedDsh(dsh)?.manifest.name : null) ?? engineLabel(input.engine),
          onPrepared: prepared => { scmLaunchRecord = prepared.scmLaunchRecord },
          // The person's own start may try every way this computer reaches GitHub. A Swarm agent's repository was cloned
          // by its start (superTabs/projectFolder.ts), which keeps to one address per transport and never an alias.
          ...(projectFolder.source === 'remote' ? { cloneFallback: !input.swarmRole,
            onCloned: (clone: { alias?: string }) => { if (clone.alias) clonedVia = { alias: clone.alias } } } : {}) })
        if (projectFolder.source === 'new') made = preparedFolder
      }
      catch (error) {
        return { state: 'failed', error: error instanceof ProjectFolderError ? error.code : 'PROJECT_PREPARATION_FAILED',
          detail: error instanceof ProjectFolderError ? error.message : 'Could not prepare the project folder.',
          // The folder a typed name found already there: the apps offer to start in it, and `harness new` names it.
          ...(error instanceof ProjectFolderError && error.folder ? { existingFolder: error.folder } : {}),
          // GitHub refused every way in: the apps say "No access" in their own words rather than git's.
          ...(error instanceof RepositoryAccessError ? { access: 'denied' as const } : {}) }
      }
      // Only a folder this daemon just made EMPTY is one the engine need not ask about. A clone or
      // the person's own repo is theirs to answer for (engines/kit/folderTrust.ts); a worktree gets only
      // the answer its source repo already has. `branch` IS the source folder: nothing to record.
      //
      // One consented exception: a Swarm agent, in any mode (task #4215), in the checkout a remote project resolved
      // to (cloned now, or one already there that holds that very repository). The person chose this repository
      // for the Swarm, and machine trust favors that choice over a prompt. 2026-10-26: on WIN-DELL
      // a Lead in a reused `harnesses\openharness` sat at Claude Code's trust question; on the Mac Studio a Lead in
      // a fresh clone did, and the next Lead, in a worktree of it, asked again because the source had never been
      // answered. Its Yes then landed under the source's key (Claude Code records a worktree's answer under its
      // main repository), which made the source look trusted before the worktree started.
      // Claude Code only: Codex's trust also sets its defaults for the person's own later sessions in that folder.
      //
      // And a worktree of a repository the person picked in this machine's OWN window for a Swarm agent, in any mode (#4215):
      // 2026-10-30, a new Swarm made with Cmd+S on a local openharness checkout started its PM in a worktree of it, and
      // the PM sat at Claude Code's trust question, which no Swarm view shows; it read Idle and every message to it was
      // withheld. Only from a local frame: a relayed request could name any repository on this machine.
      const swarmAgent = input.engine === 'claude' && !!input.swarmRole
      const swarmCheckout = swarmAgent && (projectFolder.source === 'remote' || (projectFolder.source === 'worktree' && local))
      try {
        // A Codex agent on its own profile reads its trust from that profile's config.toml, not ~/.codex.
        const engineTrust = folderTrust(input.engine, input.codexHome ?? input.claudeHome ?? null)
        if (engineTrust && (projectFolder.source === 'new' || swarmCheckout
          || (projectFolder.source === 'worktree' && engineTrust.trusts(projectFolder.gitSource)))) {
          engineTrust.record(preparedFolder)
        }
      } catch (error) { console.warn(`[agent] pre-trust ${preparedFolder} · ${error instanceof Error ? error.message : error}`) }
    } else if (!dsh && !resumeSessionId && local && dirname(input.cwd) === projectsRoot()) {
      // On the LOCAL machine the desktop makes a new workspace ITSELF and sends the path as a plain
      // cwd, so `projectFolder` above never sees it. Such a folder is empty and is trusted the way a
      // `new` project is — but only on evidence, and only where those workspaces live:
      //
      //   · directly inside the projects root, which is the one folder the app and this daemon
      //     create workspaces in. Claude Code's trust INHERITS downward, so recording it for a
      //     folder the person merely browsed to — an empty `~/code`, or a home with nothing in it —
      //     would silently cover every repo cloned under it later: OH-14 again by another door.
      //   · empty as read from disk, never on the client's word. A clone, a worktree or the
      //     person's own repo has content, so it stays the engine's question (engines/kit/folderTrust.ts).
      //   · from a LOCAL frame. agent_create is not backend-only, so a relayed peer would otherwise
      //     name an empty path on this host and have it trusted.
      //
      // DSH trust is decided in cli.ts, where the template count is known; leave that to it.
      try {
        const empty = await readdir(input.cwd).then((names) => names.length === 0, () => false)
        if (empty) folderTrust(input.engine, input.codexHome ?? input.claudeHome ?? null)?.record(input.cwd)
      } catch (error) { console.warn(`[agent] pre-trust ${input.cwd} · ${error instanceof Error ? error.message : error}`) }
    }
    const result = await invoke(preparedFolder ? { ...input, cwd: preparedFolder, scmLaunchRecord } : input)
    if (result.ok) return { state: 'created', agentId: result.session.agentId, ...(clonedVia ? { clonedVia } : {}) }
    // tmux may have executed before a timeout; registration cleanup is best-effort.
    // Neither can prove that no process started, so never encourage another launch.
    if (result.error === 'SPAWN_FAILED' || result.error === 'REGISTRATION_FAILED') return { state: 'unconfirmed' }
    // A new project's folder that nothing started in goes again while it is still empty: left, it made the same
    // `harness new codex scratch1` refuse its own name ("already exists", a fresh Ubuntu VM, 2026-10-12). rmdir
    // removes only an empty folder, so anything put there meanwhile stays, and the folder is then reported.
    if (made && await rmdir(made).then(() => true, () => false)) preparedFolder = undefined
    return { state: 'failed', error: result.error, ...(preparedFolder ? { preparedFolder } : {}), ...(result.detail ? { detail: result.detail.slice(0, 2000) } : {}) }
  }

  const modelHold = { service: 'models', detail: 'Waiting for the selected model. This request is saved and will continue when it is available.' }
  const launchHold = { service: 'launch', detail: 'Waiting for launch preparation. This request is saved and will continue when its dependencies are available.' }
  const pending = createPendingLaunches({ receipts, prepare: async (saved, authority) => {
    if (saved.kind === 'native-create-v1') {
      if (!prepareCreate || typeof saved.local !== 'boolean' || !saved.input || typeof saved.input !== 'object'
        || typeof saved.label !== 'string' || !/^harness-[a-z0-9-]+$/.test(saved.label)) return null
      const input = structuredClone(saved.input) as CreateInput
      const projectFolder = (saved.projectFolder ?? null) as ProjectFolder | null
      if (!ENGINES.includes(input.engine) || typeof input.cwd !== 'string' || input.resumeSessionId
        || (projectFolder !== null && typeof projectFolder.source !== 'string')) return null
      const { local, label } = saved
      if (saved.selection) {
        authority.hold(modelHold)
        const target = await modelTarget(saved.selection as NewAgentModel)
        if (!authority.current()) return null
        if (!target) { authority.hold(modelHold); return null }
        input.grid = target
        authority.hold(launchHold)
      }
      // An engine Harness is installing for this launch holds it under `install`, which `harness new` waits longer
      // for than any other hold (lib/newCommand.ts): installs take a minute on a fresh computer.
      const held = (ready: { installing?: boolean; unavailable?: string; detail?: string }) =>
        authority.hold({ service: ready.installing ? 'install' : ready.unavailable!, detail: ready.detail ?? 'Waiting for launch preparation.' })
      const refused = (ready: { error: string; detail?: string }) => async (): Promise<AgentCreationOutcome> =>
        ({ state: 'failed', error: ready.error, ...(ready.detail ? { detail: ready.detail.slice(0, 2000) } : {}) })
      if (projectFolder) {
        // A new project waits for its engine before its folder is made, so a launch still waiting for an install leaves
        // nothing behind when it is cancelled or the install fails. It used to be refused at once, folder made, saying
        // "the saved launch continues after installation" of a launch that was over (a fresh Ubuntu VM, 2026-10-12).
        // The folder, the engine's final preparation and the launch are then one claimed effect, as they always were
        // for a project: a refusal there is its outcome, never a hold.
        const engine = prepareEngine ? await prepareEngine(input.engine, input, authority) : null
        if (!authority.current()) return null
        if (engine && !engine.ok) {
          if (engine.refusal) return refused({ error: engine.refusal, detail: engine.detail })
          held(engine); return null
        }
        const invoke: CreateAgent = async (prepared) => {
          const ready = await prepareCreate(prepared, { ...authority, label }, { local })
          return ready.ok ? ready.dispatch() : { ok: false, error: ready.error, ...(ready.detail ? { detail: ready.detail } : {}) }
        }
        return () => executeCreate(input, projectFolder, local, invoke)
      }
      const ready = await prepareCreate(input, { ...authority, label }, { local })
      if (!authority.current()) return null
      if (!ready.ok) {
        if (ready.unavailable) { held(ready); return null }
        return refused(ready)
      }
      return async () => {
        if (!authority.current()) return { state: 'unconfirmed' }
        // All preparation, including local workspace trust, precedes the claim.
        // A trust write here would invalidate Codex's final config proof.
        const result = await ready.dispatch()
        if (result.ok) return { state: 'created', agentId: result.session.agentId }
        // Dispatch's outcome is uncertain once its exclusive claim is durable.
        // In particular, a stale guard must never reopen that claim for replay.
        return { state: 'unconfirmed' }
      }
    }
    // A future intent kind cannot be interpreted as this one. Keep unknown or
    // damaged requests held instead of guessing at their launch choices.
    if (saved.kind !== 'model-create-v1' || typeof saved.local !== 'boolean'
      || !saved.input || typeof saved.input !== 'object' || !saved.selection || typeof saved.selection !== 'object') return null
    const input = structuredClone(saved.input) as CreateInput
    const selection = saved.selection as NewAgentModel
    if (!ENGINES.includes(input.engine) || typeof input.cwd !== 'string' || input.resumeSessionId
      || input.grid !== null || typeof selection.model !== 'string' || typeof selection.grid !== 'string') return null
    const invoke = createAgent()
    if (!invoke) return null
    const target = await modelTarget(selection)
    if (!target) return null
    input.grid = target
    return () => executeCreate(input, (saved.projectFolder ?? null) as ProjectFolder | null, saved.local as boolean, invoke)
  } })

  /** Recover by stable runtime identity; a deleted agent must never become a fresh launch. */
  const creationStatusPayload = async (status: AgentCreationStatus): Promise<Record<string, unknown>> => {
    if (status.state === 'created') {
      const session = byAgent(status.agentId)
      return session
        ? { state: 'created', agent: await toProject(session), ...(status.level ? { level: status.level } : {}), ...(status.resumed !== undefined ? { resumed: status.resumed } : {}),
          ...(status.clonedVia ? { clonedVia: status.clonedVia } : {}) }
        : { state: 'unavailable', createdAgentId: status.agentId }
    }
    // A recorded refusal is a completed outcome. Keep it separate from transport/dispatch errors
    // so clients can distinguish "safe to correct the choices" from "outcome still unknown".
    if (status.state === 'failed') {
      return { state: 'failed', ...(status.preparedFolder ? { preparedFolder: status.preparedFolder } : {}), failure: { code: status.error,
        ...(status.reason ? { reason: status.reason } : {}), ...(status.detail ? { detail: status.detail } : {}),
        ...(status.existingFolder ? { existingFolder: status.existingFolder } : {}), ...(status.access ? { access: status.access } : {}) } }
    }
    return status
  }

  /** A guest sees only its own creations. For anyone else's id it hears what an unknown id gets, so the
   *  answer does not tell whether the id exists. The owner administers the machine and sees them all. */
  const hiddenFrom = (asker: Pick<Asker, 'local' | 'guest'>, creationId: string): boolean => {
    if (asker.guest === undefined) return false
    // Damaged evidence for this id is hidden the same way; the guest's own retry still meets it in `run`.
    try { return receipts.creator(creationId) !== asker.guest }
    catch (error) { if (error instanceof AgentCreationReceiptError) return true; throw error }
  }

  /** Answers `agent_create_status`: what became of the launch a `creationId` names. */
  const createStatus = async (payload: Record<string, unknown>, asker: Pick<Asker, 'local' | 'guest'>, reply: Reply): Promise<void> => {
    const creationId = payload.creationId
    if (!validCreationId(creationId)) { reply({ error: 'INVALID_CREATION_ID' }); return }
    try {
      if (hiddenFrom(asker, creationId)) { reply({ creationId, state: 'missing' }); return }
      const status = receipts.status(creationId)
      const launchModel = status.state === 'created' ? receipts.createdLaunchModel(creationId) : null
      reply({ creationId, ...await creationStatusPayload(status), ...(launchModel ? { launchModel } : {}) })
    } catch (error) {
      // The reason travels with the code, so the host can tell the Swarm why the start waits (task #3861).
      reply({ error: error instanceof AgentCreationReceiptError ? error.code : 'INTERNAL', ...error instanceof AgentCreationReceiptError && error.detail ? { detail: error.detail } : {} })
    }
  }

  /** A guest's `agent_create`: its own launch, never the owner's (core/agents/guestCreate.ts). A `creationId` keeps a
   *  receipt as the owner's launches do, so a status check or a retry finds the same harness. */
  const createForGuest = async (payload: Record<string, unknown>, guest: string, reply: Reply): Promise<void> => {
    const launch = guestCreate?.()
    if (!launch) { reply({ error: 'GUEST_NOT_ALLOWED' }); return }
    const creationId = payload.creationId
    if (creationId !== undefined && !validCreationId(creationId)) { reply({ error: 'INVALID_CREATION_ID' }); return }
    if (creationId === undefined) {
      const result = await launch(payload, guest)
      reply(result.ok ? { agent: await toProject(result.session) } : { error: result.error, ...(result.detail ? { detail: result.detail } : {}) })
      return
    }
    try {
      const fingerprint = creationFingerprint({ guest, engine: payload.engine, name: payload.name })
      void receipts.run(creationId, fingerprint, async () => {
        const result = await launch(payload, guest)
        return result.ok ? { state: 'created', agentId: result.session.agentId }
          : { state: 'failed', error: result.error, ...(result.detail ? { detail: result.detail } : {}) }
      }, guest).then(async (status) => {
        reply({ creationId, ...await creationStatusPayload(status) })
      }).catch(() => reply({ error: 'INTERNAL' }))
    } catch (error) {
      reply({ error: error instanceof AgentCreationReceiptError ? error.code : 'INTERNAL' })
    }
  }

  /** Answers `agent_create`. `asker.local` says the frame came from this machine; `asker.guest`, that a guest
   *  of a machine shared with them asks (core/guestPolicy.ts). */
  const create = async (payload: Record<string, unknown>, asker: Pick<Asker, 'local' | 'guest'>, reply: Reply): Promise<void> => {
    if (asker.guest !== undefined) { await createForGuest(payload, asker.guest, reply); return }
    const engine = payload.engine as AgentEngine | undefined
    const cwd = payload.cwd
    if (typeof engine !== 'string' || !ENGINES.includes(engine)) { reply({ error: 'INVALID_ENGINE' }); return }
    let projectFolder
    try { projectFolder = parseProjectFolder(payload) }
    catch (error) {
      reply(error instanceof ProjectFolderError
        ? { error: error.code, detail: error.message }
        : { error: 'INVALID_PROJECT_SOURCE' }); return
    }
    // A terminal opens where a terminal app would — the home directory — when the client names
    // no folder; every other engine works IN a folder and must be told which.
    const terminal = isTerminalEngine(engine)
    if (terminal && projectFolder) { reply({ error: 'INVALID_PROJECT_SOURCE', detail: 'a terminal opens in a folder, it does not prepare one' }); return }
    if (!projectFolder && !(terminal && cwd === undefined) && (typeof cwd !== 'string' || !isAbsolute(cwd))) { reply({ error: 'INVALID_CWD' }); return }
    const onCreateAgent = createAgent()
    if (!onCreateAgent) { reply({ error: 'UNSUPPORTED_ON_REMOTE' }); return }
    const creationId = payload.creationId
    if (creationId !== undefined && !validCreationId(creationId)) {
      reply({ error: 'INVALID_CREATION_ID' }); return
    }
    if (projectFolder && (!validCreationId(creationId) || cwd !== undefined)) {
      reply({ error: 'INVALID_PROJECT_SOURCE' }); return
    }
    // Absent is the ordinary case and stays indistinguishable from a client that predates grids;
    // present-but-malformed is refused here rather than half-applied at launch, because an agent
    // that quietly ran on the engine's own login would look like it worked.
    const model = parseNewAgentModel(engine, payload)
    if (model.state === 'invalid') { reply({ error: 'INVALID_GRID', detail: model.detail }); return }
    const grid = parseGridLaunchOverride(payload.grid)
    if (grid.state === 'invalid') { reply({ error: 'INVALID_GRID', detail: grid.reason }); return }
    if (terminal && grid.state === 'ok') { reply({ error: 'INVALID_GRID', detail: 'a terminal has no engine to point at a grid' }); return }
    // A model and effort for this session alone, as flags (lib/launchModel.ts). Refused, never ignored: a daemon that
    // dropped them would start the agent on the engine's own model and look like it worked, so a caller that gets
    // LAUNCH_MODEL_UNSUPPORTED switches the model after the start instead. A grid picks its own model.
    const launchModel = parseLaunchModel(engine, payload)
    if (launchModel.state === 'invalid') { reply({ error: 'INVALID_LAUNCH_MODEL', detail: launchModel.detail }); return }
    if (launchModel.state === 'unsupported') { reply({ error: 'LAUNCH_MODEL_UNSUPPORTED', detail: launchModel.detail }); return }
    if (launchModel.state === 'ok' && (grid.state === 'ok' || model.state === 'ok')) {
      reply({ error: 'INVALID_LAUNCH_MODEL', detail: 'a grid chooses its own model' }); return
    }
    // A Claude Code too old for the flags would print its help in the new pane. Refused here, before any receipt, so the
    // caller creates the agent without them and switches the model afterwards, as it did before the flags.
    if (launchModel.state === 'ok') {
      const missing = await unsupportedLaunchModelFlag(engine, launchModel.launchModel)
      if (missing) { reply({ error: 'LAUNCH_MODEL_UNSUPPORTED', detail: `The ${engine} on this machine does not support ${missing}; update ${engine} to launch it with a model.` }); return }
    }
    // Checked here whatever the client checked (`Agent._safeCodexHome` in the desktop app), because a client's own check is
    // not a guarantee about what arrives on the wire. Absolute as this platform spells it: on Windows a drive-letter path,
    // which a leading-'/' check refused, so a linked profile's agent ran on the default account (#4183).
    const rawCodexHome = typeof payload.codexHome === 'string' ? payload.codexHome : null
    const codexHome = rawCodexHome && homeIsAbsolute(rawCodexHome) && rawCodexHome.length <= 4096
      && !/[\x00-\x1f\x7f]/.test(rawCodexHome)
      ? rawCodexHome
      : null
    if (codexHome && (engine !== 'codex' || grid.state === 'ok')) {
      reply({ error: 'INVALID_CODEX_HOME', detail: 'codexHome is only valid for codex, without a grid' })
      return
    }
    // Claude profiles (CLAUDE_CONFIG_DIR) follow the same rule: Claude only, without a grid.
    const rawClaudeHome = typeof payload.claudeHome === 'string' ? payload.claudeHome : null
    const claudeHome = rawClaudeHome && homeIsAbsolute(rawClaudeHome) && rawClaudeHome.length <= 4096
      && !/[\x00-\x1f\x7f]/.test(rawClaudeHome)
      ? rawClaudeHome
      : null
    if (claudeHome && (engine !== 'claude' || grid.state === 'ok')) {
      reply({ error: 'INVALID_CLAUDE_HOME', detail: 'claudeHome is only valid for claude, without a grid' })
      return
    }
    if (claudeHome && claudeHomeOffered && !claudeHomeOffered(claudeHome)) {
      reply({ error: 'INVALID_CLAUDE_HOME', detail: 'claudeHome is not a Claude profile of this machine' })
      return
    }
    // A DSH is refused, never approximated: an agent created as its plain base engine would look
    // like it worked and have none of the skills the user picked the tile for.
    let dsh: string | null = null
    let installed: ReturnType<typeof installedDsh>
    if (payload.dsh !== undefined && payload.dsh !== null) {
      if (typeof payload.dsh !== 'string' || !DSH_ID_RE.test(payload.dsh)) {
        reply({ error: 'INVALID_DSH', detail: 'dsh must be an owner/name id' }); return
      }
      installed = installedDsh(payload.dsh)
      // Formerly-named packages used their canonical ID in both launch input
      // and v1 fingerprints. Resolve aliases without refusing a known receipt
      // merely because the package is no longer installed.
      dsh = installed?.id ?? payload.dsh
    }
    // A first prompt is refused BEFORE any pane exists: an engine with no way to take one would
    // otherwise open on an empty input and look like the person's request had been heard. The
    // length bound is a first message's, not a document's. The text itself is never logged.
    let prompt: string | null = null
    if (payload.prompt !== undefined && payload.prompt !== null) {
      if (typeof payload.prompt !== 'string') { reply({ error: 'INVALID_PROMPT', detail: 'prompt must be a string' }); return }
      const trimmed = payload.prompt.trim()
      if (trimmed.length > MAX_FIRST_PROMPT_CHARS) {
        reply({ error: 'PROMPT_TOO_LONG', detail: `prompt is longer than ${MAX_FIRST_PROMPT_CHARS} characters` }); return
      }
      if (trimmed && !supportsFirstPrompt(engine)) {
        reply({ error: 'PROMPT_UNSUPPORTED', detail: new FirstPromptUnsupportedError(engine).message }); return
      }
      prompt = trimmed || null
    }
    const swarmRole = payload.swarmRole
    if (!swarmLaunch && ((swarmRole !== undefined && swarmRole !== null) || payload.swarmSkillMode !== undefined || payload.swarmGitHub !== undefined)) {
      reply({ error: 'INVALID_SWARM_ROLE', detail: 'The Swarm is off on this computer (HARNESS_SWARM).' }); return
    }
    // Project instructions, phase 4 (decision 1): a coordinator, an agent or a Buddy. An older Harness sends lead, dev or review
    // (a Reviewer, which keeps its swarm-review file); the next release may send the kinds, so this one takes both.
    const swarm = swarmRole === undefined || swarmRole === null ? null : roleFromWire(swarmRole)
    if (swarmRole !== undefined && swarmRole !== null &&
      (!swarm || !swarmLaunch?.role(swarm.role) || (engine !== 'claude' && engine !== 'codex'))) {
      reply({ error: 'INVALID_SWARM_ROLE', detail: 'A Swarm role is coordinator, agent or buddy (or lead, dev or review from an older Harness), for Claude Code or Codex.' }); return
    }
    // The skills of the project the agent joins (superTabs/start.ts); a start from before modes sends none.
    const swarmSkillMode = payload.swarmSkillMode
    if (swarmSkillMode !== undefined && !swarmLaunch?.mode(swarmSkillMode)) {
      reply({ error: 'INVALID_SWARM_ROLE', detail: 'A Swarm skill mode is default or orchestration.' }); return
    }
    // Another person's project work: git and gh use the Harness GitHub App's token for the task (lib/swarmGitHub.ts).
    // Only `true`, and only with a role; a start from before the app sends none and launches as it did.
    const swarmGitHub = payload.swarmGitHub
    if (swarmGitHub !== undefined && (swarmGitHub !== true || !swarm)) {
      reply({ error: 'INVALID_SWARM_ROLE', detail: 'swarmGitHub is true, with a Swarm role.' }); return
    }
    // Its worktree fetches nothing with this machine's own git login: its host fetched with the app's token just before
    // (superTabs/projectFolder.ts), or, started by a Lead on its own machine, it starts from what the checkout has.
    if (swarmGitHub === true && projectFolder?.source === 'worktree') projectFolder = { ...projectFolder, offline: true }
    // Blank is "number it", the same as absent — a client that sends an empty field is not
    // asking for an agent with no name.
    const name = typeof payload.name === 'string' && payload.name.trim() ? payload.name.trim() : null
    // The engine's named agent is refused BEFORE any pane exists, like the prompt: an engine with
    // no way to open as one would otherwise come up as a general session under that agent's
    // name. The shape is an identifier the engine looks a file up by — never a path.
    let agent: string | null = null
    if (payload.agent !== undefined && payload.agent !== null) {
      if (typeof payload.agent !== 'string' || !AGENT_NAME_RE.test(payload.agent)) {
        reply({ error: 'INVALID_AGENT', detail: 'agent must be 1-64 letters, digits, `-` or `_`' }); return
      }
      agent = payload.agent
    }
    // A permission mode picked in New Harness. A client that predates the choice sends only
    // `bypassPermission`; one that sends a mode this engine does not have is refused rather than
    // quietly launched in some other mode.
    let permissionMode: string | null = null
    if (payload.permissionMode !== undefined && payload.permissionMode !== null) {
      if (typeof payload.permissionMode !== 'string' || !permissionModeFlags(engine, payload.permissionMode)) {
        reply({ error: 'INVALID_PERMISSION_MODE', detail: `${engine} has no permission mode ${JSON.stringify(payload.permissionMode)}` }); return
      }
      permissionMode = payload.permissionMode
    }
    // Opening a conversation Harness did not start: the engine resumes it, as it was. Nothing a new
    // conversation is created with applies to it.
    let resumeSessionId: string | null = null
    if (payload.resumeSessionId !== undefined && payload.resumeSessionId !== null) {
      // Engines' ids: uuids, `ses_…` (OpenCode, Kilo), `20260927_101500_ab12cd` (Hermes), slugs
      // (Devin), Pi's custom ids with dots. One word, never a path.
      if (typeof payload.resumeSessionId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{1,127}$/.test(payload.resumeSessionId)) {
        reply({ error: 'INVALID_SESSION', detail: 'resumeSessionId must be a session id' }); return
      }
      if (terminal || projectFolder || grid.state === 'ok' || model.state === 'ok' || launchModel.state === 'ok' || dsh || prompt || agent || swarmRole) {
        reply({ error: 'INVALID_SESSION', detail: 'a resumed conversation takes no new folder, grid, harness, prompt or agent' }); return
      }
      resumeSessionId = payload.resumeSessionId
    }
    let takeOver: 'idle' | 'now' | 'wait' | null = null
    if (payload.takeOver !== undefined && payload.takeOver !== null) {
      if (!resumeSessionId || (payload.takeOver !== 'idle' && payload.takeOver !== 'now' && payload.takeOver !== 'wait')) {
        reply({ error: 'INVALID_SESSION', detail: 'takeOver is idle, now or wait, with a resumeSessionId' }); return
      }
      takeOver = payload.takeOver
    }
    // Another agent started it (`harness new` from its pane, agentClient/commands.ts `agentOrigin`): its pull requests
    // say so (lib/agentAttribution.ts). Refused, not ignored, when it is anything else: absent is the person.
    if (payload.startedBy !== undefined && payload.startedBy !== null && payload.startedBy !== 'agent') {
      reply({ error: 'INVALID_STARTED_BY', detail: 'startedBy is agent, or absent for the person' }); return
    }
    // Which harness here that agent is (`harness new` or `harness_start` from its pane): the windows open the new one
    // beside it and say who started it. Only with `startedBy: 'agent'`, and only an agent id; one this machine does not
    // know is left out rather than refused, so a harness that just closed does not stop its child from starting.
    let parentAgentId: string | null = null
    if (payload.parentAgentId !== undefined && payload.parentAgentId !== null) {
      parentAgentId = payload.startedBy === 'agent' ? parentAgentIdOf(payload.parentAgentId) : null
      if (!parentAgentId) { reply({ error: 'INVALID_STARTED_BY', detail: 'parentAgentId is the agent id of the harness that started it, with startedBy agent' }); return }
      if (!byAgent(parentAgentId)) parentAgentId = null
    }
    const input: Parameters<CreateAgent>[0] = {
      engine,
      cwd: typeof cwd === 'string' ? cwd : terminal ? homedir() : '',
      // On unless a client says otherwise: a harness works without stopping to ask for each command.
      bypassPermission: permissionMode ? permissionModeApproves(permissionMode) : payload.bypassPermission !== false,
      permissionMode,
      grid: grid.state === 'ok' ? grid.override : null,
      codexHome,
      dsh,
      prompt,
      ...(swarm ? { swarmRole: swarm.role, ...(swarm.fallback ? { swarmFallback: swarm.fallback } : {}), ...(swarmSkillMode ? { swarmSkillMode } : {}),
        ...(swarmGitHub ? { swarmGitHub } : {}) } : {}),
      name,
      agent,
      resumeSessionId,
      takeOver,
      // Only when set: a person's create keeps the fingerprint its receipt was recorded with before the field.
      ...(claudeHome ? { claudeHome } : {}),
      ...(payload.startedBy === 'agent' ? { startedBy: 'agent' as const } : {}),
      ...(launchModel.state === 'ok' ? { launchModel: launchModel.launchModel } : {}),
      ...(parentAgentId ? { parentAgentId } : {}),
    }
    // The fingerprint names the role in the wire's values, as every receipt from before role kinds does: a start asked again
    // after this machine's update still finds the receipt its first ask got, whichever value set the asker sends.
    const { swarmFallback: _fallback, ...stable } = input
    const recorded = swarm ? { ...stable, swarmRole: wireRole(swarm) } : input
    const fingerprintInput = model.state === 'ok' ? { ...recorded, modelSelection: model.selection } : recorded
    if (creationId !== undefined) {
      // Reserve before spawning. A transport retry carries the SAME creationId; a deliberate
      // New agent action carries a new one. Detach so a status check can pass a slow create
      // on this connection, just as engines_probe is detached above.
      const create = onCreateAgent
      try {
        const fingerprint = creationFingerprint(projectFolder ? { ...fingerprintInput, projectFolder } : fingerprintInput)
        // A new project too, which waits for its engine as any other create does (above).
        const durableNative = !!prepareCreate && !resumeSessionId
        // A new project is refused at once for a harness or named agent it cannot have, as it always was, rather than
        // after its engine is installed and its folder made.
        if ((!durableNative || projectFolder) && model.state !== 'ok' && !receipts.has(creationId, fingerprint)) {
          const refusal = await validateInstalled(input, installed)
          if (refusal) { reply(refusal); return }
        }
        const operation = durableNative
          ? pending.start(creationId, fingerprint, { kind: 'native-create-v1', input, ...(projectFolder ? { projectFolder } : {}),
            selection: model.state === 'ok' ? model.selection : null, label: buildHarnessSessionLabel(engine), local: asker.local }, model.state === 'ok' ? modelHold : launchHold)
          : model.state === 'ok'
          ? pending.start(creationId, fingerprint, { kind: 'model-create-v1', input, selection: model.selection, projectFolder, local: asker.local }, modelHold)
          : receipts.run(creationId, fingerprint, () => executeCreate(input, projectFolder, asker.local, create, true))
        void operation.then(async (status) => {
          reply({ creationId, ...await creationStatusPayload(status) })
        }).catch(() => reply({ error: 'INTERNAL' }))
      } catch (error) {
        reply({ error: error instanceof AgentCreationReceiptError ? error.code : 'INTERNAL' })
      }
      return
    }
    // Clients predating receipts retain their existing response shape.
    const refusal = await validateInstalled(input, installed)
    if (refusal) { reply(refusal); return }
    if (model.state === 'ok') {
      const target = await modelTarget(model.selection).catch(() => null)
      if (!target) { reply({ error: 'GRID_UNAVAILABLE', detail: 'The selected model is unavailable. Choose another model or refresh the list.' }); return }
      input.grid = target
    }
    const result = await onCreateAgent(input)
    // `detail` carries the underlying cause (tmux's own message) so the person who clicked
    // Create can read it, rather than having to open a log on the machine that failed.
    if (!result.ok) {
      reply(result.detail ? { error: result.error, detail: result.detail } : { error: result.error })
      return
    }
    reply({ agent: await toProject(result.session) })
  }

  // Resume attaches or restores a saved conversation; restart replaces a live process in its
  // existing pane. Both keep the agentId and use the same durable operation receipt protocol.
  const relaunch = async (type: string, payload: Record<string, unknown>, reply: Reply, asker: { ownerApp: boolean }): Promise<void> => {
    const target = payload.agentId as string | undefined
    if (!target) { reply({ error: 'MISSING_AGENT_ID' }); return }
    const operation = type === 'agent_resume' ? 'resume' : 'restart'
    const restart = operation === 'resume' ? resumeAgent() : restartAgent()
    if (!restart) { reply({ error: 'UNSUPPORTED_ON_REMOTE' }); return }
    const permissionMode = payload.permissionMode
    if (permissionMode !== undefined && (operation !== 'resume' || typeof permissionMode !== 'string'
      || !['ask', 'auto', 'plan', 'full'].includes(permissionMode))) {
      reply({ error: 'INVALID_PERMISSION_MODE' }); return
    }
    // Team-written work keeps its project settings off: no resume trades that mode for another (audit H2).
    if (permissionMode !== undefined && byAgent(target)?.permissionMode === 'teamWritten') {
      reply({ error: 'INVALID_PERMISSION_MODE' }); return
    }
    // Extra launch flags ride a restart or a resume of an agent the owner may change, and are checked with the engine's
    // own refused list before anything is relaunched. The engine runs them as the owner, so only the owner's own app
    // may send them (a device, an agent's own CLI and a guest may not), as only it may change a permission.
    let launchArgs: string[] | undefined
    if (payload.launchArgs !== undefined) {
      if (!asker.ownerApp) { reply({ error: 'INVALID_LAUNCH_ARGS', detail: 'Launch flags can only be changed from your own Harness app.' }); return }
      // A harness a bad flag left stopped is in the stopped store, not the registry: the way back is to resume it.
      const known = byAgent(target) ?? stoppedAgent(target)
      if (typeof payload.launchArgs !== 'string' || known?.permissionMode === 'teamWritten') {
        reply({ error: 'INVALID_LAUNCH_ARGS' }); return
      }
      if (!known) { reply({ error: 'AGENT_NOT_FOUND' }); return }
      const parsed = parseLaunchArgs(known.engine, payload.launchArgs)
      if (!parsed.ok) { reply({ error: 'INVALID_LAUNCH_ARGS', detail: parsed.detail }); return }
      launchArgs = parsed.args
    }
    // The words travel with the relaunch and the launch saves them once the engine is back (core/agents/restart.ts,
    // lib/resumeAgentService.ts): a restart refused, a process gone or an engine that did not start leaves the record as
    // it was, and nothing here has to be undone.
    const invoke = () => operation === 'resume'
      ? (launchArgs ? resumeAgent()!(target, permissionMode as string | undefined, launchArgs)
        : permissionMode === undefined ? restart(target) : resumeAgent()!(target, permissionMode as string))
      : (launchArgs ? restartAgent()!(target, launchArgs) : restart(target))
    // What the record holds now: the words a successful launch saved, `[]` once cleared. Never on a failure.
    const echo = () => launchArgs ? { launchArgs: byAgent(target)?.launchArgs ?? [] } : {}
    const creationId = payload.creationId
    if (creationId !== undefined) {
      if (!validCreationId(creationId)) { reply({ error: 'INVALID_CREATION_ID' }); return }
      try {
        void receipts.run(creationId, creationFingerprint({ operation, agentId: target,
          ...(permissionMode === undefined ? {} : { permissionMode }), ...(launchArgs ? { launchArgs } : {}) }), async () => {
          const result = await invoke()
          if (result.ok) return { state: 'created', agentId: result.session.agentId, resumed: result.resumed }
          // RESTART_FAILED can follow an unobserved relaunch. Never silently
          // replace that process again when a caller checks this intent.
          if (result.error === 'RESTART_FAILED' || result.error === 'RESUME_UNCONFIRMED') return { state: 'unconfirmed' }
          return { state: 'failed', error: result.error, ...(result.reason ? { reason: result.reason } : {}),
            ...(result.detail ? { detail: result.detail.slice(0, 2000) } : {}) }
        }).then(async (status) => {
          reply({ creationId, ...await creationStatusPayload(status), ...(status.state === 'created' ? echo() : {}) })
        }).catch(() => reply({ error: 'INTERNAL' }))
      } catch (error) {
        reply({ error: error instanceof AgentCreationReceiptError ? error.code : 'INTERNAL' })
      }
      return
    }
    const result = await invoke()
    if (!result.ok) {
      reply({ error: result.error, ...(result.reason ? { reason: result.reason } : {}), ...(result.detail ? { detail: result.detail } : {}) })
      return
    }
    reply({ agent: await toProject(result.session), resumed: result.resumed, ...echo() })
  }

  // Fork an agent: a second one with the first one's history — see lib/forkAgent.ts. The reply
  // is agent_create's shape plus `level`, so a client opens the pane the same way.
  const fork = async (payload: Record<string, unknown>, reply: Reply): Promise<void> => {
    const target = payload.agentId as string | undefined
    if (!target) { reply({ error: 'MISSING_AGENT_ID' }); return }
    const onForkAgent = forkAgent()
    if (!onForkAgent) { reply({ error: 'UNSUPPORTED_ON_REMOTE' }); return }
    const name = typeof payload.name === 'string' && payload.name.trim() ? payload.name.trim().slice(0, 120) : null
    const rawPrompt = payload.prompt
    if (rawPrompt !== undefined && rawPrompt !== null && typeof rawPrompt !== 'string') { reply({ error: 'INVALID_PROMPT' }); return }
    const prompt = typeof rawPrompt === 'string' && rawPrompt.trim() ? rawPrompt : null
    if (prompt && prompt.length > MAX_FIRST_PROMPT_CHARS) { reply({ error: 'PROMPT_TOO_LONG' }); return }
    const creationId = payload.creationId
    if (creationId !== undefined) {
      if (!validCreationId(creationId)) { reply({ error: 'INVALID_CREATION_ID' }); return }
      // Forking starts a new process too. Reserve the same durable intent used
      // by agent_create so a lost receipt can be checked without another fork.
      const fork = onForkAgent
      try {
        void receipts.run(creationId, creationFingerprint({ operation: 'fork', agentId: target, name, prompt }), async () => {
          const result = await fork({ agentId: target, name, prompt })
          if (result.ok) return { state: 'created', agentId: result.session.agentId, level: result.level }
          if (result.error === 'SPAWN_FAILED' || result.error === 'REGISTRATION_FAILED') return { state: 'unconfirmed' }
          return { state: 'failed', error: result.error, ...(result.detail ? { detail: result.detail.slice(0, 2000) } : {}) }
        }).then(async (status) => {
          reply({ creationId, ...await creationStatusPayload(status) })
        }).catch(() => reply({ error: 'INTERNAL' }))
      } catch (error) {
        reply({ error: error instanceof AgentCreationReceiptError ? error.code : 'INTERNAL' })
      }
      return
    }
    const result = await onForkAgent({ agentId: target, name, prompt })
    if (!result.ok) {
      reply(result.detail ? { error: result.error, detail: result.detail } : { error: result.error })
      return
    }
    reply({ agent: await toProject(result.session), level: result.level })
  }

  const cancelCreate = async (payload: Record<string, unknown>, asker: Pick<Asker, 'local' | 'guest'>, reply: Reply): Promise<void> => {
    if (!validCreationId(payload.creationId)) { reply({ error: 'INVALID_CREATION_ID' }); return }
    try {
      // A guest cancels nothing of another's, and leaves no cancelled mark for an id that is not its own.
      if (hiddenFrom(asker, payload.creationId)) { reply({ creationId: payload.creationId, state: 'missing' }); return }
      reply({ creationId: payload.creationId, ...await creationStatusPayload(receipts.cancelIntent(payload.creationId)) })
    }
    catch (error) { reply({ error: error instanceof AgentCreationReceiptError ? error.code : 'INTERNAL' }) }
  }

  return { createStatus, cancelCreate, create, relaunch, fork, open: pending.open, stop: pending.stop, recover: pending.recover }
}