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 { createGridAssignments } from './agents/gridAssignments.js'
import { createShortTurnGuard } from './turns/shortTurnGuard.js'
import { createQuestionControls } from './engines/questionControls.js'
import { masterRunsEngineQuestionControl } from '../harnessd/services.js'
import { createModelControls } from './engines/modelControls.js'
import { masterRunsEngineModelControl } from '../harnessd/services.js'
import { createScreens } from './engines/screens.js'
import { createScreenTransport } from './engines/screenTransport.js'
import { inProcessScreen, preloadEngine } from '../engines/inProcess.js'
import { opencodeMajorVersion } from '../engines/launchControl.js'
import { inspectNativeLaunch, type NativeLaunch } from '../engines/nativeLaunch.js'
import { nativeHookLocations } from '../engines/kit/nativeLocations.js'
import { createNativeLaunchPreparer } from '../engines/prepareNativeLaunch.js'
import { engineDownloading } from '../engines/kit/downloadMarker.js'
import { createNativeInstallations } from '../engines/kit/nativeInstall.js'
import { createWindowsInstallations } from '../engines/kit/windowsInstall.js'
import { publishGridConfigDir } from '../lib/publishedGridConfig.js'
import { masterRunsEngineScreen } from '../harnessd/services.js'
import { createSubmissions } from './engines/submissions.js'
import { createNativeControls } from './engines/nativeControls.js'
import { createEngineLinks } from './engines/engineLinks.js'
import { engineLaunches } from '../engines/launches.js'
import { masterRunsEngineNativeControl } from '../harnessd/services.js'
import { submissionPolicy } from '../engines/submissionPolicies.js'
import { createSubmissionTransport } from './engines/submissionTransport.js'
import { masterRunsEngineSubmission } from '../harnessd/services.js'
/**
* The core's entry: `harness __run`. `runForeground` is the composition root, which builds the core's
* modules, starts the services through `serviceHost` and wires them to the socket
* (cli/AGENTS.md). It moved here from cli.ts verbatim, with what only it uses, so that the core's process
* is measured from its own entry rather than from the CLI's (docs/design/2026-10-06-core-boundary-next.md,
* step 1); `src/architecture.spec.ts` walks the imports from this file and holds them to a budget.
*
* cli.ts stays the process's entry and the CLI: it parses the command and, for `__run` (and a start under tsx,
* or `start -f` with `HARNESS_NO_MASTER=1`), calls in here. `start -f` runs harnessd's master, which starts
* the core with `__run`.
*/
import { readFileSync, writeFileSync, openSync, existsSync, rmSync, statSync } from 'fs'
import { readFile } from 'node:fs/promises'
import { join } from 'path'
import { execFile, spawn } from 'child_process'
import { createServer, type Server } from 'http'
import { homedir, hostname } from 'os'
import { env } from '../config/env.js'
import { VERSION } from '../version.js'
import { isLocalOnly, withoutUpdate } from '../lib/cardUpdate.js'
import { elapsedSecondsOf } from '../lib/footerTimer.js'
import { sqlitePreflightMessage } from '../lib/sqliteAvailability.js'
import { loginShellCaptureLine, warmLoginShellEnvironment } from '../lib/loginShellEnv.js'
import { enableOffThreadExec } from '../lib/offThreadExec.js'
import type { AppSwarms } from '../cable/cableSession.js'
import type { UnreadNotification } from '../lib/notificationRead.js'
import { claudeHomeOffered } from '../lib/claudeProfiles.js'
import { registry, projectDisplayName, validTranscriptPath, type RegisteredSession } from '../lib/registry.js'
import { engineSessionTitle } from '../lib/sessionTitle.js'
import { machineNames } from '../lib/machineNames.js'
import { engineHooks as engineHookFacets } from '../engines/hooks.js'
import type { LiveFor } from '../engines/facets/live.js'
import { DAEMON_LOG_FILE, PID_FILE, daemonPort, isAlive, readPid, LEGACY_LOG_FILE, MACHINE_NAME_FILE, tildify, computerId, thisDeviceLabel } from '../lib/daemonState.js'
import { clearSafeModeMarker, safeModeDisposition, safeModeStatusBody, SafeModeRequest, writeSafeModeMarker } from '../lib/daemonSafeMode.js'
import { awakeTimeout } from '../lib/sleepAware.js'
import { removePidFileIf, onError } from '../lib/daemonLaunch.js'
import { harnessdEnv, holdHarnessdEnv } from '../lib/harnessdEnv.js'
import { dropAgentSessionEnv } from '../lib/agentSessionEnv.js'
import { AUTH_DIR, AuthSessionManager, ensureSignInEpoch, markSignedOut, readAuthSession, signInOf, type AuthSession } from '../lib/authSession.js'
import { ENGINES, enginePathOverride } from '../lib/engineBin.js'
import { isTerminalEngine, type AgentEngine } from '../engines/types.js'
import { engineInstallRecipe } from '../lib/engineInstall.js'
import { buildEngineLaunchArgv, engineLaunchEnv, supportsFirstPrompt } from '../lib/engineLaunch.js'
import { isWindowsHeldPane, windowsPaneLaunch } from '../lib/windows/engineStart.js'
import { createGuestHostBackend } from '../lib/windows/guestHostBackend.js'
import { workspaceMissing } from '../lib/workspaceCheck.js'
import { HERMES_SYSTEM_MANAGED_DIR, type GridLaunchMachine } from '../lib/gridLaunchWire.js'
import { writeGridConfigDir } from '../lib/gridConfigDir.js'
import { clearDeleted, isRecentlyDeleted, markDeleted } from '../lib/deletedSessions.js'
import { findLiveSession, findResumedTranscript } from '../lib/sessionRepair.js'
import { processSessionOf } from '../engines/sessionStores.js'
import { createHandoffDependencies } from './handoffDependencies.js'
import { TmuxBackend } from '../lib/tmuxBackend.js'
import { tmuxAvailableNow } from '../lib/tmuxOnPath.js'
import { createTerminalBackendRecovery } from '../lib/terminalBackendRecovery.js'
import { isDrainBackend, ptyHostBackends, ptyHostOnProbation, PtyHostDrain, rowInstancesOf, rowsOnInstance, untilHostAttached, withoutCreateHost } from '../lib/ptyHost/drain.js'
import { removeUnusedPtyVersions, targetHost } from '../lib/ptyHost/launch.js'
import { DEFAULT_HOST_THEME, loadHostTheme, saveHostTheme, type HostTheme } from '../lib/hostTheme.js'
import { restoreAgents, type RestoreAgentsDeps, type RestoreSummary } from '../lib/restoreAgents.js'
import { restoreTerminals } from '../lib/restoreTerminals.js'
import { acquireAfterHold, MoveGate } from '../lib/hostMove/gate.js'
import { HostMover, settleMovesForHandOver } from '../lib/hostMove/mover.js'
import { moveHeldLine, removeOrphanMovePanes, type MoveOutcome } from '../lib/hostMove/moveAgent.js'
import { QUIET_MS, QuietClock } from '../lib/hostMove/quiet.js'
import { resumesConversation } from '../lib/resumeCapability.js'
import { createRetainExitedSession } from '../lib/retainExitedSession.js'
import { createKeepAbandonedConversation } from '../lib/keepAbandonedConversation.js'
import { RESUME_READINESS_BUDGET_MS } from '../lib/resumeStoppedAgent.js'
import { createConversationOwners } from './agents/conversationOwners.js'
import { OpenTabProtection } from '../lib/openTabProtection.js'
import { createNativeTurnObservations, nativeTurnBinding } from '../lib/nativeTurnObservations.js'
import { sessionCheckpoints } from '../lib/sessionCheckpoint.js'
import { repairProjectCwds } from '../lib/cwdRepair.js'
import { stoppedAgents } from '../lib/stoppedAgents.js'
import { externalSessionAnswer, externalUnavailable } from '../lib/externalSessionWire.js'
import { externalResumePending } from '../lib/externalResume.js'
import { type LaunchOverridesDeps } from '../lib/launchOverrides.js'
import { buildHarnessSessionLabel } from '../lib/harnessSessionLabel.js'
import { listTmuxPanes } from '../lib/tmuxAgentDiscovery.js'
import { installedDsh, invalidateInstalledDsh } from '../dsh/installed.js'
import { dshThrough } from './agents/dshThrough.js'
import { ApiConnectionMetadata } from '../lib/apiConnectionMetadata.js'
import { prepareApiInstructions } from '../lib/apiInstructions.js'
import type { AgentDshContext } from '../lib/agentFrame.js'
import type { AgentGridTarget, GridAnnotation } from '../lib/gridAnnotation.js'
import { confirmHomes, sessionCodexHome } from '../lib/engineHomes.js'
import { sessionStoreContracts } from '../engines/sessionStoreContracts.js'
import { argvTokens, processRows } from '../lib/processTable.js'
import { defaultTerminalBackends } from '../config/terminalConfig.js'
import { prepareTerminalBackends, TerminalBackendCoordinator } from '../lib/terminalBackendCoordinator.js'
import { canRestart, heldIn, noBackendCode, type TerminalBackend } from '../lib/terminalBackend.js'
import { handoffAgentId } from '../lib/terminalHandoff.js'
import { TerminalStreamManager } from '../lib/terminalStreamManager.js'
import { ownedPanesOf, terminalRouteKey, terminalRuntimeLabel } from '../lib/terminalRuntime.js'
import { probeTerminalAgents } from '../lib/terminalAgentDiscovery.js'
import { RECONCILE_PASS_DEADLINE_MS, TerminalAgentReconciler } from '../lib/terminalAgentReconciler.js'
import { Watcher } from '../watcher/watcher.js'
import { startHookServer } from '../hookServer.js'
import { connectToMaster } from '../harnessd/coreLink.js'
import { daemonStopRoute, leaveBeforeStartUp } from './daemonStopRoute.js'
import { createTerminalOpener } from './terminals/open.js'
import { createTerminalSessions } from './terminals/sessions.js'
import { checkPidRuntime } from '../lib/deleteAgentFallback.js'
import { SHELL_REQUESTS } from '../lib/shellProtocol.js'
import { answerShellQuery } from './shellQueries.js'
import { createTerminalControl } from './terminals/control.js'
import { createTerminalRequests } from './terminals/requests.js'
import { createBrowser } from './terminals/browser.js'
import { loopbackGet } from '../lib/loopbackGet.js'
import { writeBrowserShim } from '../lib/browserShim.js'
import { createAgentEvents } from './agents/events.js'
import { createSessionNormalizers } from './transcripts/normalizers.js'
import { createInput } from './input.js'
import { createQuestionResponse, createQuestions } from './questions.js'
import { createCloudAgents, type CloudAgents } from './agents/cloud.js'
import { createCloudLink } from './cloudLink.js'
import { activityOf, createTurnActivity } from './turns/activity.js'
import { createLastTurnReader } from './transcripts/lastTurn.js'
import { createEngineReaders } from './engines/readers.js'
import { createLiveTransport } from './engines/liveTransport.js'
import { createLiveWatcher } from './engines/liveWatcher.js'
import { readerEngine, READER_SERVICES } from '../engines/worker/protocol.js'
import { createRecaps } from './turns/recaps.js'
import { summaryReader } from './turns/summaries.js'
import { stopDeadline } from './stopDeadline.js'
import { stopsForGood } from './stopReasons.js'
import { createUpdateHandoff, handOverOnceReleased, probeStagedMaster, type TeardownStep } from './updateHandoff.js'
import { needsUpdaterBeside, startUpdaterBeside } from './updaterBeside.js'
import { createHeartbeats } from './turns/heartbeats.js'
import { createEventFunnel } from './turns/funnel.js'
import { createAgyBackstop } from './turns/agyBackstop.js'
import { createIngest } from './transcripts/ingest.js'
import { createTurnHooks } from './turns/turnHooks.js'
import { createAttach } from './transcripts/attach.js'
import { createHistory } from './transcripts/history.js'
import { createRelaunchMarks, transcriptSize } from './transcripts/relaunch.js'
import { createForgetSession } from './agents/forget.js'
import { createBinding } from './agents/bind.js'
import { createDiscoveryHandlers } from './agents/discovery.js'
import { createLaunchHelpers, gridLaunchThrough } from './agents/launch.js'
import { createLaunchAuthority } from './agents/launchAuthority.js'
import { AgentRestartCoordinator } from '../lib/restartAgent.js'
import { createPaneOperations } from './agents/paneOperations.js'
import { createRestoreLaunch } from './agents/restoreLaunch.js'
import { createHeldLaunches, heldPaneArgv } from './agents/heldLaunches.js'
import { createCancel, createCancelRequest } from './turns/cancel.js'
import { createPaneWatcher } from './agents/newPane.js'
import { createExternalResumes } from './agents/externalResume.js'
import { createExternalPreflight } from './agents/externalPreflight.js'
import { createAgentCreator } from './agents/create.js'
import { createAgentForker } from './agents/fork.js'
import { createPaneSwap } from './agents/swap.js'
import { createAgentRetargeter } from './agents/retarget.js'
import { createAgentRestarter } from './agents/restart.js'
import { createHostMove, moveWaitingArgv } from './agents/hostMove.js'
import { createAgentLifecycle, createPurgeRequest, createStopRequest } from './agents/lifecycle.js'
import { createAgentClosing, createCloseRequests } from './agents/close.js'
import { answerConversationQuery, conversationReads } from './conversationQueries.js'
import { createLaunchRequests } from './agents/launches.js'
import { createAgentList } from './agents/list.js'
import { createAgentUpdate } from './agents/update.js'
import { createEngineHooks, installEngineHooks, installOpencodePluginBeforeSpawn } from './engines/hooks.js'
import { createCursorDiscovery } from './engines/cursorDiscovery.js'
import { createCursorTaskHooks, loadPendingCursorTasks } from './engines/cursorTasks.js'
import { databaseHistory, hermesDb } from './transcripts/databaseHistory.js'
import { CLOUD_FALLBACKS, CLOUD_REQUESTS, type CloudCore, CONNECTORS_REQUESTS, SHARED_MACHINES_FALLBACKS, SHARED_MACHINES_OFF, SHARED_MACHINES_REQUESTS, MEMORY_REQUESTS, ROUTER_REQUESTS, createCoreApi, DEVICES_FALLBACKS, DEVICES_REQUESTS, emptyPorts, MACHINE_ADDON_REQUESTS, HANDOFF_REQUESTS, EXPERIMENTS, LONG_ANSWERS, MODELS_FALLBACKS, MODELS_OFF, MODELS_REQUESTS, MONITOR_FALLBACKS, MONITOR_OFF, MONITOR_REQUESTS, ORCHESTRATOR_FALLBACKS, OS_DEVICE_REQUESTS, ORCHESTRATOR_REQUESTS, SHARE_REQUESTS, SHARING_FALLBACKS, PROJECTS_REQUESTS, SEARCH_FALLBACKS, SEARCH_REQUESTS, STORE_FALLBACKS, STORE_OFF, STORE_REQUESTS, MESSAGES_FALLBACKS, MESSAGES_REQUESTS, TURN_DELIVERERS, USAGE_FALLBACKS, USAGE_REQUESTS, VIEWERS_FALLBACKS, WIFI_FALLBACKS, WINDOW_NAMES_REQUESTS, WORKSPACES_FALLBACKS, type GatewayAccount, type GatewayOps, type GatewayStatus, type RouteAnswer, type WindowFocus } from './api.js'
import { createServiceHost, testFaults } from './serviceHost.js'
import { SUPER_TAB_REQUESTS, SUPER_TAB_FALLBACKS } from './api.js'
import { startStalls } from './stall.js'
import { createServiceLinks, type ServiceLinks } from './serviceLinks.js'
import { createViewerStreams } from './viewerStreams.js'
import { createViewersLink } from './viewersLink.js'
import { createWorkspacesLink } from './workspacesLink.js'
import { createMonitorLink } from './monitorLink.js'
import { createSharedMachinesLink } from './sharedMachinesLink.js'
import { createGuestCreate } from './agents/guestCreate.js'
import { createStoreLink } from './storeLink.js'
import { createModelsLink } from './modelsLink.js'
import { createRecapsLink } from './recapsLink.js'
import { createAgentCleanupLink } from './agentCleanupLink.js'
import { AGENT_CLEANUP_FALLBACKS, RECAPS_FALLBACKS, TERMINALS_OFF } from './api.js'
import { answerAgentQuery } from './agentQueries.js'
import { createDeliveries } from './deliveries.js'
import { createTerminalWatch } from './terminalWatch.js'
import { createSharingLink } from './sharingLink.js'
import { createAgentSettingsSync, createExperimentHooks, wakeExperiments } from './experiments.js'
import { answerExperimentQuery, answerMachineAddonsQuery, createForExperiment, creationForExperiment } from './experimentQueries.js'
import { answerConnectorsQuery } from './connectorsQueries.js'
import { answerSharedMachinesQuery } from './sharedMachinesQueries.js'
import { inlineSharedMachinesPort } from '../lib/sharedMachinesPort.js'
import { createOrchestratorLink } from './orchestratorLink.js'
import { daemonCommand } from '../lib/daemonCommand.js'
import { KNOWN_SERVICES, masterRunsEngineRuntime, masterRunsLiveEngines, servicesOn, servicesTheMasterRuns, swarmOn } from '../harnessd/services.js'
import { askForMessages, createMessagesLink } from './messagesLink.js'
import { createDevicesLink } from './devicesLink.js'
import { CORE_EXIT_STOP, CORE_EXIT_UPDATE, PROBE_COMMAND } from '../harnessd/protocol.js'
import { localSocketListenPath, localSocketPath, refuseServedDataFolder, servedFolderDeps, type LocalSocketServer } from '../lib/localSocket.js'
import { ensureDaemonToken } from '../lib/windows/pipeAuth.js'
import { claimDataFolder } from '../lib/windows/dataFolderClaim.js'
import { saveDaemonPort } from '../lib/daemonEndpoint.js'
import { publishHookRoute } from '../lib/hookRoutes.js'
import { BackendSocket, isLocalClientId } from '../backendSocket.js'
import { createGatewayLink, laneOf, tabKeyOf, tabRelayOf } from './gatewayLink.js'
import { createWifiCore, WIFI_START_MS } from './wifi.js'
import { createDevicesWake, DEVICES_ON_DEMAND } from './devicesWake.js'
import { wakeModels } from './modelsWake.js'
import { wakeGateway } from './gatewayWake.js'
import { createViewersWake, VIEWERS_ON_DEMAND, wakeViewers } from './viewersWake.js'
import { createWifiLink } from './wifiLink.js'
import { wifiDoors } from './wifiAgents.js'
import { autonomousDeviceLocalRequest, deviceAddonRoutes, machineAddonRoutes } from '../lib/deviceManagementHttp.js'
import { loadOrCreateHookCredential } from '../lib/hookAuth.js'
import { attachLocalWsServer, LOCAL_WS_PATH, LOCAL_WS_PROTOCOL_VERSION } from '../localWsServer.js'
import { TERMINAL_BINARY_VERSION } from '../lib/terminalBinary.js'
import { isLoopbackRequest, loopbackHosts } from '../lib/loopbackRequest.js'
import { isInstalledCopy } from '../lib/installedCopy.js'
import { managedNodePath } from '../lib/nodeRuntime.js'
import { type ActivityFrame } from '../lib/turnActivity.js'
import { cursorDataDir } from '../engines/cursor/contract.js'
import { TranscriptPager } from '../lib/transcriptPages.js'
import { AgentCreationReceipts } from '../lib/agentCreationReceipt.js'
import { agentFrame, lastActivityAt, type AgentFrame } from '../lib/agentFrame.js'
import { transcriptActivityAt } from '../lib/transcriptActivity.js'
import { forgetAgentProject } from '../lib/agentProject.js'
import { createUsageLink } from './usageLink.js'
import type { UsageSnapshots } from './usageLink.js'
import { usageTarget, validUsage, validUsageTarget, type AgentUsageTarget } from '../lib/agentUsageWire.js'
import { RuntimeProfileState, type RuntimeModelOption } from '../lib/runtimeProfileState.js'
import { createRuntimeProfiles } from './engines/runtimeProfiles.js'
import { createRuntimeTransport } from './engines/runtimeTransport.js'
import { RuntimeProfileController } from '../lib/runtimeControl.js'
import { installTimestampedConsole, sid, prepareLogFile, trimLogFile, LOG_CHECK_INTERVAL_MS } from '../lib/log.js'
import { backendHttpBase } from '../lib/controlPlane.js'
// Daemon stdout/stderr. Capped at LOG_MAX_BYTES — see prepareLogFile/trimLogFile in lib/log.ts.
const LOG_FILE = DAEMON_LOG_FILE
/** Pairing labels that stand in for a name rather than being one (manager.ts `addPaired` callers). */
const GENERIC_PAIR_LABELS: ReadonlySet<string> = new Set(['harness link', 'browser'])
/** The name a new terminal tile greets with: the machine's display name the backend gave it, else the host's. */
function terminalHintMachineName(): string {
try { return readFileSync(MACHINE_NAME_FILE, 'utf-8').trim() || hostname() } catch { return hostname() }
}
/** The name the dial's wheel and the fleet give this computer: its display name, else "This machine". */
function dialMachineName(): string {
try { return readFileSync(MACHINE_NAME_FILE, 'utf8').trim() || 'This machine' } catch { return 'This machine' }
}
/**
* The window's tiles, in tile order, as last reported.
*
* Kept HERE rather than only handed to the cable host, because the window can
* report them before that host exists: the local websocket server is listening
* long before the cable is wired up, and a daemon restart has the app
* reconnecting into that window. The roster is only re-sent when it CHANGES, so
* one early report used to leave the dial's ring flat and edgeless for as long
* as the tiles held still — which looks exactly like the feature not being
* installed, and cost most of a morning proving otherwise.
*/
let appPaneAgents: string[] = []
/**
* The window's tabs, kept for the same reason: a window can connect while this daemon is still
* booting (the app no longer waits for its first scan), and an `app_swarms` that lands before the
* cable host exists was dropped — the dial then had no tab, drew "Choose a pane" and took no swipe
* or voice until the window happened to send its tabs again (measured 2026-10-01: 80 s).
*
* Kept by the core, too, because the devices can restart where the windows do not: in a process of
* their own (step 9), a devices process that starts again is told the desk, the tabs, what is unread
* and which window has the person's attention, as they stand (services/devices.ts).
*/
let appSwarmsLatest: AppSwarms | null = null
/** What the window still has unread, kept for the same reason. */
let appUnreadLatest: UnreadNotification[] = []
// OpenCode's SQLite store — polled per session by OpencodeReader (no per-session transcript file).
const OPENCODE_DB = join(env.OPENCODE_DATA_DIR, 'opencode.db')
// Kilo's SQLite store — same shape, its own file and its own reader (see engines/kilo/).
const KILO_DB = join(env.KILO_DATA_DIR, 'kilo.db')
// Hermes keeps every surface's history in one SQLite store PER HOME — polled per session by
// HermesReader, against the home that session lives in (`hermesDbForSession`; `hermes -p <name>` has
// its own). Reading one fixed store is what left profile agents' activity empty (openharness#191).
// Devin likewise keeps all history in one SQLite store (WAL) — polled per session by DevinReader.
const DEVIN_DB = join(env.DEVIN_HOME, 'sessions.db')
/** How many agents' histories are read at once — the first reconcile pass after a boot asks for every
* agent's, and each read is a tmux probe, a `ps`, and the whole transcript or store (see `attaches`). */
const ATTACH_CONCURRENCY = 4
/** The currently-running script — dist/cli.js when built, src/cli.ts under tsx. Named by cli.ts, the
* process's entry, as it starts the core: under tsx this module's own URL is src/core/main.ts. */
let SCRIPT_PATH = ''
/**
* Start harnessd's master, detached, on the bundle on disk, and name it in the pid file: how a core on its
* own hands the machine to a newer build (core/updateHandoff.ts); the master judges it. Named at once, so a
* `harness start` in the seconds after this core leaves finds a live daemon and starts no second master,
* whose core would lose to this one's and roll the update back. Not `harness start`'s `spawnDaemon`, which
* finds THIS daemon in the pid file and exits. The managed Node is re-read, so a runtime provisioned while
* this ran is the master's. `ADAPTER_UPDATED_TO` (an older build's handoff) and `HARNESSD_SAFE_MODE` (a
* master's word to its own core) are not for the master to pass to every core it starts. The rest of what
* this core was started with is, its `HARNESSD_*` included (lib/harnessdEnv.ts): the master is harnessd's.
*/
function startMasterHere(): void {
// A log that cannot be opened (a full disk) costs the master's lines, never the handoff.
let log: number | 'ignore' = 'ignore'
try {
prepareLogFile(LOG_FILE, LEGACY_LOG_FILE)
log = openSync(LOG_FILE, 'a')
} catch (e) { console.error('[update] the master starts without the log:', e instanceof Error ? e.message : e) }
const { ADAPTER_UPDATED_TO: _handedOver, HARNESSD_SAFE_MODE: _safeMode, ...inherited } = harnessdEnv()
const master = spawn(managedNodePath(), [SCRIPT_PATH, '__harnessd'], { detached: true, env: inherited, stdio: ['ignore', log, log] })
// A spawn failure (e.g. EMFILE) emits 'error' on the child; with no listener that is an
// uncaughtException. This core is leaving either way, and the next `harness start` starts the daemon.
master.on('error', (e) => console.error('[update] master spawn error:', e instanceof Error ? e.message : e))
master.unref()
try {
if (master.pid) writeFileSync(PID_FILE, `${master.pid}\n`)
else removePidFileIf(process.pid)
} catch { /* the master claims it itself once its core has bound */ }
console.log(`[update] harnessd's master started (pid ${master.pid ?? '?'})`)
}
/**
* What a staged update does while the daemon is still starting up — and the little the boot needs to
* know about itself to do it.
*
* The master's updater (services/updaterProcess.ts) can stage a build at any moment, and the master then
* asks this core to hand over (`harnessd:update`), which `runForeground`'s prologue listens for before
* anything that can throw or hang: a daemon that cannot finish booting must still leave for its fix. That
* request therefore has to mean something LONG before `restartForUpdate` exists — hence the indirection:
* `applyStagedUpdate` is `bootHandoff` until the body has built everything `restartForUpdate` tears down,
* and is swapped for it at that one line.
*/
/** This process's channel to a harnessd master, when one started it (see harnessd/coreLink.ts).
* Inert otherwise: a daemon run on its own claims its pid file, and gets no updates. */
const coreLink = connectToMaster()
/** When the devices' process starts: once there is a device, a dial's port, a Wi-Fi device or a request for one
* (core/devicesWake.ts). Asked of the master through the channel above. */
/** A Harness Team daemon runs no devices, the Wi-Fi device's service or the dials' (security re-check 1 of #2089): set as
* it decides it is one (runForeground), before anything is wired to them. */
let devicesOff = false
const devicesWake = createDevicesWake({ want: (service) => { if (!devicesOff) coreLink.want(service) }, dataDir: env.ADAPTER_DATA_DIR, cableDisabled: env.CABLE_DISABLE, testDialPort: harnessdEnv().HARNESSD_TEST_DIAL_PORT })
const daemonBoot: {
/** Stops the updater this core runs beside itself under a master too old to run it (core/updaterBeside.ts). */
updaterBeside: (() => void) | null
/** The hook server, once bound — the only thing a mid-boot handoff has to release. */
hookServer: Server | null
/** Its Unix-socket twin (lib/localSocket.ts), when one could be opened. Read by `/api/status`. */
localSocket: LocalSocketServer | null
/** Set by the body so a failed boot can flip its own `/api/status` to not-ready. */
markNotReady: ((reason: string) => void) | null
/** Why this daemon is in safe mode, or null while it is healthy. Read by `/api/status`. */
safeMode: string | null
handingOff: boolean
applyStagedUpdate: (version: string) => void | Promise<void>
/** Opens the request gate of a start-up that did not finish, so its clients are answered (safe mode). */
openRequests: (() => void) | null
/**
* This core's own stop, for `harness stop` on Windows when no master runs it (core/daemonStopRoute.ts). The route
* is served from the moment the hook server is bound, so it is held here: until `runForeground` has built its
* `shutdown` it leaves at once, then it is `shutdown`, and in safe mode, safe mode's `leave`.
*/
stopHere: (why: string) => void
} = {
updaterBeside: null, hookServer: null, localSocket: null, markNotReady: null, safeMode: null, handingOff: false, applyStagedUpdate: bootHandoff, openRequests: null,
stopHere: leaveBeforeStartUp({ removePidFile: () => { removePidFileIf(process.pid) }, log: (line) => console.log(line), exit: (code) => process.exit(code) }),
}
/**
* Hand the machine to a newer build without finishing start-up: the master asked (its updater staged one),
* and starts the new bundle the moment this exits, and judges it.
*
* SYNCHRONOUS END TO END, and that is the whole safety argument: never awaiting means the half-built
* `runForeground` body cannot interleave between the port closing and the exit, so it can never reach the
* code that would bind the port the successor is about to take. Only a master asks; a core without one
* gets no updates.
*/
function bootHandoff(version: string): void {
if (daemonBoot.handingOff) return
daemonBoot.handingOff = true
console.log(`[update] ${VERSION} → ${version} staged during start-up — handing back to harnessd`)
try { daemonBoot.hookServer?.close() } catch { /* already gone */ }
try { daemonBoot.localSocket?.closeSync() } catch { /* already gone */ }
process.exit(CORE_EXIT_UPDATE)
}
/** Set by runForeground once the DSH companions exist; a frame projected before that carries none. */
let activityFrameContextRef: ((s: RegisteredSession) => ActivityFrame | null) | null = null
let dshFrameContextRef: ((s: RegisteredSession) => AgentDshContext | null) | null = null
/** Aggregate snapshots only; populated after the optional usage port is composed. */
let usagePortRef: UsageSnapshots | null = null
/** Set by runForeground once models can be asked: what an agent's frame says of its grid. */
let gridAnnotationRef: ((grid: AgentGridTarget) => GridAnnotation | null) | null = null
function projectFrame(s: RegisteredSession, selectedModel: string | null): Promise<AgentFrame> {
return agentFrame(s, {
tokenUsage: usagePortRef?.get(s) ?? null,
selectedModel,
terminalAvailable: registry.terminalAvailable(s.agentId),
dsh: dshFrameContextRef?.(s) ?? null,
activity: () => activityFrameContextRef?.(s) ?? null,
gridAnnotation: (grid) => gridAnnotationRef?.(grid) ?? null,
})
}
function primaryTerminalLabel(session: RegisteredSession): string {
const runtime = session.runtimes.find((candidate) => terminalRouteKey(candidate) === session.primaryRuntimeKey)
return runtime ? terminalRuntimeLabel(runtime) : 'dormant'
}
/** The daemon body: hooks + watcher + process discovery + backend socket. */
async function runForeground(session: AuthSession | null): Promise<void> {
installTimestampedConsole() // daemon-only: every harness.log line gets a wall-clock timestamp
const startedAt = Date.now()
// Set when the restore pass could not run. The reconciler reads it at call time (its deps are built
// long before this is decided) and keeps rows it would otherwise retire — see `onRemoved`.
// Restore did not run this boot (every row), or could not look at these rows (core/agents/discovery.ts).
let restoreFailed = false
const restoreUnsurveyed = new Set<string>()
let discoveryReady = false
let discoveryError: string | null = null
// How a boot that failed AFTER this server bound turns its own status not-ready: the app reads
// `discoveryReady: false` as "alive, not ready" and stops respawning over it (`enterSafeMode`).
daemonBoot.markNotReady = (reason) => { discoveryReady = false; discoveryError = reason }
// The pid file is claimed further down, the moment the control port is bound — not here, and not
// by whoever spawned us. See the comment at that claim.
// Last-resort net: a stray throw in ANY long-lived callback (a malformed JSONL line, a hostile backend
// frame, a timer) must NEVER take the daemon down — there is no supervisor. Log it and keep running.
// (Startup errors still fail loudly: they reject the runForeground promise → onError → exit, not these.)
process.on('unhandledRejection', (reason) => {
console.error('[fatal-guard] unhandledRejection:', reason instanceof Error ? (reason.stack ?? reason.message) : reason)
})
process.on('uncaughtException', (err) => {
console.error('[fatal-guard] uncaughtException:', err instanceof Error ? (err.stack ?? err.message) : err)
})
// ── THE MASTER'S UPDATE IS HEARD FIRST. Everything below this point can throw, hang, or wait on a vendor
// file, a port, or tmux — and a daemon that never finishes starting must still leave for its fix. The
// updater is the master's, in a process of its own (services/updaterProcess.ts): the core never
// downloads a build. When it stages one, the master asks this core to hand over, and the request is
// listened for here, before anything that can fail.
//
// `applyStagedUpdate` is one indirection on purpose: the handoff's teardown does not exist yet and must not
// move (it tears down two dozen subsystems declared further down). Until it is ready, a staged update is
// applied by `bootHandoff`, which hands the machine over without finishing start-up.
coreLink.onUpdate((version) => { void daemonBoot.applyStagedUpdate(version) })
// The core's probes spawn from a worker, so a terminal's keystrokes never wait behind one (lib/offThreadExec.ts).
enableOffThreadExec()
// What the master told this core, read from here: runCore took it out of process.env before anything
// could hand it to a child (lib/harnessdEnv.ts).
const harnessd = harnessdEnv()
// Agents held until the service their launch asks is ready, and the passes that launch them
// (core/agents/heldLaunches.ts): the boot's restore of only those agents, set where tmux is there to restore into.
const restorePanes = createPaneOperations()
const restartJobs = new AgentRestartCoordinator()
// Moving agents off a drained pty host (lib/hostMove/): how long each has been idle and untouched, the one gate an
// agent's input waits in while it changes host, and the agents a move a dead daemon left may still run beside
// (`removeOrphanMovePanes` below), held this start: neither restored, nor discovered, nor moved.
const hostQuiet = new QuietClock({ now: Date.now })
const moveGate = new MoveGate()
const moveHeld = new Set<string>()
/** The conversations of the agents in [moveHeld]: an adoption of one would start a second engine on it too. */
const moveHeldConversations = new Map<string, string>()
let hostMover: HostMover | null = null
// Every removal of a row goes through here: its clocks go with it.
const forgetRestartRevision = (agentId: string): void => { restartJobs.forget(agentId); hostQuiet.forget(agentId) }
const restoreRevision = (agentId: string): number => restartJobs.revision(agentId)
let externalResumes: ReturnType<typeof createExternalResumes> | null = null
let searchGeneration = 0
let restoreCancelled = (_agentId: string): boolean => false
let launchCancelled = (_agentId: string): boolean => false
let restoreOnly: ((only: ReadonlySet<string>, current: () => boolean) => Promise<RestoreSummary>) | null = null
const heldLaunches = createHeldLaunches({
registry,
restore: (only, current) => restoreOnly?.(only, current) ?? Promise.resolve({ restored: [], skipped: [], failed: [], held: [], unsurveyed: [] }),
log: (line) => console.log(line),
})
wakeGateway({ outOfProcess: servicesTheMasterRuns(harnessd, KNOWN_SERVICES), signedIn: !!session, dataDir: env.ADAPTER_DATA_DIR, want: (service) => coreLink.want(service) })
// …or, under a master too old to run the updater, from the updater this core runs beside itself
// (core/updaterBeside.ts), in a process of its own: the core downloads no build either way.
if (needsUpdaterBeside(harnessd, coreLink.supervised, isInstalledCopy(SCRIPT_PATH, env.ADAPTER_CLI_DIR), env.ADAPTER_UPDATE_DISABLE)) {
daemonBoot.updaterBeside = startUpdaterBeside({
spawn: () => {
// Harnessd's own process: handed what this core's master said (HARNESSD_JUDGES_SUPERSEDED) explicitly.
const updater = spawn(managedNodePath(), [SCRIPT_PATH, '__service', 'updater'], {
env: { ...harnessdEnv(), HARNESSD_SERVICE: 'updater', HARNESSD_UPDATER_BESIDE_CORE: '1' }, stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
})
updater.on('error', (e) => console.error('[update] the updater could not start:', e instanceof Error ? e.message : e))
return { onMessage: (listener) => { updater.on('message', listener) }, onExit: (listener) => { updater.on('exit', listener) }, kill: () => { updater.kill() } }
},
staged: (version) => { void daemonBoot.applyStagedUpdate(version) },
log: (line) => console.log(line),
})
}
// The update handoff (core/updateHandoff.ts): after the update is listened for, never above it
// (startupOrder.spec.ts), and ahead of the /api/status handler that reads whether it is under way.
const updateHandoff = createUpdateHandoff({
version: VERSION, supervised: coreLink.supervised, exitForUpdate: () => process.exit(CORE_EXIT_UPDATE),
// A core on its own that an older release started: its master must answer its probe, as a master asks
// before it re-executes on a bundle; then the master takes the machine, and runs the updater.
probeMaster: () => probeStagedMaster((done) => execFile(managedNodePath(), [SCRIPT_PATH, PROBE_COMMAND], { encoding: 'utf8', env: harnessdEnv() }, (error, stdout) => done(error, stdout))),
handOff: () => { startMasterHere(); process.exit(0) },
log: (line) => console.log(line), error: (line) => console.error(line),
// A move to another pty host that holds input: waited for, or its input written out, before the teardown closes the
// pty host connection the held keystrokes would be written through (lib/hostMove/mover.ts).
beforeTeardown: () => settleMovesForHandOver({ mover: hostMover, gate: moveGate, log: (line) => console.log(line) }),
})
// Another daemon serves this data folder: leave before reading or writing anything of its — its
// registry, its viewers, its panes. Just after the update is listened for, never before it
// (startupOrder.spec.ts).
await refuseServedDataFolder(localSocketPath(env.ADAPTER_DATA_DIR, env.PORT), 1_000, servedFolderDeps(env.ADAPTER_DATA_DIR, env.PORT))
// Windows: each start listens on a pipe of a new name, which never meets a second core on this folder as the
// fixed Unix socket does, and the ask above cannot see two starts at once. The fixed claim, held while this core
// runs, refuses the second the same way (lib/windows/dataFolderClaim.ts). It proves the daemon's token to a start
// that finds its name taken, so a name another account took does not keep this daemon down.
const dataFolderClaim = process.platform === 'win32'
? await claimDataFolder(env.ADAPTER_DATA_DIR, ensureDaemonToken(env.ADAPTER_DATA_DIR), { holder: { pid: coreLink.masterPid ?? process.pid, corePid: process.pid } })
: null
// harnessd's master saw this core crash again and again: start nothing that could do it again. The
// master's updater runs on, and a published fix still lands (`enterSafeMode`).
if (harnessd.HARNESSD_SAFE_MODE) throw new SafeModeRequest(harnessd.HARNESSD_SAFE_MODE)
const savedApis = new ApiConnectionMetadata(env.ADAPTER_DATA_DIR)
// Instructions read metadata locally; a models outage must not change a workspace's tool instructions.
const prepareApiTools = (cwd: string | null | undefined, engine: string): void => {
if (!cwd) return
try { prepareApiInstructions(savedApis, cwd, engine) }
catch { console.warn('[apis] Tool instructions could not be added. Saved connections remain available through harness api.') }
}
// What a session of another engine reads starts loading as the session enters, from disk or later
// (engines/inProcess.ts).
registry.onEnter = preloadEngine
registry.load()
// Bindings can finish before full teardown exists, or during its awaits. Cover every owned exit,
// including a staged update received during startup, without touching a different daemon's table.
process.on('exit', () => registry.flush({ exiting: true }))
// Persisted locators are hints until this process has observed their terminal root and PID/start marker.
// Mark them dormant before the backend socket can publish anything; the first authoritative reconcile
// reactivates matching process agents without changing their public identity or session binding.
await registry.transaction(() => {
for (const session of registry.list()) registry.setActive(session.agentId, false)
})
// Unset means AUTO: watch this platform's default backend, ptyhost on Windows and tmux elsewhere (see
// config/terminalConfig.ts). `parseTerminalBackends` drops a retired `herdr` still named in someone's
// environment rather than refusing to boot on it.
const backendsExplicit = env.TERMINAL_BACKENDS !== undefined
const terminalConfig = {
backends: env.TERMINAL_BACKENDS ?? defaultTerminalBackends(process.platform),
}
// The desktop's pane colours, for tmux's `window-style` (lib/hostTheme.ts): the last ones the app
// sent, or its stock dark palette until it says otherwise. Read through a closure so a change
// reaches sessions created after it without rebuilding the backend.
let hostTheme: HostTheme = loadHostTheme() ?? DEFAULT_HOST_THEME
// Each configured backend readies itself (`TerminalBackend.prepare`: tmux finds its binary, renames
// legacy sessions, forgets harnessd's variables and logs its first inventory). One that cannot is a
// STATE the daemon runs on without, never a reason to refuse to start: it still serves its status, the
// local socket and the backend link, leaves for an update, and says what is missing.
const candidates: TerminalBackend[] = []
const configuredTmux = terminalConfig.backends.includes('tmux') ? new TmuxBackend(() => hostTheme) : null
if (configuredTmux) candidates.push(configuredTmux)
// The Harness PTY host (pty/): reached, or started detached so its panes outlive this daemon. New panes go to the
// target's host, the build this daemon would start; any other host, still running from before an update, is a
// drain backend beside it (lib/ptyHost/drain.ts). The target is read here once, for this core's life: it runs the
// binary (`harness-pty version`, up to 5 s), and an update that moves it starts a new core.
const ptyTarget = terminalConfig.backends.includes('ptyhost') ? targetHost() : null
if (terminalConfig.backends.includes('ptyhost')) {
console.log(ptyTarget ? `[terminal] ptyhost: target ${ptyTarget.instance}` : '[terminal] ptyhost: target unknown')
}
const ptyHosts = terminalConfig.backends.includes('ptyhost')
? ptyHostBackends(env.HARNESS_PTY_DIR, { target: ptyTarget, rowInstances: () => rowInstancesOf(registry.list()) })
: null
const ptyHostBackend = ptyHosts?.create ?? null
if (ptyHosts) candidates.push(ptyHosts.create, ...ptyHosts.drain)
// Each is handed the registry's panes on it, and only those, for adopting what an older build left
// (tmux's legacy session names): pane ids are per backend. One whose prepare throws is unavailable.
const preparing = prepareTerminalBackends(candidates, (backend) => ownedPanesOf(registry.list(), backend.name))
// Started while the backends prepare, which ask a login shell too (tmux: where it is installed): two
// independent login-shell spawns whose wall-clock cost overlaps instead of adding up.
// `loginShellEnvPromise` is awaited later, near the existing `[env]` log line.
const loginShellEnvPromise = warmLoginShellEnvironment()
console.log(`[terminal] enabled backends: ${terminalConfig.backends.join(', ')}`)
const prepared = await preparing
const readyBackends = prepared.filter((p) => p.result.state === 'ready').map((p) => p.backend)
// With no target, the create backend took whichever host answered, which a drain backend may be on too.
const terminalBackends = ptyHosts ? withoutCreateHost(readyBackends, ptyHosts.create) : readyBackends
// The first backend that could not be readied, and why, for the status's `discoveryError`.
let terminalUnavailable: { backend: TerminalBackend['name']; reason: string; code: string } | null = prepared.flatMap(({ backend, result }) => result.state === 'unavailable'
? [{ backend: backend.name, reason: result.reason, code: result.code }] : [])[0] ?? null
// The backend new panes are made on. Every other pane operation reaches the pane's own backend
// through the coordinator (`terminals.backendFor`).
let createBackend: TerminalBackend | null = terminalBackends.find((backend) => !isDrainBackend(backend)) ?? null
// What a create, fork or resume answers while there is none: the configured backend's code, not always tmux's.
const createUnavailable = noBackendCode(terminalConfig.backends)
// A hook's tmux runtime hint is taken only while tmux is the backend new panes are made on
// (core/engines/hooks.ts). Restart, retarget, restore and adoption reach each pane's own backend
// through the coordinator, gated on what it can do (`canRestart`, `isHeld`, `killHeld`).
let tmuxBackend = createBackend instanceof TmuxBackend ? createBackend : null
const terminals = new TerminalBackendCoordinator(
terminalBackends,
terminalConfig.backends,
)
const recoverBackend = createTerminalBackendRecovery({
backend: configuredTmux,
available: tmuxAvailableNow,
ownedPanes: () => ownedPanesOf(registry.list(), 'tmux'),
recovered: (backend) => {
terminalBackends.push(backend)
terminals.replaceBackends(terminalBackends)
createBackend = tmuxBackend = backend
if (terminalUnavailable?.backend === 'tmux') terminalUnavailable = null
console.log('[terminal] tmux recovered')
},
})
// Shut down a drained host once it has no pane, and take its backend out of `terminalBackends` (stepped after
// each reconcile pass, below).
const ptyDrain = ptyHosts?.drain.length
? new PtyHostDrain({
drain: ptyHosts.drain.filter((backend) => terminalBackends.includes(backend)),
backends: terminalBackends,
coordinator: terminals,
inUse: (instanceId) => rowsOnInstance(registry.list(), instanceId),
cleanup: () => { removeUnusedPtyVersions(env.HARNESS_PTY_DIR) },
// An old host is not shut down while new panes have no host to go to: it may be the only one that serves.
createAvailable: () => createBackend === ptyHosts.create && ptyHosts.create.attached,
})
: null
const sqliteWarning = sqlitePreflightMessage()
if (sqliteWarning) console.warn(sqliteWarning)
// The user's shell environment is captured at startup, not on the first recap — a slow profile
// (nvm, conda, …) then stalls nothing live. Started above alongside the tmux PATH probe, and LOGGED
// when it lands, never waited on: nothing before the control port binds needs it (lib/loginShellEnv
// caches the capture; engine one-shots read it through `loginShellEnvironment()`), and a second
// login shell held the port — and with it the app's "Starting local service…" — for as long as the
// slower of the two shells took. See lib/loginShellEnv.ts: this is what lets a recap reach a
// credential the user exports from their rc file, which a launchd/systemd-parented daemon never read.
{
const t0 = Date.now()
void loginShellEnvPromise.then((captured) => {
const line = loginShellCaptureLine(Object.keys(captured).length, Date.now() - t0)
if (line) console.log(line)
})
}
// Reading and writing panes through control leases (core/terminals/control.ts).
const terminalControl = createTerminalControl({ resolve: (target) => registry.resolve(target), terminals })
const pinnedControls = terminalControl.pinnedControls
restoreCancelled = (agentId) => pinnedControls.has(agentId) || moveHeld.has(agentId)
const invalidateTerminalControl = terminalControl.invalidateTerminalControl
const captureTerminal = terminalControl.captureTerminal
const submitTerminal = terminalControl.submitTerminal
const typeTerminal = terminalControl.typeTerminal
const keyTerminal = terminalControl.keyTerminal
const validateTerminal = terminalControl.validateTerminal
// Persisted records are not trusted blindly. The process reconciler below adopts a matching live
// runtime, replaces it immediately when PID/start-marker changed, and requires two successful misses
// before removing it. Probe errors leave the registry untouched.
// The voice router needs to know which engines the machine actually runs: a router warmed for an
// engine no agent uses is a worker nobody asked for. It is the devices' (services/devices.ts), which are
// told again as they start.
const syncRecapPool = (): void => {
ports.devices?.engines(registry.active().map((session) => session.engine))
}
// The Swarm switch (harnessd/services.ts `HARNESS_SWARM`, on unless set off): its code in this process comes from one
// entry, loaded only while it is on (superTabs/inCore.ts), and its service is left off with it.
const swarm = swarmOn(harnessd) ? await import('../superTabs/inCore.js') : null
// Decided once, as it starts: whether this daemon is a Harness Team account's (superTabs/inCore/teamApps.ts isTeamDaemon).
const teamDaemon = !!swarm?.isTeamDaemon()
devicesOff = teamDaemon
const knownServices = servicesOn(harnessd, KNOWN_SERVICES)
const outOfProcess = servicesTheMasterRuns(harnessd, knownServices)
// A Harness Team daemon is there for its Swarms: its Swarm service starts with it. Left on demand it never started: its
// owner's requests to it are refused until a Swarm roster has marked its sessions (superTabs/inCore/teamApps.ts), and only
// that service reads the roster (2026-10-30, the Mac Studio: a new Team account answered every "add it to the Swarm"
// TEAM_READ_ONLY and never joined; its log never showed the Swarm service connecting).
if (teamDaemon && outOfProcess.has('superTabs')) coreLink.want('superTabs')
// The viewers' process (the viewers and the Store) runs once something needs it (core/viewersWake.ts).
const viewersWake = createViewersWake({ want: (service) => coreLink.want(service), outOfProcess })
const liveHosted = masterRunsLiveEngines(harnessd, process.ppid)
const runtimeHosted = liveHosted && masterRunsEngineRuntime(harnessd, process.ppid)
// An older master's explicit capability report selects compatibility. A failed worker never does.
const isolatedLive = (engine: string): boolean => liveHosted
&& readerEngine(engine) && outOfProcess.has(READER_SERVICES[engine])
const questionControlHosted = masterRunsEngineQuestionControl(harnessd, process.ppid)
const isolatedQuestionControl = (engine: string): boolean => questionControlHosted && isolatedLive(engine)
const modelControlHosted = masterRunsEngineModelControl(harnessd, process.ppid)
const isolatedModelControl = (engine: string): boolean => modelControlHosted && isolatedLive(engine)
const screenHosted = masterRunsEngineScreen(harnessd, process.ppid)
const isolatedScreen = (engine: string): boolean => screenHosted && isolatedLive(engine)
const submissionHosted = masterRunsEngineSubmission(harnessd, process.ppid)
const nativeControlHosted = masterRunsEngineNativeControl(harnessd, process.ppid)
const isolatedNativeControl = (engine: string): boolean => nativeControlHosted && isolatedLive(engine)
const isolatedSubmission = (engine: string): boolean => submissionHosted && isolatedLive(engine)
const isolatedRuntime = (engine: string): boolean => runtimeHosted && isolatedLive(engine)
const inline = knownServices.some((name) => !outOfProcess.has(name)) || !runtimeHosted || !screenHosted || !modelControlHosted || !questionControlHosted || !submissionHosted || !nativeControlHosted
? await import('../services/inline.js') : null
// The Swarm's side of the services that act on it, for those of them that run in this process while it is on
// (superTabs/inServices.ts): off, or with them in their own processes, none of it is loaded here.
const swarmServices = swarm && ['sharing', 'handoff', 'models'].some((name) => !outOfProcess.has(name))
? await import('../superTabs/inServices.js') : null
let serviceLinksRef: ServiceLinks | null = null
const runtimeTransport = createRuntimeTransport({
call: (service, type, payload, waitMs) => serviceLinksRef?.call(service, type, payload, waitMs) ?? Promise.resolve({ error: 'SERVICE_UNAVAILABLE' }),
})
const screenTransport = createScreenTransport({
call: (service, type, payload, waitMs) => serviceLinksRef?.call(service, type, payload, waitMs) ?? Promise.resolve({ error: 'SERVICE_UNAVAILABLE' }),
})
const screens = createScreens({ handles: isolatedScreen, transport: screenTransport, resolve: id => registry.resolve(id),
inline: (engine, capture) => readerEngine(engine) ? capture === null ? undefined : inline?.screenFor(engine).inspect(capture) : inProcessScreen(engine, capture) })
const submissionTransport = createSubmissionTransport({
call: (service, type, payload, waitMs) => serviceLinksRef?.call(service, type, payload, waitMs) ?? Promise.resolve({ error: 'SERVICE_UNAVAILABLE' }),
})
const submissions = createSubmissions({ policy: submissionPolicy, handles: isolatedSubmission, transport: submissionTransport, resolve: id => registry.resolve(id),
inline: engine => inline?.submissionFor(engine) })
// Codex's shared app-server, spoken to from its worker: core identifies the conversation and decides.
const nativeControls = createNativeControls({
call: (service, type, payload, waitMs) => serviceLinksRef?.call(service, type, payload, waitMs) ?? Promise.resolve({ error: 'SERVICE_UNAVAILABLE' }),
servers: Object.fromEntries(Object.entries(engineLaunches).flatMap(([name, launch]) => 'sharedServer' in launch && launch.sharedServer ? [[name, launch.sharedServer]] : [])),
handles: isolatedNativeControl, inline: engine => isolatedNativeControl(engine) ? undefined : inline?.nativeControlFor(engine),
rows: processRows, home: session => sessionCodexHome(session), argv: argvTokens, readFile: path => readFile(path, 'utf8'),
})
// Which engine workers are linked now: a close's read refused by a restart waits here for the new link.
const engineLinks = createEngineLinks()
const runtimeProfiles = createRuntimeProfiles({
local: new RuntimeProfileState(engine => isolatedRuntime(engine) ? undefined : inline?.runtimeFor(engine), id => registry.resolve(id)),
handles: isolatedRuntime,
resolve: id => registry.resolve(id), transport: runtimeTransport })
const questionControls = createQuestionControls({
handles: isolatedQuestionControl, inline: engine => inline?.questionControlFor(engine), resolve: id => registry.resolve(id),
call: (service, method, payload, waitMs) => serviceLinksRef?.call(service, method, payload, waitMs) ?? Promise.resolve({ error: 'SERVICE_UNAVAILABLE' }),
text: (target, text, allowed) => submitTerminal(target, text, { allowed }), key: keyTerminal,
})
const modelControls = createModelControls({
handles: isolatedModelControl, inline: engine => inline?.modelControlFor(engine), resolve: id => registry.resolve(id),
call: (service, method, payload, waitMs) => serviceLinksRef?.call(service, method, payload, waitMs) ?? Promise.resolve({ error: 'SERVICE_UNAVAILABLE' }),
catalog: session => runtimeProfiles.codexCatalog(session), capture: captureTerminal,
text: (target, text, allowed) => submitTerminal(target, text, { allowed }), key: keyTerminal,
waitForModel: (id, ms) => runtimeProfiles.waitForModel(id, ms), waitForProfile: (id, ms) => runtimeProfiles.waitForProfile(id, ms),
confirmEffort: (id, effort) => runtimeProfiles.confirmEffort(id, effort),
})
// An agent's Model/Effort choices, or every live agent's: what `models_list` answers (services/models.ts)
// and the dial's picker reads, so neither can show a catalog the machine would not honour.
const runtimeModels = (agentId?: string): Promise<RuntimeModelOption[]> => {
if (!agentId) return runtimeProfiles.modelsForSessions(registry.list())
const session = registry.resolve(agentId)
return session ? runtimeProfiles.modelsForSession(session) : Promise.resolve([])
}
// NB: hooks are installed AFTER the hook server binds (below), with the port it actually got — the
// server may fall back to a free port if env.PORT is taken, and the hooks must point at the real one.
// Telling the app and the dial about agents (core/agents/events.ts). The socket is read when each
// frame goes out: until it exists, frames are dropped, and start-up announces every agent again.
const agentEvents = createAgentEvents({
sink: () => backendRef,
terminalAvailable: (agentId) => registry.terminalAvailable(agentId),
resolve: (target) => registry.resolve(target),
stopped: (agentId) => stoppedAgents.get(agentId),
project: (s) => projectFrame(s, runtimeProfiles.selectedModel(s)),
})
const syncSession = agentEvents.syncSession
const announceRename = agentEvents.announceRename
const announceSession = agentEvents.announceSession
// Conversations on this machine that Harness did not start, found where each engine keeps them so
// Cmd-P can find them and open one here; and which sessions a process has open right now. Harness's
// own byproducts (recaps run in its data folder) are never among them.
// The core's one session manager: the backend link, the gateway's dials, the fleet's lane and the dial's
// transcriber all take their tokens from it, so a refresh in flight is shared rather than raced.
const auth = new AuthSessionManager(backendHttpBase())
/** Whether a dial on this computer is watching it, as the devices last said (`clients.dialWatching`). */
let dialWatching = false
/** The last `dial_status` the devices sent the windows: a window that connects afterwards is told it. */
let lastDialStatus: Record<string, unknown> = { attached: false }
/** The local socket, once it exists: the window bridges ask one window through it. */
let localWsServerRef: { sendToWindow(connId: string, frame: { type: string; payload: Record<string, unknown> }): boolean } | null = null
// The core's side of the boundary its services stand on, and the ports it reaches them through (core/api.ts).
// Delivered turns (core/deliveries.ts): text a feature writes into an agent under a delivery id of its
// own, and what becomes of each, told back to whoever made it, in this process or in its own.
// A read-only view of agents' terminals for an experiment's viewers, told to its process (core/terminalWatch.ts).
const terminalWatch = createTerminalWatch({ terminals, resolve: (id) => registry.resolve(id), watchers: new Set(Object.keys(EXPERIMENTS)), moveGate,
tell: (service, viewer, output) => serviceLinksRef?.notify(service, { type: 'service_event', payload: { kind: 'watch', viewer, output } }) ?? false })
const deliveries = createDeliveries({
submit: (agentId, text, deliveryId) => backendRef?.onMessage?.(agentId, text, deliveryId),
cancel: (deliveryId) => backendRef?.onCancelOrchestratorMessage?.(deliveryId) ?? false,
tell: (service, event) => { serviceLinksRef?.notify(service, { type: 'service_event', payload: { kind: 'delivery', event } }, { untilDelivered: true }) },
// The experiments' turns (the orchestrator's first), and Agent Messages' typed messages (core/api.ts).
deliverers: new Set(TURN_DELIVERERS),
})
const ports = emptyPorts()
// The Wi-Fi device's service runs with the dials (services/wifi.ts); what the core reads in line of it
// (who is watching, which transcripts and streams it follows, the focus revision) and the check on every
// answer it sends a device are here (core/wifi.ts). Its doors are the calls it made when it ran here.
const machineIdNow = (): string => backendRef?.machineId ?? ''
const wifiCore = createWifiCore({
port: () => ports.wifi,
gateway: {
device: (connId, type, payload) => backendRef?.deviceFrame(connId, type, payload),
deviceClient: (connId, identity) => backendRef?.deviceClient(connId, identity),
revokeIdentity: (identity) => gatewayOps.revokeIdentity(identity),
},
remoteClient: (connId) => backendRef?.remoteClient(connId) ?? null,
fullText: (agentId) => mirror.lastFullText(registry.byAgent(agentId)?.sessionId ?? agentId),
joined: () => backendRef?.onCommanderJoin?.(),
// Its direct links are the gateway's, started only once it serves: a device they connected to a service
// that could not be built would be answered by nothing.
ready: () => gatewayOps.wifiService(true),
want: () => devicesWake.ask('wifi', 'a Wi-Fi device'),
doors: wifiDoors({
registry, machineId: machineIdNow, displayName: projectDisplayName, running: (sessionId) => turnStartedAt.has(sessionId),
socket: () => backendRef ?? null, deviceInput: () => deviceInput, answer: (request) => cloudAgents?.answer(request) ?? questions.answer(request),
stop: (agentId) => cancelAgent(agentId, true), devices: () => ports.devices,
}),
})
// The cloud agents' doors (core/agents/cloud.ts), handed to the core API now and built once the questions and
// the socket are, below; the cloud service starts after both.
let cloudAgents: CloudAgents | null = null
const cloudDoors: CloudCore = {
publish: (harnesses) => cloudAgents?.doors.publish(harnesses),
ask: (agentId, requestId, question) => cloudAgents?.doors.ask(agentId, requestId, question),
unask: (agentId, requestId) => cloudAgents?.doors.unask(agentId, requestId),
}
const routeSuperTabs = (payload: Record<string, unknown>): Promise<Record<string, unknown>> => new Promise((resolve) => {
const asker = { local: true, owner: true }
if (!(serviceLinksRef?.route('super_tabs', payload, asker, resolve) || serviceHost.route('super_tabs', payload, asker, resolve))) resolve({ error: 'SERVICE_UNAVAILABLE' })
})
// The Swarm's doors in this process, while it is on (superTabs/inCore/): its members here waiting on a person, on the
// devices alone, read only once the questions exist below (the service starts after them); a member's terminal for its
// Lead, read plain and typed under the pane's write lock, built below after the inputs; and the Swarms' cards and Leads'
// recaps for the Harness Pro, on the devices alone, kept whole and shown again to a dial that attaches.
const swarmDoors = swarm && {
waits: swarm.createSuperTabAttention({
send: (frame) => ports.devices?.card(frame),
asking: (agentId) => [...openQuestions.values()].some((asked) => asked.agentId === agentId),
}),
terminal: swarm.createSuperTabTerminal({
resolve: (agentId) => registry.byAgent(agentId),
capture: (session, options) => terminals.capture(session, options),
read: (session, capture) => screens.read(session, capture),
type: typeTerminal,
key: keyTerminal,
locked: (agentId, write) => deviceInput.legacyWrite(agentId, write),
}),
cards: swarm.createSuperTabCards({
swarmCards: (items) => ports.devices?.swarmCards(items),
swarmCardRecap: (recap) => ports.devices?.swarmCardRecap(recap),
request: (payload) => routeSuperTabs(payload),
}),
}
// Shared tabs' relay, a socket per shared tab held by the gateway (gateway/tabRelay.ts), and which of them the core saw
// opened: opened again after a gateway-only restart, closed when Agent Messages' process goes (core/gatewayLink.ts).
const tabRelay = tabRelayOf(() => gatewayOps.tabRelay)
// The prompt of each agent's last turn start: what the one-line summary of a working agent says (turns/summaries.ts).
const turnPrompts = new Map<string, string>()
const nativeTurns = createNativeTurnObservations({ resolve: id => nativeTurnBinding(registry.byAgent(id)) })
/** A Team daemon's purge of an ended confidential member's session data (superTabs/inCore/teamApps.ts); null elsewhere. */
let teamPurge: ((agentId: string) => Promise<Record<string, unknown>>) | null = null
const coreApi = createCoreApi({
nativeTurns: async (agentId, cursor) => nativeTurns.read(agentId, cursor),
cloud: cloudDoors,
...(swarmDoors ? {
superTabs: { attention: (items) => swarmDoors.waits.attention(items), cards: (items) => swarmDoors.cards.cards(items), cardRecap: (recap) => swarmDoors.cards.recap(recap),
// In the core's own process Share was started with it; out of it, the master starts Share's process.
shareObservers: () => { if (outOfProcess.has('sharing')) coreLink.want('sharing') },
screen: (agentId, scrollback) => swarmDoors.terminal.screen(agentId, scrollback),
input: (agentId, text, keys) => swarmDoors.terminal.input(agentId, text, keys),
inputIfScreen: (agentId, keys, screen) => swarmDoors.terminal.inputIfScreen(agentId, keys, screen) },
// The devices' `cardsWanted`, `cardRecap` and `cardOpen`, and no other action of the Super Tab service (superTabs/inCore/cards.ts `ask`).
superTabRequest: (payload) => swarmDoors.cards.ask(payload),
} : {}),
cloudRows: () => (cloudAgents?.dialRows() ?? []) as unknown as RegisteredSession[],
// Agents' terminals: a literal-argv launch, and a read-only view for Share's observers (core/terminalWatch.ts).
terminals: { ...TERMINALS_OFF, ...createTerminalOpener({ createBackend, recoverBackend, registry, announceSession, blocksFolder: (cwd) => !!backendRef?.purgeAgentService?.blocksFolder(cwd), noBackendCode: createUnavailable }), watch: terminalWatch.watch },
dataDir: env.ADAPTER_DATA_DIR,
registry,
stoppedAgents,
databaseHistory,
syncSession,
runtimeModels,
viewerChanged: () => {}, // nothing in the core forwards to a viewer: the viewers follow their own (services/viewers.ts)
viewerFrame: (connId, type, payload) => backendRef?.sendViewerFrame(connId, type, payload) ?? false,
gridNamed: (name) => backendRef?.setHarnessGridName(name),
gridModelsChanged: () => { void backendRef?.pushGridModels() },
privateGridName: async () => backendRef?.gridName() ?? null,
machineName: () => backendRef?.machineName() ?? null,
// An experiment's account-wide settings, and Agent Messages' tabs, signed in by this core.
backend: (method, path, body) => proxyBackend(method, path, body),
onNotice: (listener) => experimentHooks.onNotice(listener),
dshInstallStatus: (status) => backendRef?.send({ type: 'dsh_install_status', payload: status }),
// The recaps' cards and recaps (services/recaps.ts) down the doors they took from here, and a turn's final answer.
turnCard: (frame) => backendRef?.sendCommander(frame), turnSummary: (frame) => backendRef?.send(frame), lastTurn: (sessionId) => readLastTurn(sessionId),
// The backend mints and remembers the account's grid name; this CLI holds neither the account's
// email nor its id. An older backend (no route) answers nothing, which the grid reconcile treats as
// "no grid yet". Bounded so a stalled control-plane connection cannot hold the attempt open.
mintGridName: () => gatewayOps.mintGridName(),
accessToken: (options) => auth.accessToken(options),
// The fleet's lane's sessions are the gateway's, which holds this machine's E2EE identity; it starts
// below, before the devices whose fleet seals through it.
lane: laneOf(() => gatewayOps.lane),
signedIn: () => readAuthSession() !== null,
environment: () => readAuthSession()?.autonomousEnv ?? env.AUTONOMOUS_ENV,
// Built further down, with the account proxies: read when the devices ask, never now.
machines: () => gatewayOps.machines(),
machine: {
id: () => backendRef?.machineId ?? '',
computerId: () => computerId(),
name: () => dialMachineName(),
},
// The dial's working card: what a Claude Code or Codex pane's footer says, read here so the pane never
// leaves the core.
activity: async (agentIds) => activityOf(agentIds, (agentId) => registry.byAgent(agentId), (session) => activityFrameContextRef?.(session) ?? null),
// One line on what each does: the kept prompt, and the latest recap line the dial's recaps read (turns/summaries.ts).
summaries: summaryReader({
live: (agentId) => registry.byAgent(agentId),
state: (session) => activityFrameContextRef?.(session)?.state,
prompts: turnPrompts,
recent: (agentId) => cloudAgents?.recent(agentId) ?? mirror.recent(registry.resolve(agentId)?.sessionId || agentId, 1),
}),
activityText: async (agentId) => {
// A cloud harness says what it is doing on its frame ("Calling Hair Lab").
if (cloudAgents?.owns(agentId)) return cloudAgents.activity(agentId)
const session = registry.resolve(agentId)
if (!session || (session.engine !== 'claude' && session.engine !== 'codex')) return null
const screen = await terminals.capture(session, { mode: 'visible', ansi: false })
return (await screens.read(session, screen.state === 'succeeded' ? screen.value : null))?.activity?.label ?? null
},
// The same footer for a Harness Pro, with its timer beside it (the agent's sentence comes from the cards).
activitySnapshot: async (agentId) => {
if (cloudAgents?.owns(agentId)) {
const text = cloudAgents.activity(agentId)
return text ? { text } : null
}
const session = registry.resolve(agentId)
if (!session || (session.engine !== 'claude' && session.engine !== 'codex')) return null
const screen = await terminals.capture(session, { mode: 'visible', ansi: false })
const activity = (await screens.read(session, screen.state === 'succeeded' ? screen.value : null))?.activity
if (!activity) return null
const elapsedSeconds = elapsedSecondsOf(activity.indicator)
return { text: activity.label, ...(elapsedSeconds !== undefined ? { elapsedSeconds } : {}) }
},
// The devices' frames for the windows on this computer, never the cloud (createCoreApi checks their types).
sendLocal: (frame) => {
if (frame.type === 'dial_status') lastDialStatus = frame.payload
backendRef?.sendLocal(frame)
},
sendToWindow: (connId, frame) => localWsServerRef?.sendToWindow(connId, frame) ?? false,
hasWindow: () => backendRef?.hasLocalClient() ?? false,
devicesChanged: (payload) => backendRef?.send({ type: 'harness_devices_changed', payload }),
wifi: wifiCore.api,
dialWatching: (watching) => {
const attached = watching && !dialWatching
dialWatching = watching
// A dial attaching is shown what is still being asked and what is still working, as a device joining
// through the backend is (onCommanderJoin): one whose devices' process restarted comes back to tiles
// mid-turn, and to a question nobody has answered yet.
// The working tiles are the recaps' to say: asked, and sent to the dial when they answer.
if (attached) for (const frame of openQuestions.values()) ports.devices?.card(frame)
if (attached) void mirror.liveCards().then((cards) => { for (const frame of cards) ports.devices?.card(frame) })
if (attached) for (const frame of cloudAgents?.liveCards() ?? []) ports.devices?.card(frame)
if (attached) swarmDoors?.waits.replay()
if (attached) swarmDoors?.cards.replay()
},
// What a device or another machine asks of an agent here: the SAME handlers the backend socket
// drives, called directly — the slash-command adaptation and the turn and question plumbing live there.
runtimeProfile: (session) => runtimeProfiles.selectedModel(session),
setRuntime: (agentId, model, effort) => {
const s = registry.resolve(agentId)
if (!s || !model) return
void runtimeController.setProfile(s.sessionId || agentId, `runtime-v1:${s.sessionId || agentId}:${s.engine}:${model}@${effort || 'auto'}`)
},
// The window's `agent_create` for an experiment's agents (core/experimentQueries.ts).
create: (request) => createForExperiment(backendRef?.onCreateAgent ?? null, request),
creationStatus: creationId => creationForExperiment(backendRef?.createStatusProvider ?? null, creationId),
// The window's `agent_close`, for the agent cleanup (services/agentCleanup.ts): createCoreApi lets it close only
// a harness another agent started. Read when it closes one, never now: the close service is built further down.
closeAgent: (request) => backendRef?.closeAgentService?.request(request) ?? Promise.resolve({ error: 'UNSUPPORTED' }),
activityAt: (session) => transcriptActivityAt(session.transcriptPath, session.engine),
// The Super Tab host keeps its Leads alive and closes the sessions its backend ends (superTabs/host.ts). Read when it
// asks, never now: the lifecycle is built further down, and one asked before then is refused, and asked again later.
resumeAgent: async (agentId) => lifecycle.resumeAgent(agentId),
// What it may close and reopen is decided in this process, on what its host retains (superTabs/inCore/agents.ts).
...(swarm ? { swarmAgents: (agentDeps) => swarm.createSwarmAgents({ ...agentDeps,
members: { leads: () => swarm.retainedLeads(env.ADAPTER_DATA_DIR), harnesses: () => swarm.retainedHarnesses(env.ADAPTER_DATA_DIR),
sleepingBuddies: () => swarm.retainedSleepingBuddies(env.ADAPTER_DATA_DIR) },
// On a Team daemon, an ended confidential member's session data goes (set below, with the Team daemon's policy).
purgeEnded: async (agentId) => teamPurge ? teamPurge(agentId) : { skipped: true } }) } : {}),
dsh: (session) => backendRef?.dshFrameProvider?.(session) ?? null,
windows: (frame) => backendRef?.sendLocal(frame),
daemon: { command: daemonCommand(), port: env.PORT, machineId: () => backendRef?.machineId ?? '', autonomousEnv: session?.autonomousEnv ?? env.AUTONOMOUS_ENV },
// Share: its observers' frames to the relay, and its welcomes signed by the gateway, which holds the identity.
observer: (connId, type, payload) => backendRef?.sendObserver(connId, type, payload) ?? false,
observerKey: { publicKey: () => gatewayOps.observerKey.publicKey(), signWelcome: (...args) => gatewayOps.observerKey.signWelcome(...args) },
// Shared tabs' rosters signed and their sessions, held by the gateway with the same identity (gateway/tabKey.ts).
tabKey: tabKeyOf(() => gatewayOps.tabKey),
// Their relay, a socket per shared tab, held by the gateway too (gateway/tabRelay.ts).
tabRelay,
// The account's connected services, sealed and opened by the gateway for the connectors service.
connectorVault: { seal: (plaintext) => gatewayOps.connectorVault.seal(plaintext), open: (envelope) => gatewayOps.connectorVault.open(envelope) },
// The same path the window's `agent_fork` takes.
fork: async (agentId) => {
if (!backendRef?.onForkAgent) return { ok: false, error: 'UNSUPPORTED' }
const result = await backendRef.onForkAgent({ agentId, name: null, prompt: null })
return result.ok ? { ok: true, agentId: result.session.agentId } : { ok: false, error: result.error, detail: result.detail }
},
turns: {
send: (agentId, text) => backendRef?.onMessage?.(agentId, text),
stop: (agentId) => backendRef?.onCancel?.(agentId),
recent: async (agentId, n) => cloudAgents?.recent(agentId) ?? mirror.recent(registry.resolve(agentId)?.sessionId || agentId, n),
asks: async (agentId) => mirror.recentAsks(registry.resolve(agentId)?.sessionId || agentId),
...deliveries.turns,
},
questions: {
// The device's own object, verbatim: rebuilt as `{ [requestId]: optionId }` it was keyed by the
// REQUEST id, not the question key `asking.answer` expects, and named a question that does not exist.
answer: (agentId, requestId, answers) => { void (cloudAgents?.answer({ requestId, answers }) ?? asking.answer({ agentId, requestId, answers })) },
answerReviewed: async (answer) => (await (cloudAgents?.answer({ requestId: answer.requestId, answers: answer.answers }) ?? questions.answer({ agentId: answer.agentId, requestId: answer.requestId,
answers: answer.answers, expectedQuestions: answer.questions, selectedLabels: answer.selections, freeTextKeys: answer.freeTextKeys }))).ok,
},
})
// Each service starts and is called through the host, so one that fails is logged and left off and
// the core carries on without it (core/serviceHost.ts).
const serviceHost = createServiceHost(ports, { faults: testFaults(harnessd.HARNESSD_TEST_FAULTS) })
// The DSH companions: each harness agent's viewer and verdict watch (services/viewers.ts), started below.
dshFrameContextRef = (s) => ports.viewers?.frameContext(s) ?? null
// Models (services/models.ts), started below: what an agent's frame says of its grid, from memory.
gridAnnotationRef = (grid) => (ports.models ?? MODELS_OFF).annotation(grid)
const attachDsh = (s: RegisteredSession): void => ports.viewers?.attach(s)
const detachDsh = (agentId: string): void => ports.viewers?.detach(agentId)
// The folders agents work in: branch names and unused worktrees (services/workspaces.ts), started below.
const syncTerminalTitles = async (): Promise<void> => {
ports.workspaces?.nameBranches()
const titles = await terminals.titles()
// The machine's name now, beside every name it has had: a title that is one of them is refused.
machineNames.observe()
// omp titles also come from its session file (sessionTitle.ts ompSessionTitle), so no terminal
// titles at all is not a reason to skip an omp session.
if (titles.size === 0 && !registry.list().some((session) => session.engine === 'omp')) return
for (const session of registry.list()) {
// Codex's own thread name when it has one; otherwise what the engine put on its terminal.
const title = engineSessionTitle(session, terminals.titleFor(session, titles))
if (!title) continue
const before = projectDisplayName(session)
// Fall back to the agent id: a terminal that became an engine harness (e.g. opencode typed
// into a New Terminal) has no engine session id — nothing fired a session-start hook — but its
// pane title is still readable and should still rename the harness.
const updated = registry.updateTitle(session.sessionId || session.agentId, title)
if (!updated) continue
const after = projectDisplayName(updated)
if (after !== before) {
syncSession(updated)
announceRename(updated)
}
}
}
let devicePartsBuilt = false
let appFormWindow: { machineId: string; connId: string } | undefined
let appVoiceFocus: { machineId: string; agentId: string; connId: string } | undefined
let backendRef: BackendSocket | undefined
/** Assigned below, once the grid reconcile exists. A backend (re)connect is the signal that the
* control plane is reachable again, which is precisely what an earlier attempt may have lacked. */
let fullReconcile: (announceDevice?: boolean) => Promise<void> = async () => {}
// The account's machine id when this computer is signed in; its own durable computer id when it is
// not. Both are just "the id this daemon serves under" to everything downstream — the local
// websocket binds clients to it, the app selects by it — and the backend binds a machine to the
// computer id at login, so a sign-in ADOPTS this machine rather than minting a second one.
const autonomousEnv = session?.autonomousEnv ?? env.AUTONOMOUS_ENV
const backend = new BackendSocket(session?.machineId ?? computerId(), (connected) => {
if (!connected) return
const sessions = registry.advertised()
console.log(`[cli] connected · ${sessions.length} agent(s) registered`)
void fullReconcile(true).catch((err) => {
console.error('[runtime-profile] connect reconcile failed:', err instanceof Error ? err.message : err)
})
})
backendRef = backend
// Nothing is answered until start-up is done (see the end of this function).
backend.holdRequests()
// The services harnessd's master runs in their own processes (harnessd/services.ts, `HARNESSD_SERVICES`):
// only under a master, which is what gives this core the token they connect with. Their requests are
// routed to them, and answered SERVICE_UNAVAILABLE while they are down (core/serviceLinks.ts).
const serviceToken = harnessd.HARNESSD_SUPERVISED === '1' ? harnessd.HARNESSD_SERVICE_TOKEN : undefined
const liveFor: LiveFor = (engine) => isolatedLive(engine) ? undefined : inline?.liveFor(engine)
// The relay and its E2EE (gateway/): the backend link, the sessions and the keys, which every remote
// client's frames go through, held at the same gate. In its own process by default (core/gatewayLink.ts),
// or here (gateway/start.ts); the socket hears it through `fromGateway` and speaks to it in the clear.
Object.assign(coreApi.terminals, createTerminalSessions({ agents: coreApi.agents,
paneState: (runtime) => terminals.backendFor(runtime)?.paneState(runtime) ?? Promise.resolve('unknown'),
processState: checkPidRuntime }))
const account = (s = readAuthSession()): GatewayAccount => ({ machineId: s?.machineId ?? null, signIn: signInOf(s?.signInEpoch, s?.signInAcct), autonomousEnv: s?.autonomousEnv ?? env.AUTONOMOUS_ENV })
const engineReaders = createEngineReaders({ isolated: outOfProcess, inline: inline?.engineTranscriptFor,
call: (service, type, payload, waitMs) => serviceLinksRef?.call(service, type, payload, waitMs) ?? Promise.resolve({ error: 'SERVICE_UNAVAILABLE' }) })
const liveTransport = createLiveTransport({
call: (service, type, payload, waitMs) => serviceLinksRef?.call(service, type, payload, waitMs) ?? Promise.resolve({ error: 'SERVICE_UNAVAILABLE' }),
})
const gatewayLink = outOfProcess.has('gateway') ? createGatewayLink({
events: backend.fromGateway,
notify: (frame) => serviceLinksRef?.notify('gateway', frame) ?? false,
notifyBinary: (bytes) => serviceLinksRef?.notifyBinary('gateway', bytes) ?? false,
buffered: () => serviceLinksRef?.buffered('gateway') ?? 0,
call: (type, payload, waitMs) => serviceLinksRef?.call('gateway', type, payload, waitMs) ?? Promise.resolve({ error: 'SERVICE_UNAVAILABLE' }),
start: () => ({ machineId: backend.machineId, computerId: computerId(), autonomousEnv, signedIn: !!session?.machineId, account: account(), machineName: terminalHintMachineName(), hostname: hostname() }),
tokens: auth, backend: (method, path) => proxyBackend(method, path), want: () => coreLink.want('gateway'),
machines: ({ body }) => ports.models?.machines(body, computerId()),
}) : null
const gateway = gatewayLink ?? inline!.startGateway({
events: backend.fromGateway, machineId: backend.machineId, computerId: computerId(), autonomousEnv,
signedIn: !!session?.machineId, tokens: auth, account: account(), machineName: terminalHintMachineName(), hostname: hostname(),
machines: ({ body }) => ports.models?.machines(body, computerId()),
})
backend.useGateway(gateway.port)
// A Harness Team daemon serves no Wi-Fi device: its frames are sealed past the Team guard and its doors reach every agent,
// a Swarm Product Manager's included (security re-check 2 of #2089).
if (teamDaemon) backend.disableWifi()
backend.useWifi(wifiCore.fromGateway)
const gatewayOps = gateway.ops
daemonBoot.openRequests = () => backend.openRequests()
// This machine's viewers, served to a client over its connection by the viewers (core/viewerStreams.ts).
backend.viewerStreams = createViewerStreams(() => ports.viewers, (connId, type, payload) => backend.sendViewerFrame(connId, type, payload))
/**
* Is ANY device surface watching this machine?
*
* Two answers, both real: a device connected through the backend (`hasCommander`), and the dial on the
* USB cable, which reaches this daemon directly over serial and is invisible to the socket that counts
* the others.
*
* This gates the whole device mirror — the "Working…" card and the LLM recap. Reading it as
* backend-only meant a dial plugged into a machine with no WiFi device saw a turn start in its tmux
* pane and then nothing at all: the daemon skipped GENERATING the cards, so there was nothing to send.
*/
// A PLUGGED-IN DIAL IS ALWAYS WATCHING THIS COMPUTER. It used to be gated on the dial having this
// machine selected, because the carousel held one machine's agents at a time; it now holds every
// machine's at once, so this computer's tiles are on screen whichever machine the wheel last landed on
// and skipping the recap here would leave them permanently blank.
/** Agents with a tile open in the desktop window right now. Empty when no window is attached. */
const cleanupTabs = new OpenTabProtection({
machineId: () => backend.machineId,
sessions: () => registry.list(),
readDesk: () => proxyBackend('GET', '/api/desk'),
})
let openPaneAgents = new Set<string>()
/** Whether the window those tiles belong to is actually in front. See onAppPanes. */
let appWindowForeground = true
/** A dial plugged into this computer, as the devices said last (`clients.dialWatching`): kept here so
* the cards are made for it in line, without asking the devices, which may be in another process. */
const cableWatchingLocal = (): boolean => dialWatching
const deviceIsWatching = (): boolean => backend.hasCommander() || cableWatchingLocal() || wifiCore.connected()
/** Anyone who can DRAW a question: a device, a cabled dial, a desktop window on this computer, or an app away
* from this desk (the phone), which is sent it over the relay (core/questions.ts). */
const someoneCanAnswer = (): boolean => deviceIsWatching() || backend.hasLocalClient() || backend.hasRemoteApp()
// A page a program in a harness's pane opens (Claude Code's `/login`) goes to the phone typing there, and the
// sign-in the phone catches comes back to the program (core/terminals/browser.ts, lib/browserShim.ts).
const browser = createBrowser({
agentOfPane: (pane) => registry.list().find((session) => session.tmuxPane === pane)?.agentId,
sendTo: (connId, type, payload) => backend.sendViewerFrame(connId, type, payload),
isLocal: isLocalClientId,
who: (connId) => backend.remoteClient(connId)?.identity ?? connId,
replay: (url) => loopbackGet(url),
now: Date.now,
log: (line) => console.log(line),
})
backend.browserProvider = { open: browser.open, callback: browser.callback }
// The script every pane's BROWSER names asks this daemon first; rewritten as it starts (the CLI may have moved).
writeBrowserShim(daemonCommand())
const terminalStreams = new TerminalStreamManager({
terminals,
resolveAgent: (agentId) => registry.resolve(agentId),
sendTarget: (connId, type, payload) => backend.sendTerminalTo(connId, type, payload),
sendBinaryTarget: (connId, frame) => backend.sendTerminalBinaryTo(connId, frame),
isLoopback: isLocalClientId,
// The Mac owner's apps on a Team daemon running a Swarm Product Manager only watch (superTabs/inCore/teamApps.ts).
watchOnly: (connId) => backend.appWatchOnly(connId),
closedTo: (connId, agentId) => backend.appClosedTo(connId, agentId),
// For a client that did not introduce itself on `terminal_open` (an older build). A loopback
// window can only be this computer's desktop; a paired peer is named by its pairing label unless
// that label is one of the placeholders pairing hands out — those name nothing.
describeClient: (connId) => {
if (isLocalClientId(connId)) return { kind: 'desktop', name: terminalHintMachineName() }
const client = backend.remoteClient(connId)
const label = client?.label
if (!label || GENERIC_PAIR_LABELS.has(label)) return null
return { kind: client.role === 'device' ? 'device' : 'web', name: label }
},
streamingAvailable: terminalBackends.some((backend) => !!backend.openStream),
diagnostic: (event, fields) => console.log(`[terminal-stream] ${event}`, fields),
typingTrace: env.TYPING_TRACE ? (line) => console.log(`[typing] ${line}`) : undefined,
// The keystroke prewarm (grid-reads-without-waking issue 03): typing into a pane whose agent runs on
// a sleeping grid starts that grid while the person types. Here, in the daemon's own input path, so
// an older desktop and typing from a phone get it too; an agent on its own login has no `grid`.
onInput: (agentId, typed, from) => {
// What the person typed restarts the agent's quiet period: one in use is not moved to another host.
if (typed) hostQuiet.noteInput(agentId)
if (typed) browser.typed(agentId, from)
if (typed) nativeTurns.typed(agentId, from.inputContext, from.submitted === true)
const grid = registry.resolve(agentId)?.grid
if (grid) ports.models?.prewarm(grid)
// The person typing into a harness another agent started makes it theirs (services/agentCleanup.ts).
if (typed) ports.agentCleanup?.typed(agentId)
},
moveGate,
})
backend.setTerminalStreamManager(terminalStreams)
// What a harness's pane runs and where, and the desktop's pane colours (core/terminals/requests.ts). A
// theme is applied only for a frame, well after `agentReconciler` below exists (connect() comes last).
const terminalRequests = createTerminalRequests({
resolve: (id) => registry.resolve(id),
paneInfo: (runtime) => terminals.backendFor(runtime)?.paneInfo(runtime) ?? Promise.resolve(null),
applyTheme: (theme) => {
if (theme.background === hostTheme.background && theme.foreground === hostTheme.foreground) return
hostTheme = theme
saveHostTheme(theme)
console.log(`[theme] panes now bg=${theme.background} fg=${theme.foreground}`)
// Existing sessions pick it up on the next scan (TmuxBackend.inventory restyles); nudge one now.
void agentReconciler.trigger()
},
})
backend.terminalInfoProvider = terminalRequests.terminalInfo
backend.themeProvider = terminalRequests.themeSet
// Each session's engine state, in one table (core/transcripts/normalizers.ts).
const normalizers = createSessionNormalizers()
const cursorNormalizers = normalizers.cursorNormalizers
const agyNormalizers = normalizers.agyNormalizers
const commandcodeNormalizers = normalizers.commandcodeNormalizers
const sessionTurnState = normalizers.sessionTurnState
const sessionTurnOpen = normalizers.sessionTurnOpen
const { watcher, live: engineLive } = createLiveWatcher(new Watcher(), {
handles: isolatedLive,
transport: liveTransport,
bySession: (id) => registry.bySession(id),
prepareFrames: (session, frames) => runtimeProfiles.prepareFrames(session, frames),
frame: (session, frame) => ingest.acceptFrame(session.sessionId, session.engine, frame, runtimeProfiles.handles(session.engine)),
reattach: (session) => attachSession(session, true),
hold: (session, reason) => attach.holdInterpretation(session, reason),
})
// Whether a turn is really working, beyond its transcript (core/turns/activity.ts).
const activity = createTurnActivity({
readScreen: screens.read,
terminals,
bySession: (sessionId) => registry.bySession(sessionId),
sessionTurnOpen,
drain: (sessionId) => watcher.pollSession(sessionId),
nativeActivity: (session) => nativeControls.activity(session),
})
const runtimeActivity = activity.runtimeActivity
const turnActivity = activity.turnActivity
activityFrameContextRef = activity.activityFrame
backend.activityFrameProvider = activityFrameContextRef
// The event funnel (core/turns/funnel.ts). Hook registration can race the rest of daemon
// initialization immediately after the localhost server binds: events wait until it is armed below.
const funnel = createEventFunnel({
clients: backend,
// Declared further down: read when a turn aborts, never now.
agentIdFor: (sessionId) => agentIdFor(sessionId),
})
const emitSessionEvents = funnel.emit
const announceTurnAborted = funnel.announceTurnAborted
const cursorDiscovery = createCursorDiscovery(cursorDataDir(), (sessionId, transcriptPath) => {
const existing = registry.bySession(sessionId)
if (!existing || existing.engine !== 'cursor' || existing.transcriptPath === transcriptPath) return
const result = registry.register({
engine: 'cursor',
sessionId,
transcriptPath,
cwd: existing.cwd ?? undefined,
source: existing.source ?? undefined,
runtimes: existing.runtimes,
primaryRuntimeKey: existing.primaryRuntimeKey,
title: existing.title ?? undefined,
model: existing.model ?? undefined,
cliVersion: existing.cliVersion ?? undefined,
processIdentity: existing.processIdentity ?? undefined,
hookEvent: 'TranscriptDiscovered',
})
if (!result) return
// The file is authoritative now. Publishing its binding must not wait for an optional reader.
syncRecapPool()
syncSession(result.entry)
void attachSession(result.entry, false, true).catch((err) => {
console.error('[cursor-discovery] attach failed:', err instanceof Error ? err.message : err)
})
})
// Where an engine's writing becomes live again after a resume or a daemon restart, read by the attach
// that follows (core/transcripts/relaunch.ts).
const relaunchMarks = createRelaunchMarks()
// Following a session: its history read into its engine's normalizer, then its tail
// (core/transcripts/attach.ts).
const attach = createAttach({
setInterpretationHold: registry.setInterpretationHold.bind(registry),
announceSession,
liveFor,
resolve: id => registry.resolve(id),
remoteLive: engineLive,
terminalGone: terminalControl.terminalGone,
normalizers,
watcher,
cursorDiscovery,
device: () => wifiCore.feed,
runtimeProfiles,
captureTerminal,
emit: (sessionId, events, opts) => emitSessionEvents(sessionId, events, opts),
announceTurnAborted,
// Built further down: read when an attach starts watching a pane, never now.
questionWatcher: { start: (sessionId) => questionWatcher.start(sessionId) },
terminalLabel: primaryTerminalLabel,
dbs: { opencode: OPENCODE_DB, kilo: KILO_DB, devin: DEVIN_DB },
devinHome: env.DEVIN_HOME,
hermesDb,
concurrency: ATTACH_CONCURRENCY,
relaunchMarks,
// Built further down: told when an attach finds its last turn already over, never now.
settled: (sessionId) => mirror.settled(sessionId),
})
const attaches = attach.attaches
const attachSession = attach.attachSession
const neverFoldedHistory = attach.neverFoldedHistory
const replayedFirstTurn = attach.replayedFirstTurn
// A conversation's history, a page at a time, and how long it is (core/transcripts/history.ts).
const history = createHistory({ readerFor: engineReaders.forEngine, resolve: (id) => registry.resolve(id), stopped: () => stoppedAgents.list(),
pages: new TranscriptPager(), dbs: { opencode: OPENCODE_DB, kilo: KILO_DB, devin: DEVIN_DB },
hermesDb })
backend.historyProvider = history.sessionGet
backend.sessionsProvider = history.sessionsList
// An agent whose turns keep ending at once has its automatic writes held a while (core/turns/shortTurnGuard.ts).
const shortTurns = createShortTurnGuard({ now: Date.now, log: (line) => console.warn(line) })
// Everything the core writes into a pane, and the device's pane lock (core/input.ts).
const inputs = createInput({
shortTurns,
// The Swarm's chat is queued in the engine's own input while an agent works (superTabs/inCore/deliveries.ts).
...(swarm ? { typesWhileBusy: swarm.typesWhileBusy } : {}),
answersQuestion: deliveries.answersQuestion,
// Built further down: read when a person's message meets an open question, never now.
pendingQuestion: (sessionId) => asking.pendingQuestion(sessionId),
readScreen: screens.read,
submission: submissions,
resolve: (id) => registry.resolve(id),
byAgent: (agentId) => registry.byAgent(agentId),
terminal: terminalControl,
deliveries: {
settled: (event) => deliveries.settled(event),
// Whether Agent Messages still wants one of its typed deliveries written (core/messagesLink.ts).
canWrite: (deliveryId) => deliveries.canWrite(deliveryId) ?? ports.messages?.canWrite(deliveryId) ?? false,
},
device: () => wifiCore.feed,
clients: backend,
// Declared further down: read when an error is reported, never now.
agentIdFor: (sessionId) => agentIdFor(sessionId),
commandcode: (sessionId) => commandcodeNormalizers.get(sessionId),
// Reassigned further down (the funnel): always the current one.
emit: (sessionId, events) => emitSessionEvents(sessionId, events),
// Declared further down: read as a prompt is typed, never now.
promptTyped: (session, capture, screen, inputContext) => {
// A message typed into the pane, from any sender (`harness send`, Agent Messages, the Device): the agent is in use.
hostQuiet.noteInput(session.agentId)
nativeTurns.submitting(session.agentId, inputContext)
if (session.sessionId) questionWatcher.notePrompt(session.sessionId, capture, screen.question)
},
// The person sent a harness text from a window or the phone (services/agentCleanup.ts).
typed: (id) => ports.agentCleanup?.typed(id),
moveGate,
})
const input = inputs.input
const deviceInput = inputs.deviceInput
// agy's turn closed from its pane when its final Stop never comes (core/turns/agyBackstop.ts).
const agyBackstop = createAgyBackstop({
agyNormalizers,
bySession: (sessionId) => registry.bySession(sessionId),
captureTerminal,
drain: (sessionId) => watcher.pollSession(sessionId),
emit: (sessionId, events) => emitSessionEvents(sessionId, events),
})
const clearAgyIdleWatch = agyBackstop.clearAgyIdleWatch
const armAgyIdleWatch = agyBackstop.armAgyIdleWatch
const acquireTerminalControl = inputs.acquireTerminalControl
// Questions an agent asks the person: shown on the dial and the window, answered from anywhere
// (core/questions.ts).
const asking = createQuestions({
questionControlFor: questionControls.forSession,
readQuestion: screens.question,
resolve: (id) => registry.resolve(id),
terminal: terminalControl,
acquireTerminalControl,
clients: backend,
// Declared further down: read when a question is shown, never now.
agentIdFor: (sessionId) => agentIdFor(sessionId),
sessionTurnOpen,
someoneCanAnswer,
deviceInput,
})
const questions = asking.questions
// Cloud harnesses (core/agents/cloud.ts): listed with the rest; their questions shown as the panes' are, and
// answered through the cloud service.
cloudAgents = createCloudAgents({ port: () => ports.cloud, clients: backend, openQuestions: asking.openQuestions, deviceInput })
const cloud = cloudAgents
backend.questionProvider = createQuestionResponse((payload) => cloud.answer(payload) ?? asking.answer(payload))
// An app away from this desk is told what is still being asked as it connects (core/questions.ts).
backend.onRemoteAppJoined = () => asking.reannounceRemote()
const openQuestions = asking.openQuestions
// The agents on this machine (core/agents/list.ts), in the socket's frames, with its monitor readings.
backend.agentsProvider = createAgentList({
registry, stoppedAgents, monitorActivityProvider: asking.monitorActivity, monitorCompletions: backend.monitorCompletions,
toProject: (s) => backend.toProject(s), toStoppedProject: (s) => backend.toStoppedProject(s),
// The monitor's readings, through its port (services/monitor.ts): none while it is off.
harnessResourcesReader: () => (ports.monitor ?? MONITOR_OFF).resources(), harnessStorageReader: (agents, invalidate) => (ports.monitor ?? MONITOR_OFF).storage(agents, invalidate),
cloudFrames: () => cloud.frames(),
}).agentsList
backend.agentGuest = (agentId) => registry.resolve(agentId)?.guest ?? null
// On a Harness Team daemon the account is the Mac's owner's, and another person's Product Manager may run here: the
// owner's own apps never reach the Swarm's confidential sessions, and only watch the rest while one runs (#895).
// Decided once, as it starts: only a Team daemon has it (security review 1 of #2089), and it reads the stopped sessions too.
if (swarm && teamDaemon) {
// The purges still to finish, kept across restarts: the account stays held until each has (superTabs/inCore/teamPurge.ts).
const purges = swarm.purgeRecord(join(env.ADAPTER_DATA_DIR, 'super-tabs', 'team-purges.json'))
const policy = swarm.teamAppPolicyFor(env.ADAPTER_DATA_DIR, () => coreApi.daemon.machineId(), () => registry.list(), () => stoppedAgents.list(), purges)
backend.remoteAppPolicy = policy
// What it doesn't finish is tried again, here and after a restart (superTabs/inCore/teamPurge.ts withPurgeRetries).
const purgeSessions = () => ({ live: registry.list(), stopped: stoppedAgents.list() })
teamPurge = swarm.withPurgeRetries(swarm.createConfidentialPurge({ sessions: purgeSessions, confidential: (agentId) => policy.isConfidential(agentId), home: homedir(), record: purges,
session: (agentId) => registry.byAgent(agentId) ?? stoppedAgents.get(agentId),
purge: async (request) => backend.purgeAgentService ? await backend.purgeAgentService.request(request as never) : { error: 'UNSUPPORTED' } }),
{ record: purges, sessions: purgeSessions, report: swarm.teamPurgeReport(), log: (line) => console.warn(`[super-tabs] ${line}`) })
}
const questionWatcher = asking.questionWatcher
// The turn's last text, for its recap, whatever the engine (core/transcripts/lastTurn.ts).
const readLastTurn = createLastTurnReader({
readerFor: engineReaders.forEngine,
bySession: (sessionId) => registry.bySession(sessionId),
dbs: { opencode: OPENCODE_DB, kilo: KILO_DB, devin: DEVIN_DB },
hermesDb,
})
// Recaps: turn cards, notifications, cut by the recaps (services/recaps.ts) from the lifecycle the core tells (core/turns/recaps.ts).
const recaps = createRecaps({
port: () => ports.recaps, turnActivity, clients: backend, deviceIsWatching, cableWatchingLocal, sessionTurnOpen,
remoteApp: () => backend.hasRemoteApp(),
bySession: (sessionId) => registry.bySession(sessionId), resolve: (id) => registry.resolve(id), live: () => registry.list(),
stopped: (agentId) => stoppedAgents.get(agentId),
orchestratorRoleOf: (agentId) => ports.orchestrator?.roleOf(agentId) ?? null,
quietOnDevices: (session) => swarm?.quietOnDevices(session) ?? false,
})
asking.hearQuestions(recaps.question) // a turn waiting on the person is not announced as done
const isSubagentSession = recaps.isSubagentSession
const mirror = recaps.mirror
// Recaps are STORED under the engine session id — that is what lets `--resume` bring the last recap
// back under a brand-new agent — but they are ASKED FOR by agent id, which is the only id the device
// and the voice router know. Resolve across the two, or every tile restores empty.
backend.agentRecentProvider = recaps.agentRecent
// Quiet-machine QA: the edge host renders Change agent's handoff from these conversation reads.
// Build discovery once to keep "one search per agent" across requests.
coreApi.conversations = conversationReads(createHandoffDependencies({
registry,
stopped: {
get: (id) => stoppedAgents.get(id),
// Every saved record, readable or not (the store's own `list()` skips an unreadable one), so ownership fails closed.
ids: () => stoppedAgents.ids(),
},
mirror,
databaseHistory,
findLiveSession,
processSession: processSessionOf,
isRecentlyDeleted,
findResumedTranscript,
validTranscriptPath,
}, env.ADAPTER_DATA_DIR))
// The requests each service that can run in its own process answers, as core/api.ts declares them.
const requestsOf: Record<string, readonly string[]> = {
search: SEARCH_REQUESTS, store: STORE_REQUESTS, usage: USAGE_REQUESTS, monitor: MONITOR_REQUESTS, projects: PROJECTS_REQUESTS, models: MODELS_REQUESTS, handoff: HANDOFF_REQUESTS, connectors: CONNECTORS_REQUESTS, sharedMachines: SHARED_MACHINES_REQUESTS,
devices: DEVICES_REQUESTS, windowNames: WINDOW_NAMES_REQUESTS, shell: SHELL_REQUESTS, messages: MESSAGES_REQUESTS, osDevice: OS_DEVICE_REQUESTS, machineAddons: MACHINE_ADDON_REQUESTS,
...Object.fromEntries(Object.entries(EXPERIMENTS).map(([name, experiment]) => [name, experiment.requests])),
}
// The experiments (core/api.ts `EXPERIMENTS`): each may act on the core through the hooks an experiment has.
const experiments = new Set(Object.keys(EXPERIMENTS))
// What the core keeps of the orchestrator in its own process: each agent's role, and which frames are its
// Directors' (core/orchestratorLink.ts).
const orchestratorLink = createOrchestratorLink((frame) => serviceLinks.notify('orchestrator', frame))
// What the core keeps of the viewers in their own process, for the frames it builds (core/viewersLink.ts).
const viewersLink = createViewersLink(coreApi, (frame, opts) => serviceLinks.notify('viewers', frame, opts),
{ call: (type, payload, waitMs) => serviceLinks.call('viewers', type, payload, waitMs), buffered: () => serviceLinks.buffered('viewers') },
{ wake: (why) => viewersWake.ask('viewers', why) })
// How the core tells workspaces in their own process what to do, and answers them (core/workspacesLink.ts).
const workspacesLink = createWorkspacesLink(coreApi, (frame) => serviceLinks.notify('workspaces', frame), forgetAgentProject)
// Agent Messages in its own process: which of its deliveries may be written, as it last said, and what it may ask
// and hear of the core (core/messagesLink.ts).
// A roster change it tells (`observers`) goes to Share: to its process, which a call starts while it is off, or to its
// handler in this one.
const messagesLink = createMessagesLink({ core: coreApi, notify: (frame) => serviceLinks.notify('messages', frame),
share: (type, payload) => outOfProcess.has('sharing') ? serviceLinks.call('sharing', type, payload)
: new Promise((resolve) => { if (!serviceHost.route(type, payload, { local: true, owner: true }, resolve)) resolve({ error: 'SERVICE_UNAVAILABLE' }) }) })
// An experiment asked for, and the account's notices for those that hear them (core/experiments.ts).
const experimentHooks = createExperimentHooks({ want: (service) => coreLink.want(service), notify: (service, frame) => serviceLinks.notify(service, frame),
outOfProcess, experiments })
backend.onAccountNotice = (notice) => {
experimentHooks.notice(notice)
// Agent Messages reads its tabs again at `desk_changed`: told here in its own process, heard through
// `account.onNotice` in this one.
messagesLink.notice(notice)
// The connectors service merges the account's sealed connections again (services/connectors.ts); in
// the core's process it hears this through `account.onNotice` like any listener.
// A device key added or confirmed (`device_keys_changed`) may be a machine to seal them for as well.
if ((notice.type === 'connectors_changed' || notice.type === 'device_keys_changed') && outOfProcess.has('connectors')) {
serviceLinks.notify('connectors', { type: 'service_event', payload: { kind: 'notice', notice } })
}
// Shared machines read who uses this machine, and which machines are shared with this account, again
// (services/sharedMachines.ts): someone added it, or the sharing of one changed.
if (notice.type === 'machines_changed' && outOfProcess.has('sharedMachines')) {
serviceLinks.notify('sharedMachines', { type: 'service_event', payload: { kind: 'notice', notice } })
}
// The devices' fleet reads the machine list on `machines_changed` (services/fleet.ts); in its own process it hears it
// only through this (services/devicesProcess.ts), in the core's through `account.onNotice`.
if (notice.type === 'machines_changed' && outOfProcess.has('devices')) {
serviceLinks.notify('devices', { type: 'service_event', payload: { kind: 'notice', notice } })
}
}
// What shared machines in their own process reach through the core: this machine's sharing on the
// backend, signed in here, and the gateway's trust stores (core/sharedMachinesQueries.ts).
const sharedMachinesAccount = {
backend: coreApi.account.backend, machineId: () => coreApi.daemon.machineId(),
trust: (desired: Parameters<typeof gatewayOps.sharedTrust>[0]) => gatewayOps.sharedTrust(desired),
}
// What a shared tab's relay said: a close the core forgets the tab for (core/gatewayLink.ts `tabRelayOf`), and every
// frame for Agent Messages, in its own process or in this one (core/messagesLink.ts).
backend.onTabFrame = (event) => { tabRelay.heard(event); messagesLink.tabFrame(event) }
// What the Store in its own process tells the core: an install's progress, and that what is installed changed (core/storeLink.ts).
const storeLink = createStoreLink(coreApi, invalidateInstalledDsh, (type, payload) => serviceLinks.call('store', type, payload))
storeLink.onReady(() => { void heldLaunches.restoreHeld('store') })
// What the core keeps of models in its own process for frames and keystrokes, and how it asks it the rest (core/modelsLink.ts).
const modelsLink = createModelsLink(coreApi, (type, payload) => serviceLinks.call('models', type, payload), (frame) => serviceLinks.notify('models', frame))
// The devices in their own process (core/devicesLink.ts): told what the windows say, asked ⌘K, and told it
// all again whenever they connect, from what the core keeps.
const devicesLink = createDevicesLink({
core: coreApi,
notify: (frame) => serviceLinks.notify('devices', frame),
call: (type, payload, waitMs) => serviceLinks.call('devices', type, payload, waitMs),
state: () => ({ desk: appPaneAgents, foreground: appWindowForeground, swarms: appSwarmsLatest, unread: appUnreadLatest,
focus: windowFocus(), engines: registry.active().map((agent) => agent.engine), commanders: backend.hasCommander() }),
})
// The Wi-Fi device in the devices' process (core/wifiLink.ts): its sessions' requests and what the agents do,
// in order; on each connection, what the core holds for it (core/wifi.ts).
const wifiLink = createWifiLink({
core: coreApi,
notify: (frame) => serviceLinks.notify('wifi', frame),
call: (type, payload, waitMs) => serviceLinks.call('wifi', type, payload, waitMs),
})
// Its port from the start: its process connects as soon as the socket answers, before the rest of the
// core is wired, and is resumed through this port then (core/wifi.ts `started`).
if (outOfProcess.has('wifi')) ports.wifi = wifiLink.port
// What the core tells the recaps in their own process, and reads back from what they said (core/recapsLink.ts).
const recapsLink = createRecapsLink({ notify: (frame, opts) => serviceLinks.notify('recaps', frame, opts), buffered: () => serviceLinks.buffered('recaps'),
call: (type, payload) => serviceLinks.call('recaps', type, payload), clients: coreApi.clients, lastTurn: coreApi.transcripts.lastTurn })
// What the core tells the agent cleanup in its own process, and answers it (core/agentCleanupLink.ts).
const agentCleanupLink = createAgentCleanupLink(coreApi, (frame, opts) => serviceLinks.notify('agentCleanup', frame, opts))
const usageLink = createUsageLink({ call: payload => ports.usage?.read(payload.target as AgentUsageTarget) ?? Promise.resolve({}), changed: agentEvents.onTokenUsageChanged })
const serviceLinks = createServiceLinks({
token: serviceToken,
owned: Object.fromEntries([...outOfProcess].map((name) => [name, requestsOf[name] ?? []])),
waits: LONG_ANSWERS,
// An experiment's process runs once on, the devices' once there is one, models', the gateway's and the viewers'
// once needed: a request asks. Shell and Agent Messages are in the always-running edge host, but a first request
// can beat that host's connection. Hold it through the same bounded startup gate; after any disconnect, fail
// promptly as before. Under a master from before, Agent Messages' own process starts at its first request this way.
onDemand: new Set([...experiments, ...DEVICES_ON_DEMAND, ...VIEWERS_ON_DEMAND, ...Object.values(READER_SERVICES), 'models', 'gateway', 'shell', 'messages']),
// But the Store's requests wait through its process's restart too: a window's Store list was answered unavailable
// while the master restarted the viewers (core/serviceLinks.ts `waitsThroughRestart`).
waitsThroughRestart: new Set(['store']),
want: (service) => experimentHooks.want(service),
// The gateway's first: its `backend` reads (the device key log) were refused below as NOT_AN_EXPERIMENT.
answer: async (service, query, payload, authority) => await questionControls.answer(service, query, payload) ?? await modelControls.answer(service, query, payload) ?? await nativeControls.answer(service, query, payload) ?? engineReaders.answer(service) ?? (service === 'gateway' && gatewayLink ? gatewayLink.answer(query, payload) : null) ?? deliveries.answer(service, query, payload)
// Agent Messages is answered what it uses and nothing more, never what an experiment may ask (core/messagesLink.ts).
?? (service === 'messages' ? await messagesLink.answer(query, payload) : null)
?? await answerConnectorsQuery(coreApi, service, query, payload)
?? await answerSharedMachinesQuery(sharedMachinesAccount, service, query, payload)
?? answerMachineAddonsQuery(coreApi, service, query)
?? await answerExperimentQuery(coreApi, experiments, service, query, payload)
?? await terminalWatch.answer(service, query, payload)
?? (service === 'orchestrator' ? orchestratorLink.answer(query, payload) : null)
?? (service === 'viewers' ? viewersLink.answer(query, payload)
: service === 'workspaces' ? workspacesLink.answer(query, payload)
: service === 'store' ? storeLink.answer(query, payload)
: service === 'models' ? modelsLink.answer(query, payload)
: service === 'devices' ? devicesLink.answer(query, payload)
: service === 'wifi' ? wifiLink.answer(query, payload)
: service === 'handoff' ? answerConversationQuery(coreApi, query, payload, authority)
: service === 'shell' ? answerShellQuery(coreApi, query, payload)
: service === 'agentCleanup' ? agentCleanupLink.answer(query, payload)
: service === 'recaps' ? recapsLink.answer(query, payload) : answerAgentQuery(coreApi, query, payload)),
// The gateway's own traffic: its remote clients and what they sent, and its comings and goings; and what
// the devices tell the core (a turn, a frame for the windows, a dial on the wire); a viewer stream's answers.
notice: (service, payload) => { if (service === 'gateway') gatewayLink?.notice(payload); else if (service === 'devices') devicesLink.notice(payload); else if (service === 'wifi') wifiLink.notice(payload); else if (service === 'viewers') viewersLink.notice(payload); else if (service === 'recaps') recapsLink.notice(payload) },
binary: (service, bytes) => { if (service === 'gateway') gatewayLink?.binary(bytes) },
connected: (service) => {
engineReaders.connected(service)
liveTransport.connected(service)
runtimeTransport.connected(service)
screenTransport.connected(service)
submissionTransport.connected(service)
nativeControls.connected(service)
engineLinks.connected(service)
modelControls.connected(service)
questionControls.connected(service)
if (service === 'search') { searchGeneration++; externalResumes?.wake() }
if (service === 'usage') usageLink.connected()
// The gateway first hears what it starts from, then the shared tabs it held before a restart.
if (service === 'gateway') { gatewayLink?.connected(); tabRelay.connected() }
if (service === 'devices') devicesLink.connected()
if (service === 'superTabs') swarmDoors?.cards.serviceUp()
if (service === 'wifi') wifiCore.started(appVoiceFocus ?? null)
if (service === 'viewers') viewersLink.connected()
devicesWake.connected(service)
viewersWake.connected(service)
// A service up again (or up at last): the agents held for it are launched (core/agents/heldLaunches.ts).
void heldLaunches.restoreHeld(service)
},
disconnected: (service) => {
if (service === 'search') searchGeneration++
if (service === 'usage') usageLink.disconnected()
engineReaders.disconnected(service)
liveTransport.disconnected(service)
runtimeTransport.disconnected(service)
screenTransport.disconnected(service)
submissionTransport.disconnected(service)
nativeControls.disconnected(service)
engineLinks.disconnected(service)
modelControls.disconnected(service)
questionControls.disconnected(service)
if (service === 'gateway') gatewayLink?.disconnected()
// Agent Messages' process went: its tabs' sockets have no one to hear them, and it opens them again as it starts.
if (service === 'messages') tabRelay.closeOpened()
if (service === 'devices') { devicesLink.disconnected(); swarmDoors?.cards.devicesGone() }
if (service === 'wifi') wifiCore.stopped()
if (service === 'recaps') recapsLink.disconnected()
void terminalWatch.gone(service)
},
})
serviceLinksRef = serviceLinks
// A request a service declared goes to it: in its own process, or in this one (core/serviceHost.ts).
backend.serviceRouter = (type, payload, asker, reply) => serviceLinks.route(type, payload, asker, reply) || serviceHost.route(type, payload, asker, reply)
// The connection that asked closed: the services abort what it asked, wherever they run.
backend.onConnectionClosed = (connId) => { serviceLinks.closeConnection(connId); serviceHost.closeConnection(connId) }
// Session search (services/search.ts): in this process, or in its own (services/searchProcess.ts),
// where the core tells it what changed. A purge's forgetting waits for it if it is down.
if (outOfProcess.has('search')) {
ports.search = {
inspect: async request => externalSessionAnswer(await serviceLinks.call('search', 'external_inspect', { ...request }, 4_000), request),
touch: (sessionId) => { serviceLinks.notify('search', { type: 'service_event', payload: { kind: 'touch', sessionId } }) },
deleteHistory: (sessionId) => { serviceLinks.notify('search', { type: 'service_event', payload: { kind: 'deleteHistory', sessionId } }, { untilDelivered: true }) },
session: () => undefined,
stop: () => {},
}
} else {
serviceHost.start('search', inline!.startSearch, coreApi, SEARCH_FALLBACKS, SEARCH_REQUESTS)
}
// What the core calls search through: guarded, so it answers its fallbacks once search is switched off.
const sessionSearch = ports.search
// The DSH viewers: in this process, or in its own (services/viewersProcess.ts), told of each agent.
if (outOfProcess.has('viewers')) ports.viewers = viewersLink.port
else serviceHost.start('viewers', inline!.startViewers, coreApi, VIEWERS_FALLBACKS)
// Workspaces: in this process, or in the edge host (services/workspacesProcess.ts), told what to do and when.
if (outOfProcess.has('workspaces')) ports.workspaces = workspacesLink.port
else serviceHost.start('workspaces', inline!.startWorkspaces, coreApi, WORKSPACES_FALLBACKS)
// The orchestrator, an experiment (services/orchestrator.ts): in this process, or in its own once it is on,
// as the core sees it there (core/orchestratorLink.ts). It reads its Directors' turns from the frames sent.
if (outOfProcess.has('orchestrator')) ports.orchestrator = orchestratorLink.port
else serviceHost.start('orchestrator', inline!.startOrchestrator, coreApi, ORCHESTRATOR_FALLBACKS, ORCHESTRATOR_REQUESTS)
// Cloud agents, an experiment (services/cloud.ts): in its own process once it is on, asked through its port
// (core/cloudLink.ts), which starts it; or in this one behind the service host's guard.
if (outOfProcess.has('cloud')) ports.cloud = createCloudLink((type, payload) => serviceLinks.call('cloud', type, payload))
else serviceHost.start('cloud', inline!.startCloud, coreApi, CLOUD_FALLBACKS, CLOUD_REQUESTS)
backend.onFrameSent = (frame) => ports.orchestrator?.frame(frame)
// Share (services/sharing.ts): in this process, or in its own once it is on (core/sharingLink.ts). Its
// observers' frames reach it as the relay hands them over.
if (outOfProcess.has('sharing')) ports.sharing = createSharingLink({ call: (type, payload) => serviceLinks.call('sharing', type, payload), notify: (frame) => serviceLinks.notify('sharing', frame) })
else serviceHost.start('sharing', (core, given) => inline!.startSharing(core, given, swarmServices ? { observers: swarmServices.observerSource } : {}), coreApi, SHARING_FALLBACKS, SHARE_REQUESTS)
backend.observers = { receive: (connId, type, payload) => ports.sharing?.observer(connId, type, payload), closeAll: () => ports.sharing?.linkDown() }
// Agent Messages (services/messages.ts): in the edge host, or in this process behind the service host's guard (a
// fault there costs no message its write).
if (outOfProcess.has('messages')) ports.messages = messagesLink.port
// In this process it hears its shared tabs' frames from the same listeners the socket's `onTabFrame` feeds.
else serviceHost.start('messages', (core, started) => inline!.startMessagesInCore(core, started, { onTabFrame: messagesLink.onTabFrame,
observers: () => { void Promise.resolve(messagesLink.answer('observers', {})).catch(() => {}) } }), coreApi, MESSAGES_FALLBACKS, MESSAGES_REQUESTS)
// The harnesses installed here, and installing, updating and removing one (services/store.ts): in this
// process, or beside the viewers in theirs (services/storeProcess.ts).
if (outOfProcess.has('store')) ports.store = storeLink.port
else serviceHost.start('store', (core, installedPorts) => inline!.startStoreInCore(core, installedPorts, () => { void heldLaunches.restoreHeld('store') }), coreApi, STORE_FALLBACKS, STORE_REQUESTS)
// This machine's Claude and Codex rate limits, read with its own credentials (services/usage.ts): in this
// process, or in the edge host (services/usageProcess.ts).
if (outOfProcess.has('usage')) ports.usage = { read: target => serviceLinks.call('usage', 'agentUsage', { target }), stop: () => {} }
else serviceHost.start('usage', inline!.startUsageInCore, coreApi, USAGE_FALLBACKS, USAGE_REQUESTS)
usagePortRef = usageLink.port
backend.tokenUsageProvider = target => usageLink.port.get(target)
coreApi.usage = target => usageLink.readSnapshot(target, coreApi.agents.all())
coreApi.usageFresh = async (agentId) => {
const row = registry.byAgent(agentId)
const target = row && usageTarget(row)
if (!target || !validUsageTarget(target)) return null
const answer = await ports.usage?.read(target)
return answer && validUsage(answer.value) ? answer.value : null
}
// This machine's and each agent's resources, for the Monitor and the list's readings (services/monitor.ts):
// in this process, or in the edge host (services/monitorProcess.ts), asked through its port (core/monitorLink.ts).
if (outOfProcess.has('monitor')) ports.monitor = createMonitorLink((type, payload) => serviceLinks.call('monitor', type, payload))
else serviceHost.start('monitor', inline!.startMonitor, coreApi, MONITOR_FALLBACKS, MONITOR_REQUESTS)
// An agent's branch and pull request, a project's repository and preview, a folder's subfolders and a
// media file from an agent's project (services/projects.ts), and a window's name (services/windowNames.ts):
// in this process, or in the edge host.
if (!outOfProcess.has('projects')) serviceHost.serve('projects', inline!.startProjects, coreApi, PROJECTS_REQUESTS)
if (!outOfProcess.has('windowNames')) serviceHost.serve('windowNames', inline!.startWindowNames, coreApi, WINDOW_NAMES_REQUESTS)
if (!outOfProcess.has('memory')) serviceHost.serve('memory', inline!.startMemory, coreApi, MEMORY_REQUESTS)
if (!outOfProcess.has('router')) serviceHost.serve('router', inline!.startRouter, coreApi, ROUTER_REQUESTS)
if (!swarm) serviceHost.leaveOff('superTabs', SUPER_TAB_REQUESTS)
else if (!outOfProcess.has('superTabs')) serviceHost.start('superTabs', swarm.startSuperTabs, coreApi, SUPER_TAB_FALLBACKS, SUPER_TAB_REQUESTS)
if (!outOfProcess.has('handoff')) serviceHost.serve('handoff', (core) => inline!.startHandoff(core, undefined, undefined, swarmServices?.recordReplacement), coreApi, HANDOFF_REQUESTS)
// Connected services' MCP bridge and the Connectors screen (services/connectors.ts): here, or in the edge host.
if (!outOfProcess.has('connectors')) serviceHost.serve('connectors', inline!.startConnectors, coreApi, CONNECTORS_REQUESTS)
// Sharing this machine with other accounts, and the machines shared with this one (services/sharedMachines.ts).
// Its port builds a guest's harness (core/agents/guestCreate.ts), asked of the edge host (core/sharedMachinesLink.ts).
if (outOfProcess.has('sharedMachines')) ports.sharedMachines = createSharedMachinesLink((type, payload) => serviceLinks.call('sharedMachines', type, payload))
else serviceHost.start('sharedMachines', (core, staged) => inline!.startSharedMachines(core,
{ port: inlineSharedMachinesPort(sharedMachinesAccount, core.account.signedIn()), ports: staged }), coreApi, SHARED_MACHINES_FALLBACKS, SHARED_MACHINES_REQUESTS)
// A Harness OS computer managed from the owner's phone: its update and its Wi-Fi (services/osDevice.ts): here, or in the edge host.
if (!outOfProcess.has('osDevice')) serviceHost.serve('osDevice', inline!.startOsDevice, coreApi, OS_DEVICE_REQUESTS)
// Add-ons of a device that is this machine (services/machineAddons.ts, openharness#1654): here, or in the edge host.
if (!outOfProcess.has('machineAddons')) serviceHost.serve('machineAddons', inline!.startMachineAddons, coreApi, MACHINE_ADDON_REQUESTS)
// The recaps: in this process, or in the edge host (services/recapsProcess.ts), told each turn's lifecycle.
if (outOfProcess.has('recaps')) ports.recaps = recapsLink.port; else serviceHost.start('recaps', inline!.startRecaps, coreApi, RECAPS_FALLBACKS)
// Cleaning up after agents: the harnesses a closed harness started, and those idle half an hour (services/agentCleanup.ts).
if (outOfProcess.has('agentCleanup')) ports.agentCleanup = agentCleanupLink.port; else serviceHost.start('agentCleanup', (core, given) => inline!.startAgentCleanup(core, given, swarm ? { retained: swarm.retainedHarnesses, closed: swarm.recordCleanupClose } : undefined), coreApi, AGENT_CLEANUP_FALLBACKS)
if (!outOfProcess.has('shell')) serviceHost.serve('shell', inline!.startShell, coreApi, SHELL_REQUESTS)
// Models: grid access and its pin, the model pictures on agents' frames, the keystroke prewarm, where an
// agent on a grid model sends its inference, and the models requests the apps send (services/models.ts):
// in this process, or in its own (services/modelsProcess.ts), reached through core/modelsLink.ts.
if (outOfProcess.has('models')) ports.models = modelsLink.port
else serviceHost.start('models', (core, given) => inline!.startModels(core, given, swarmServices ?? undefined), coreApi, MODELS_FALLBACKS, MODELS_REQUESTS)
// What the socket asks of models: read on each use, so a models service switched off answers its fallbacks.
backend.models = () => ports.models ?? MODELS_OFF
const runtimeController = new RuntimeProfileController({
modelControlFor: modelControls.forSession,
readScreen: screens.read,
manager: runtimeProfiles,
getSession: (id) => registry.resolve(id),
validateRuntime: validateTerminal,
capture: captureTerminal,
sendText: submitTerminal,
sendLiteral: typeTerminal,
sendKey: keyTerminal,
// The /model picker waits out a move to another host rather than answer BUSY (hostMove/gate.ts).
acquireInput: (id) => acquireAfterHold(moveGate, registry.resolve(id)?.agentId ?? id, () => acquireTerminalControl(id)),
})
/**
* Engine session id → the agent that owns it. The event stream speaks in ENGINE session ids while
* anything the user addresses (input queue, control lock, every outbound frame) belongs to the AGENT,
* which outlives the session it is currently bound to.
*/
const agentIdFor = (sessionId: string): string => registry.bySession(sessionId)?.agentId ?? sessionId
backend.runtimeProfileProvider = (session) => runtimeProfiles.selectedModel(session)
backend.dshFrameProvider = (s) => ports.viewers?.frameContext(s) ?? null
// `harness remote` names the tile it was typed in by its pane; the registry knows whose it is (lib/terminalHandoff.ts).
backend.onTerminalHandoff = (pane) => handoffAgentId(registry.advertised(), pane)
// A rename, a model and effort, or an app opening an agent (core/agents/update.ts).
const agentUpdate = createAgentUpdate({
registry, clients: backend, toProject: (s) => backend.toProject(s), closeAgentService: () => backend.closeAgentService,
onAgentRename: (session, name) => { void terminals.setTitle(session, name) },
onRuntimeProfileUpdate: (sessionId, selectedModel) => runtimeController.setProfile(sessionId, selectedModel),
}).agentUpdate
// A cloud harness is no registry row: its rename goes to the cloud service (core/agents/cloud.ts).
backend.agentUpdateProvider = async (payload, reply) => {
const cloud = cloudAgents?.update(payload)
if (cloud) reply(await cloud)
else await agentUpdate(payload, reply)
}
runtimeProfiles.onChanged = (sessionId) => {
const session = registry.resolve(sessionId)
if (session) syncSession(session)
}
// Turn heartbeats (core/turns/heartbeats.ts).
const turnBeats = createHeartbeats({
bySession: (sessionId) => registry.bySession(sessionId),
sessionTurnOpen,
agentIdFor,
runtimeActivity,
turnActivity,
mirror,
clients: backend,
})
const heartbeats = turnBeats.heartbeats
const turnStartedAt = turnBeats.turnStartedAt
const stopHeartbeat = turnBeats.stopHeartbeat
const startHeartbeat = turnBeats.startHeartbeat
// Everything the funnel feeds exists now: install it, and deliver what waited.
funnel.arm({
bySession: (sessionId) => registry.bySession(sessionId),
tokenUsage: { changed: target => usageLink.port.changed(target) },
agentIdFor,
turnActivity,
isSubagentSession,
clients: backend,
search: sessionSearch,
turnStartedAt,
prompts: turnPrompts,
nativeTurns,
input,
deviceInput,
submission: submissions,
device: () => wifiCore.feed,
startHeartbeat,
questionWatcher,
mirror,
// A live turn, however short and with no input of its own (a /loop wake-up, a background notification), restarts
// the agent's quiet period: the mover's ticks alone, seconds apart, would miss it.
working: (agentId) => hostQuiet.noteActivity(agentId, 'working'),
shortTurns,
})
// Cursor's Task hooks and the sub-agents they start (core/engines/cursorTasks.ts).
const cursorTasks = createCursorTaskHooks({ emitSessionEvents, watcher, registry, cursorNormalizers })
const cursorSubagents = cursorTasks.cursorSubagents
const cursorTaskHooks = cursorTasks.cursorTaskHooks
const onCursorTaskStart = cursorTasks.onCursorTaskStart
// Release a session's binding, or remove a process-owned agent everywhere (core/agents/forget.ts).
// One owner per conversation, stopped harnesses included; the conversations claimed twice so far settle now.
const conversationOwners = createConversationOwners({ stoppedAgents, live: () => registry.list(), clients: backend, reservationMs: RESUME_READINESS_BUDGET_MS })
conversationOwners.settle()
const forgetSession = createForgetSession({
owners: conversationOwners,
shortTurns,
forgetAttach: attach.forget,
onRemoved: (agentId) => forgetRestartRevision(agentId),
relaunchMarks,
registry,
stoppedAgents,
syncRecapPool,
normalizers,
turnStartedAt,
prompts: turnPrompts,
neverFoldedHistory,
replayedFirstTurn,
clearAgyIdleWatch,
cursorDiscovery,
cursorSubagents,
runtimeProfiles,
watcher,
stopHeartbeat,
input,
deviceInput,
detachDsh,
mirror,
clients: backend,
dataDir: env.ADAPTER_DATA_DIR,
})
const retainExitedSession = createRetainExitedSession({
forgetRelaunch: relaunchMarks.forget,
stoppedAgents,
registry,
send: frame => backend.send(frame),
publishStoppedAgent: saved => backend.publishStoppedAgent(saved),
// A terminal is never the dial's business, and `syncSession` forces that for it anyway.
announceSession: session => announceSession(session, { device: false }),
invalidateTerminalControl,
forgetInput: agentId => { forgetRestartRevision(agentId); input.forget(agentId); deviceInput.forget(agentId) },
detachDsh,
syncRecapPool,
warn: (message, error) => console.warn(message, error),
})
const keepAbandonedConversation = createKeepAbandonedConversation({ stoppedAgents, publishStoppedAgent: (saved) => backend.publishStoppedAgent(saved) })
// Binding a session to its agent, and a running process to its session (core/agents/bind.ts).
const binding = createBinding({
owners: conversationOwners,
registry,
mirror,
forgetSession,
clients: backend,
attachSession,
announceSession,
stoppedAgents,
syncRecapPool,
input,
deviceInput,
homes: { copilot: env.COPILOT_HOME, grok: env.GROK_HOME, agy: env.AGY_HOME },
})
binding.whileChanging((agentId) => restorePanes.busy(agentId))
const pendingForkInherit = binding.pendingForkInherit
const handleRegistered = binding.handleRegistered
const bindObservedAgent = binding.bindObservedAgent
// What the reconciler's scans mean for the registry (core/agents/discovery.ts).
const discovery = createDiscoveryHandlers({
registry,
attachDsh,
forgetSession,
announceSession,
bindObservedAgent,
syncRecapPool,
attachSession,
invalidateTerminalControl,
input,
deviceInput,
questionWatcher,
stopHeartbeat,
retainExitedSession,
stoppedAgents,
restoreDegraded: (agentId) => restoreFailed || restoreUnsurveyed.has(agentId),
terminals,
})
// HARNESSD_TEST_SLOW_PROBE_MS holds each discovery probe for up to that long, at random, before it is
// applied: some scans land at once and some straddle an agent's start, as on a loaded machine. The
// end-to-end suite uses it to put a scan across an engine's start on purpose (e2e/core.e2e.ts).
const slowProbeMs = Number(harnessd.HARNESSD_TEST_SLOW_PROBE_MS) || 0
const gridAssignments = createGridAssignments({ models: () => ports.models ?? MODELS_OFF, registry,
revision: (id) => restartJobs.revision(id), announce: announceSession })
// Set once the stop below exists: a Harness Team account's daemon stops for good once no agent runs in it.
let afterAgentsPass = (): void => {}
const agentReconciler = new TerminalAgentReconciler({
// The hook server starts before restore. Its early SessionStart hints must not run a full
// discovery scan over rows whose panes have not been recreated yet (and archive those rows).
deferUntilStart: true,
current: () => registry.list(),
backends: terminalBackends,
backendOrder: terminalConfig.backends,
transaction: (apply) => registry.transaction(apply, { holdSavesMs: RECONCILE_PASS_DEADLINE_MS }),
...(slowProbeMs > 0 ? {
probe: async (hints: Parameters<typeof probeTerminalAgents>[3]) => {
const probe = await probeTerminalAgents(terminalBackends, terminalConfig.backends, process.pid, hints)
await new Promise((resolve) => setTimeout(resolve, Math.random() * slowProbeMs))
return probe
},
} : {}),
...discovery,
onReconciled: (agents) => {
gridAssignments.observe(agents)
afterAgentsPass()
if (ptyDrain) {
void ptyDrain.step().catch((error) => {
console.error('[terminal] ptyhost: drain failed:', error instanceof Error ? error.message : error)
})
}
// At most one idle, unwatched agent at a time moves off a drained host (lib/hostMove/mover.ts).
void hostMover?.step().catch((error) => {
console.error('[terminal] move: the mover failed:', error instanceof Error ? error.message : error)
})
},
onProbeStatus: (status) => {
discoveryReady = status.ready
discoveryError = status.error
},
})
// A PTY host that died took its panes with it: the reconnected (new) host lists none of them, and a pass
// now marks their agents gone, which the resume path takes from there, rather than at the next tick.
// A drain host that exited took its panes too.
for (const backend of ptyHosts ? [ptyHosts.create, ...ptyHosts.drain] : []) {
backend.onHostReplaced = () => {
void agentReconciler.trigger().catch((error) => {
console.error('[terminal] ptyhost: reconcile after host restart failed:', error instanceof Error ? error.message : error)
})
}
}
// Account HTTP and the persistent machine cache belong to the gateway. The core routes the request
// and keeps only state reported by that service, so a backend outage cannot stall an agent's loop.
function proxyBackend(method: string, path: string, body?: unknown): Promise<{ status: number; body: Record<string, unknown>; retryAfterMs?: number }> {
return gatewayOps.backend(method, path, body)
}
// The daemon's status (GET /api/status, read by `harness status`, the desktop's discovery and scripts):
// health, the computer's fingerprint and its local pairings. It deliberately does NOT expose chat or
// transcripts. The fingerprint and the pairings are the gateway's, asked for each time (bounded:
// core/gatewayLink.ts).
const statusBody = async (relay: GatewayStatus): Promise<Record<string, unknown>> => ({
machineId: backend.machineId,
computerId: computerId(),
// Whether this daemon booted with an account. Read LIVE, not from the boot session: a login or
// logout restarts the daemon, and the window between the file changing and the restart landing
// is exactly when the app asks — the answer it needs is the file's.
signedIn: readAuthSession() !== null,
version: VERSION,
localWs: {
path: LOCAL_WS_PATH,
protocolVersion: LOCAL_WS_PROTOCOL_VERSION,
terminalProtocolVersion: TERMINAL_BINARY_VERSION,
e2ee: false,
},
// The same REST and local WS, over the daemon's Unix socket (lib/localSocket.ts). Null where
// none could be opened; clients then stay on this port.
localSocket: daemonBoot.localSocket?.path ?? null,
backendUrl: env.BACKEND_WS_URL,
autonomousEnv,
dataDir: env.ADAPTER_DATA_DIR,
authDir: AUTH_DIR,
webUrl: env.WEB_URL,
connected: backend.isConnected(),
deviceTransportConnected: backend.hasCommander(),
deviceE2eeConnected: backend.deviceE2eeConnected(),
uptimeSec: Math.round((Date.now() - startedAt) / 1000),
// The daemon as everything outside knows it: the pid file's pid, which `harness stop` signals
// and the desktop app judges the owner of. Under a master that is the master's. A core's pid
// changes with every restart, and macOS counts a core as its master's, so an app judging the
// core would read a daemon started from tmux or ssh as "owned by node" and restart it on sight.
pid: coreLink.masterPid ?? process.pid,
corePid: process.pid,
startedAt,
// The master keeping this core running, when one is: how often it has restarted it, and why the
// last one ended. Null for a core run on its own.
harnessd: coreLink.supervised ? { masterPid: coreLink.masterPid, ...coreLink.status() } : null,
// True for the few hundred ms between an update being staged and this server closing for the
// handoff. Informational: nothing should build readiness on a field the server stops serving.
restarting: updateHandoff.restarting(),
discoveryReady,
discoveryError: discoveryError ?? (terminalUnavailable ? `${terminalUnavailable.backend} unavailable: ${terminalUnavailable.reason}` : null),
// Present only when start-up failed and this daemon is holding the machine open until a fix
// arrives. Clients key on `discoveryReady`; this says WHY, in one word, for a person reading it.
...(daemonBoot.safeMode ? { safeMode: true } : {}),
// Agents whose history is being read right now, and how many wait their turn. Normally empty or
// gone in a second; one that stays here names the store that is slow, which no other field does.
attaching: attaches.attaching(),
attachQueue: attaches.queued(),
fingerprint: relay.fingerprint,
config: {
watching: `${terminalConfig.backends.join(' + ')} terminals across all supported engines`,
terminalBackends: terminalConfig.backends,
terminalSelection: backendsExplicit ? 'configured' : 'auto',
terminalTargets: terminalBackends.map((target) => ({
backend: target.name, instance: target.instanceId.slice(target.name.length + 1), state: 'configured',
})),
dormantAgents: registry.list().filter((session) => !session.active).length,
dataDir: tildify(env.ADAPTER_DATA_DIR),
port: daemonPort(),
},
sessions: await Promise.all(registry.advertised().map(async (s) => ({
id: s.agentId,
sessionId: s.sessionId,
name: projectDisplayName(s),
engine: s.engine,
cwd: tildify(s.cwd ?? ''),
tmuxPane: s.tmuxPane || null,
terminal: { available: registry.terminalAvailable(s.agentId), primary: s.primaryRuntimeKey, runtimes: s.runtimes },
// When the conversation last moved, as in every agent frame — not the row's `touchedAt`.
updatedAt: await lastActivityAt(s),
}))),
pairs: relay.pairs,
pending: relay.pending,
})
const turnHooks = createTurnHooks({
holdStop: attach.holdStop,
afterStop: attach.afterStop,
resolve: (id) => registry.resolve(id),
normalizers,
emit: (sessionId, events) => emitSessionEvents(sessionId, events),
drain: (sessionId) => watcher.pollSession(sessionId),
onCursorTaskStart,
cursorTaskHooks,
cursorSubagents,
announceTurnAborted,
armAgyIdleWatch,
clearAgyIdleWatch,
mirror,
dataDir: env.ADAPTER_DATA_DIR,
})
// Which agent a hook belongs to, and what a SessionEnd means (core/engines/hooks.ts).
const engineHooks = createEngineHooks({ get tmuxBackend() { return tmuxBackend }, ptyHostBackend, agentReconciler, registry, panePending: restorePanes.pending, syncSession })
// What agents may do: the account's experiments, kept in this daemon's data folder for its launches
// (lib/agentSettings.ts, core/experiments.ts). Started once bound, below.
const agentSettings = createAgentSettingsSync({ dataDir: env.ADAPTER_DATA_DIR, backend: proxyBackend, session: readAuthSession,
// Agent Messages is told when its switch changes, wherever it runs: off, it reads it again only when told or its
// file changes (messages/service.ts).
onNotice: (listener) => experimentHooks.onNotice(listener), messagesChanged: () => ports.messages?.settingsChanged() })
// Windows: the daemon's pipe takes only requests that prove this token (lib/windows/pipeAuth.ts). It is made on
// the first start and kept in the data folder, in the profile.
const pipeToken = process.platform === 'win32' ? ensureDaemonToken(env.ADAPTER_DATA_DIR) : null
const { server: hookServer, port: hookPort, localSocket } = await startHookServer(daemonPort(), {
onAutonomousDeviceRequest: async (method, target, body) => {
// Until the pieces below are built; after, a piece that could not be is refused by the requests
// that need it, and the rest (list, status, revoke) answer from the pairings.
if (!devicePartsBuilt) return { status: 503, body: { error: { code: 'UNAVAILABLE', message: 'Autonomous device service is starting' } } }
// A Harness Team daemon pairs no Wi-Fi device and serves none (backendSocket.ts disableWifi).
if (teamDaemon) return { status: 403, body: { error: { code: 'TEAM_ACCOUNT', message: 'A Harness Team account does not serve a Wi-Fi device.' } } }
// The Wi-Fi device's pairings and direct links are the gateway's (gateway/start.ts); its receipts its
// service's, with the dials (services/wifi.ts).
const viaGateway = async (request: Parameters<GatewayOps['wifi']>[0]): Promise<Record<string, unknown>> => {
const answer = await gatewayOps.wifi(request)
if ('refused' in answer) throw Object.assign(new Error(answer.refused.message), { code: answer.refused.code })
return answer.result
}
return autonomousDeviceLocalRequest({
discover: async () => { await wifiCore.serving(WIFI_START_MS); return viaGateway({ op: 'discover' }) },
pairStart: async ({ code, device }) => { await wifiCore.serving(WIFI_START_MS); return viaGateway({ op: 'pair', code, device }) },
pairStatus: () => viaGateway({ op: 'pairStatus' }),
list: () => viaGateway({ op: 'list' }),
status: async () => ({ transport: 'direct', connected: wifiCore.directSessions() > 0,
paired: ((await viaGateway({ op: 'list' })).devices as unknown[]).length, sessions: wifiCore.directSessions(), proto: 1 }),
revoke: ({ id }) => viaGateway({ op: 'revoke', id }),
receipt: async (target) => {
const answer = await (ports.wifi?.receipt(target.deviceId, target.idempotencyKey) ?? { unavailable: true as const })
if ('unavailable' in answer) throw Object.assign(new Error('The Wi-Fi device service is not running on this computer. See the daemon\'s log.'), { code: 'UNAVAILABLE' })
return { receipt: answer.receipt }
},
...deviceAddonRoutes((op, input) => ports.wifi?.addon(op, input) ?? Promise.resolve({ unavailable: true as const })),
// The device's own service, on this machine: the same `machine_addon` door, asked as a process here.
...machineAddonRoutes((op, input, waitMs) => outOfProcess.has('machineAddons')
? serviceLinks.call('machineAddons', 'machine_addon', { op, input }, waitMs + 5_000)
: new Promise((resolve) => { if (!serviceHost.route('machine_addon', { op, input }, { local: true, owner: true }, resolve)) resolve({ error: 'SERVICE_UNAVAILABLE' }) })),
}, method, target, body)
},
resolveHookAgent: engineHooks.resolveHookAgent,
hookAdmissionBlocked: id => launchCancelled(id),
onAdmissionHeld: engineHooks.onAdmissionHeld,
onAdmissionStop: attach.holdAdmissionStop,
captureAdmissionStop: attach.captureAdmissionStop,
onRegistered: handleRegistered,
onSessionEnd: engineHooks.onSessionEnd,
// What the engines' own hooks say about a turn (core/turns/turnHooks.ts).
onTurnStart: turnHooks.onTurnStart,
onToolStart: turnHooks.onToolStart,
onTurnStop: turnHooks.onTurnStop,
onPromptHook: turnHooks.onPromptHook,
stopHookDelayMs: Number(harnessd.HARNESSD_TEST_STOP_HOOK_DELAY_MS) || 0,
// `harness pair`, `unpair`, `remote-password`, `link connect`, `group` and `devices`: the keys are the
// gateway's, and so are these answers (gateway/start.ts).
onPair: (code) => gatewayOps.pair(code),
onListPairs: () => gatewayOps.listPairs(),
onRevoke: (id) => gatewayOps.revoke(id),
onRevokeAll: () => gatewayOps.revokeAll(),
onSetRemotePassword: (password) => gatewayOps.setRemotePassword(password),
onClearRemotePassword: () => gatewayOps.clearRemotePassword(),
onRemotePasswordStatus: () => gatewayOps.remotePasswordStatus(),
onTrustLinkedPeer: (peer) => gatewayOps.trustLinkedPeer(peer),
onGroupList: () => gatewayOps.groupList(),
onGroupSync: () => gatewayOps.groupSync(),
onGroupRemove: (selector) => gatewayOps.groupRemove(selector),
onDevicesList: () => gatewayOps.devicesList(),
onDevicesRemove: (pub) => gatewayOps.devicesRemove(pub),
onDevicesHistory: () => gatewayOps.devicesHistory(),
onDevicesDismiss: (body) => gatewayOps.devicesDismiss(body),
onDevicesRebaseline: (confirm, head) => gatewayOps.devicesRebaseline(confirm, head),
onStatus: async () => statusBody(await gatewayOps.status()),
onMachinesList: () => gatewayOps.machines(true),
onMachineRename: (machineId, name) => proxyBackend('PATCH', `/api/machines/${encodeURIComponent(machineId)}`, { name }),
onMachineDelete: (machineId) => proxyBackend('DELETE', `/api/machines/${encodeURIComponent(machineId)}`),
onAuthMe: () => proxyBackend('GET', '/api/auth/me'),
onAuthMeUpdate: (body) => proxyBackend('PATCH', '/api/auth/me', body),
onAuthHandoff: () => proxyBackend('POST', '/api/auth/handoff', {}),
...daemonStopRoute({ askMaster: () => coreLink.stopAll(), stopHere: () => daemonBoot.stopHere('harness stop') }),
// Signed out there is nothing shared WITH this computer and nobody to ask: a share is made on the
// account. Answered as an empty list rather than proxied into the backend's 401, which is the one
// status the desktop app reads as "your session ended" — and a guest has no session to end.
onSharedHarnesses: () => readAuthSession()
? proxyBackend('GET', '/api/harness-shares')
: Promise.resolve({ status: 200, body: { success: true, data: { machines: [] } } }),
// The account's desk — see backend routes/desk.ts. The window edits its tabs through the ops
// route and hears about everyone else's edits as `desk_changed` (backendSocket.ts).
onDeskRead: () => proxyBackend('GET', '/api/desk'),
onDeskOps: (body) => proxyBackend('POST', '/api/desk/ops', body),
// The account's tabs for Agent Messages (backend routes/agentMessages.ts). A tab's flag is an older window's only:
// the account's experiment decides, so its switch is passed on and wakes nothing.
onAgentMessagesRead: () => proxyBackend('GET', '/api/agent-messages'),
onAgentMessagesWrite: (tabId, body) => proxyBackend('PATCH', `/api/agent-messages/tabs/${tabId}`, body),
onExperimentalRead: () => agentSettings.experimentalRead(),
onExperimentalWrite: (body) => agentSettings.experimentalWrite(body),
onAgentSettingsRead: () => agentSettings.settingsRead(),
onAgentSettingsWrite: (body) => agentSettings.settingsWrite(body),
onProductFeedback: (body) => proxyBackend('POST', '/api/product-usage/feedback', body),
onSignInAnswer: (action, body) => proxyBackend('POST', `/api/auth/qr/${action}`, body),
...(swarm ? { onSuperTabAttachment: (req, res, path) => swarm.forwardAttachmentUpload(req, res, path,
{ accessToken: () => auth.accessToken(), environment: autonomousEnv, base: backendHttpBase() }),
// A file over 10 MB: its signed link and its completion, with the account's token; the bytes go straight to storage.
onSuperTabAttachmentUpload: (path, body) => proxyBackend('POST', path, body) } : {}),
onProductUsageReport: (body) => proxyBackend('POST', '/api/product-usage/report', body),
onProductUsageRead: () => proxyBackend('GET', '/api/product-usage/settings'),
onProductUsageWrite: (body) => proxyBackend('POST', '/api/product-usage/settings', body),
onStore: (method, path, body) => proxyBackend(method, path, body),
}, { socketPath: localSocketListenPath(env.ADAPTER_DATA_DIR, env.PORT), pipeToken, allowPortFallback: true })
// On Windows the record also names the pipe and this core's pid: both are new on each start, so clients read them here.
try { saveDaemonPort(env.ADAPTER_DATA_DIR, env.PORT, hookPort, pipeToken && localSocket ? { pipe: localSocket.path, pid: process.pid } : undefined) } catch (error) {
await localSocket?.close()
hookServer.close()
throw error
}
publishHookRoute(env.ADAPTER_DATA_DIR, hookPort)
// Claim the pid file for OURSELVES, and only now that the control port is bound. It used to be
// written by whoever spawned us — so a parent that died mid-handover left a daemon nothing could
// manage — and then, for a while, by us at the top of this function, before the bind — so a child
// that LOST the port to a sibling still left a file naming itself, a corpse, over the winner. A
// process that is running AND holds the port is the only honest author of its own pid; that claim
// is also the signal `harness start` and the update handoff wait on to know the bind succeeded.
// Under harnessd the master claims it, for itself, when this core says it is bound.
if (coreLink.supervised) {
coreLink.bound(hookPort)
coreLink.startHeartbeat()
// The experiments with saved state are on: their processes are asked for now, the master heeding a bound core
// alone (core/experiments.ts). The others wait for their first request. Agent Messages is asked for too, which
// starts a process only under a master from before it joined the edge host (core/messagesLink.ts).
wakeExperiments({ dataDir: env.ADAPTER_DATA_DIR, experiments: EXPERIMENTS, outOfProcess, want: (service) => experimentHooks.want(service) })
askForMessages(outOfProcess, (service) => coreLink.want(service))
devicesWake.start(outOfProcess)
wakeModels({ outOfProcess, dataDir: env.ADAPTER_DATA_DIR, runtimeDir: env.ADAPTER_RUNTIME_DIR, want: (service) => coreLink.want(service) })
wakeViewers({ wake: viewersWake, agents: () => registry.list(), dataDir: env.ADAPTER_DATA_DIR })
} else {
try { writeFileSync(PID_FILE, String(process.pid) + '\n') } catch { /* best effort */ }
}
// The account's agent experiments, read now and as they change, once the experiments above may be asked for.
agentSettings.start()
// The one thing a handoff that happens before start-up finishes has to release: the port has no
// fallback, so a successor that cannot bind it is a daemon that does not come up (see bootHandoff).
daemonBoot.hookServer = hookServer
daemonBoot.localSocket = localSocket
console.log(`[cli] daemon pid ${process.pid} · v${VERSION}${process.env.ADAPTER_UPDATED_TO ? ' · updated' : ''} · listening on 127.0.0.1:${hookPort}`)
// The device key log records which sign-in this machine is under: a session from before sign-in epochs
// gets one first, adopted so it never starts the log over, and the gateway registers with it then.
if (session?.machineId) void ensureSignInEpoch().catch(() => null).then(() => gatewayOps.account(account()))
// The dial, the window bridges and the Wi-Fi device are the devices' (services/devices.ts, services/wifi.ts),
// behind their ports, guarded there: the local socket closes a connection whose frame handler throws, so a
// device fault reaching here would disconnect the desktop, again on every pane change.
/** Which window has the person's attention, as the devices are told it. */
const windowFocus = (): WindowFocus => ({ voice: appVoiceFocus ?? null, form: appFormWindow ?? null })
/** ⌘K's answer with no devices to route through. */
const unrouted = (reason: string): RouteAnswer => ({ agentId: '', machineId: '', name: '', confidence: 0, reason, candidates: [], weighed: 0, machines: 0, via: '' })
const DEVICES_OFF = 'the devices service is unavailable'
const localWsServer = attachLocalWsServer(hookServer, {
localSocketServer: localSocket?.server ?? null,
// Over TCP the window, the CLI or a tool shows this user's 0600 credential (lib/localCredential.ts).
localCredential: loadOrCreateHookCredential(env.ADAPTER_DATA_DIR),
services: serviceLinks,
// A window's answer to a bridge's ask, and its comings and goings: the window bridges are the devices'.
onSelectionReply: (connId, machineId, payload) => ports.devices?.windowReply('selection', connId, machineId, payload),
onVisitReply: (connId, machineId, payload) => ports.devices?.windowReply('visit', connId, machineId, payload),
onFormReply: (connId, machineId, payload) => ports.devices?.windowReply('form', connId, machineId, payload),
onAppDisconnect: (machineId, connId) => {
if (appFormWindow?.connId === connId) appFormWindow = undefined
if (appVoiceFocus?.connId === connId) appVoiceFocus = undefined
ports.devices?.windowFocus(windowFocus())
ports.devices?.windowGone(connId)
void ports.wifi?.appFocus(machineId, null, connId)
},
// The window and the dial are one desk: opening an agent in the app brings the dial to it, switching
// the dial's machine first when the app moved to another one.
onDevicePrepareOpened: (operationId, agentId) => ports.wifi?.revealed(operationId, agentId),
onAppFocusState: (machineId, agentId, connId, expectedRevision) => {
// A delayed automatic selection cannot replace a newer explicit user choice. A device service
// that cannot say which choice is newest is one with no choice to protect: refused, as without one.
if (expectedRevision && wifiCore.focusRevision() !== expectedRevision) return false
appFormWindow = { machineId, connId }
if (agentId === null) {
if (appVoiceFocus?.connId === connId) appVoiceFocus = undefined
} else appVoiceFocus = { machineId, agentId, connId }
ports.devices?.windowFocus(windowFocus())
void ports.wifi?.appFocus(machineId, agentId, connId)
},
onAppFocus: (machineId, agentId) => ports.devices?.appFocus(machineId, agentId),
// Everything the window still has unread. Held rather than acted on: the dial is handed it when a
// cable attaches, which is the one moment its own drawer is known to be empty.
onAppUnread: (items) => {
appUnreadLatest = items
ports.devices?.unread(items)
},
// The window looked at a harness, so the dial's drawer row for it is stale.
// The dial's own tap already reaches the window (`agent.open`); this is the
// return leg, and the pair is what keeps the badge and the pill equal.
onAgentSeen: (agentId, readToken) => ports.devices?.seen(agentId, readToken),
// The window's swarms. Relayed to the dial as its own list — the dial names the one on screen above
// the agent and offers the rest — and, through setSwarms, what makes the desk strict: a present
// window with an empty swarm is an empty carousel, not the whole machine.
onAppSwarms: (swarms) => {
appSwarmsLatest = swarms
ports.devices?.swarms(swarms)
},
onAppTabAgents: (connection, ids) => cleanupTabs.updateWindow(connection, ids),
// Agents the window has a tile for, in tile order: the dial's ring (services/devices.ts). A finished turn
// on one of these is already in front of the person, so the dial updates its tile in silence rather
// than beeping about something being looked at. An OPEN tile counts as seen, deliberately — not a
// focused one: with four tiles on a grid all four are on screen.
onAppPanes: (agentIds, foreground) => {
appPaneAgents = agentIds
// A tile behind a browser is not a tile anybody is looking at: the roster does not change when the
// window loses focus, so without this the dial went quiet about work nobody could see.
appWindowForeground = foreground
ports.devices?.desk(agentIds, foreground)
const next = new Set(agentIds)
// Logged on CHANGE only. It fires on every pane add, close and reconnect,
// and it is the one place the whole feature is observable from — without
// it, "the dial went quiet" and "the roster never arrived" look identical.
const changed = next.size !== openPaneAgents.size || [...next].some((id) => !openPaneAgents.has(id))
openPaneAgents = next
if (changed) console.log(`[cable] window tiles: ${next.size ? [...next].map(sid).join(' ') : '(none)'}`)
},
// ⌘K in the window: a typed task, and which agent it belongs to, on any of the owner's machines. The
// fleet's to answer, beside the dial in the devices (services/fleet.ts routeTask), so it answers with
// the dial absent or off.
onRouteTask: backend.ownerCommands.onRouteTask = async (text) => ports.devices ? ports.devices.routeTask(text) : unrouted(DEVICES_OFF),
// A window that connects after the dial did has missed the `dial_status` that announced it: the last one
// the devices sent, kept here.
dialStatus: () => lastDialStatus,
/*
* A window changing a device's settings. Addressed by the fleet's id, so a second robot on the same
* desk is not dragged along — every other cable command broadcasts on purpose (they all show the
* same desktop), but a preference belongs to the glass it was set on.
*
* Nothing is answered here. The device replies to its own `settings.set` with the values it now
* holds, and that reaches the window as an ordinary `dial_status`.
*/
onDialSettings: (id, patch) => ports.devices?.settings(id, patch),
openQuestions: () => [...openQuestions.values()],
// Committed. Sent through the fleet's router — the dial's own dispatch — and NOT straight into
// backend.onMessage: that resolves the id against THIS computer's registry, so a remote agent would land
// as "This harness is no longer available", an error about an agent alive on another machine.
onRouteSend: backend.ownerCommands.onRouteSend = async (agentId, text) =>
ports.devices ? ports.devices.routeSend(agentId, text) : { ok: false, machine: '', reason: DEVICES_OFF },
onVoiceRouteReply: (voiceId, reply) => ports.devices?.voiceReply(voiceId, reply),
machineId: backend.machineId,
backend,
relayPool: gateway.windowRelay,
autonomousEnv: readAuthSession()?.autonomousEnv ?? env.AUTONOMOUS_ENV,
// A window from before it introduced itself still gets named on the far side's "took control"
// banner: the relay knows it is this machine's desktop. Same source as `describeClient` above.
// Cut to the wire's limit here rather than let the far daemon drop the whole claim over a long name.
localClient: () => ({ kind: 'desktop', name: terminalHintMachineName().slice(0, 64), machineId: backend.machineId }),
})
localWsServerRef = localWsServer
// Teardown owns the controller as soon as the background pass starts after readiness.
let installedHooks: ReturnType<typeof installEngineHooks> | undefined
// Each transcript line, through its engine's normalizer, into the funnel (core/transcripts/ingest.ts).
const ingest = createIngest({
liveFor,
has: (sessionId) => registry.has(sessionId),
bySession: (sessionId) => registry.bySession(sessionId),
tokenUsage: { changed: target => usageLink.port.changed(target) },
device: () => wifiCore.feed,
runtimeProfiles,
normalizers,
announceTurnAborted,
emit: (sessionId, events, opts) => emitSessionEvents(sessionId, events, opts),
attachSession: (session, reset) => attachSession(session, reset),
})
ingest.wireWatcher(watcher)
// Nothing re-attaches the registry's agents here. Every one of them is dormant from the moment the
// registry loads (see the `setActive(false)` transaction at the top of this function), and the first
// reconcile pass is what reactivates each one it finds a live process for — and attaches it, in the
// background and a few at a time (`onObserved` above, `attaches` below). Readiness never waits on an
// agent's history being read: one slow store used to hold the app out of every agent on the machine.
/**
* What the launch builder needs to know about THIS machine, read at launch time.
*
* The one fact is whether an administrator pinned Hermes settings in `/etc/hermes`: Hermes's web
* tools ride a managed-scope overlay that REPLACES that directory rather than adding to it, and the
* builder drops the overlay on such a machine (the agent launches on the grid without web tools,
* and the app says so). Read here rather than in the contract because it is a fact about the
* machine: a `build()` that stats the filesystem answers differently on two of them, and its spec
* would follow. What is DONE with the fact lives in the builder, so create, retarget and restore
* cannot disagree about it.
*
* The other is which OpenCode is installed: v2's TUI exits 1 on v1's `-m` / `--agent`. Cached per
* installed file (`engines/opencode/version.ts`), so this costs a `stat` after the first read. Read for an
* OpenCode launch alone, by OpenCode's own code: every launch of OpenCode loads it before asking, and is refused
* without it (core/agents/create.ts, lib/launchOverrides.ts).
*/
const gridLaunchMachine = async (engine: AgentEngine, native?: NativeLaunch): Promise<GridLaunchMachine> => ({
hermesSystemManaged: existsSync(HERMES_SYSTEM_MANAGED_DIR),
opencodeMajor: native ? native.opencodeMajor : engine === 'opencode' ? await opencodeMajorVersion() : null,
...(native?.environment.HOME ? { grokHome: nativeHookLocations(native.environment).GROK_HOME } : {}),
})
/**
* What a relaunch of `session` must be given, beyond the engine's argv, to come back where it was —
* on its grid (the registry kept the launch, key included) or under its Codex profile. Restore and
* restart read the row; retarget passes the override the desktop just sent. The config directory is
* keyed on the agent, so relaunching the same agent rewrites one directory instead of leaving a trail.
*/
// Grid and saved-API launches are built by the models service (core/agents/launch.ts `gridLaunchThrough`): a
// launch on one while models is down is refused, and one on the engine's own login never asks it.
const gridLaunch = gridLaunchThrough(() => ports.models ?? MODELS_OFF)
const dshLaunch = dshThrough({ store: () => ports.store ?? STORE_OFF,
nameOf: id => installedDsh(id)?.manifest.name, account: () => ({ privateGrid: backend.gridName() }) })
const prepareNativeLaunch = createNativeLaunchPreparer({
installations: (process.platform === 'win32' ? createWindowsInstallations : createNativeInstallations)({ directory: join(env.ADAPTER_DATA_DIR, 'native-installations') }),
inspect: (engine, source) => inspectNativeLaunch(engine, source, {
confirmHome: (engine, home) => { confirmHomes({ [sessionStoreContracts[engine].sessions.moved.variable]: home }) },
}),
// The Desktop's own download of the engine on a fresh computer: a launch waits for it rather than installing beside it.
downloading: (engine) => engineDownloading(engine),
})
const launchOverridesDeps: LaunchOverridesDeps = {
// A Swarm session's skill and GitHub App on every relaunch; off, such a session is not relaunched.
...(swarm ? { swarm: swarm.SWARM_LAUNCH } : {}),
publishConfig: publishGridConfigDir,
machine: gridLaunchMachine,
native: prepareNativeLaunch,
prepareNative: (native, current, environment, clear) => native.prepareHooks(env.DISABLE_HOOK_INSTALL ? 0 : hookPort, current, environment, clear),
gridLaunch,
writeGridConfigDir,
// No backend to make the pane on is not this check's to say: the launch answers the configured backend's code.
capabilities: () => createBackend?.capabilities() ?? Promise.resolve({ sessionEnv: true }),
installCodexHooks: (codexHome) => env.DISABLE_HOOK_INSTALL ? true : engineHookFacets.codex.installIn(hookPort, codexHome),
dshLaunch: dshLaunch.relaunch,
}
// What a relaunch needs to bring a pane back (core/agents/launch.ts). Declared before the restore
// pass below, which calls these for every pane it rebuilds.
const launchAuthority = createLaunchAuthority({ byAgent: id => registry.byAgent(id), revision: restoreRevision, cancelled: id => launchCancelled(id) })
const adoptSwarmSkill = swarm?.createSwarmSkillAdoption({
authority: launchAuthority,
candidate: id => swarm.retainedHarnesses(env.ADAPTER_DATA_DIR).has(id),
role: outOfProcess.has('superTabs')
? swarm.swarmRoleThrough((type, payload) => serviceLinks.call('superTabs', type, payload, 3500))
: id => ports.superTabs?.swarmRole(id) ?? Promise.resolve(undefined),
save: (id, skill) => registry.setSwarmSkill(id, skill),
})
const launchHelpers = createLaunchHelpers({
authority: launchAuthority,
prepareApiTools,
launchOverridesDeps,
setGridLaunch: (agentId, launch) => registry.setGridLaunch(agentId, launch),
setTail: (sessionId, offset) => watcher.setTail(sessionId, offset),
})
const relaunchOverrides = launchHelpers.relaunchOverrides
const refreshGridWebSearch = launchHelpers.refreshGridWebSearch
const downgradedPermission = launchHelpers.downgradedPermission
const prepareSessionResume = launchHelpers.prepareSessionResume
// Rows that drifted out of their project folder while `register` still took the hook's cwd on
// every prompt are put back BEFORE anything relaunches them: restore below `cd`s into `entry.cwd`,
// and what it archives on the way is copied from the row. See cwdRepair.ts.
// Best effort: an archive directory that cannot be listed, or a row that cannot be rewritten, is a
// line in the log, never a daemon that does not come up.
try {
const repaired = await repairProjectCwds({ registry, stoppedAgents, log: (message) => console.log(message) })
if (repaired.registry || repaired.archived) console.log(`[repair] cwd · ${repaired.registry} live · ${repaired.archived} saved`)
} catch (error) {
console.warn(`[repair] cwd repair skipped · ${error instanceof Error ? error.message : error}`)
}
watcher.start()
await cursorDiscovery.start()
// What a restored agent's engine writes from here on is live: the first attach of each folds its
// conversation only up to this byte (core/transcripts/relaunch.ts). The request gate opens before
// those attaches run, and a message answered in between was filed as history.
for (const entry of registry.list()) {
if (!entry.sessionId || !entry.transcriptPath || watcher.tails(entry.sessionId, entry.transcriptPath)) continue
const offset = transcriptSize(entry.transcriptPath)
if (offset !== null) relaunchMarks.note(entry.sessionId, offset)
}
// Panes that died while the daemon was down (a reboot takes the whole tmux server with it) are
// rebuilt BEFORE the first reconcile pass: it would otherwise count them absent, and a second
// pass five seconds later would drop the agents for good. Pane creation is awaited so the first
// announce already shows every restored agent with a terminal; binding their engine processes
// continues in the background, the same way `agent_create` does it.
for (const entry of registry.list()) {
const saved = isTerminalEngine(entry.engine) ? stoppedAgents.get(entry.agentId) : null
if (saved && !isTerminalEngine(saved.engine)) retainExitedSession(entry, true)
}
// What restore asks of the terminals, each pane of its own backend, and the launch it builds (both shared with a move
// to another pty host, core/agents/hostMove.ts). Every pane question asked of the pane's own backend, as every other
// pane read is.
const restoreOn = restoreTerminals({
backendFor: (runtime) => terminals.backendFor(runtime),
newPanesOn: (backend) => isDrainBackend(backend) ? createBackend : null,
listTmuxPanes: () => listTmuxPanes(),
cwd: homedir(),
label: (engine) => buildHarnessSessionLabel(engine),
})
const restoreLaunch = createRestoreLaunch({
adoptSwarmSkill,
workspaceMissing, relaunchOverrides, prepareSessionResume, refreshGridWebSearch,
downgradedPermission: (entry, native) => downgradedPermission(entry, entry.bypassPermission === true, 'restore', native),
launch: (entry, opts, overrides, permission) => {
const { env: launchEnv, extraArgs, ownerArgs, clearEnv } = overrides
const argv = buildEngineLaunchArgv(entry.engine, {
...opts,
...(overrides.native ? { native: overrides.native } : {}),
...(entry.externalResume?.continue && entry.externalResume.signal === 'sent' && !entry.externalResume.dispatched && supportsFirstPrompt(entry.engine) ? { firstPrompt: 'continue' } : {}),
bypassPermission: permission.bypassPermission === true,
...(permission.permissionMode ? { permissionMode: permission.permissionMode } : {}),
installIfMissing: enginePathOverride(entry.engine) ? undefined : engineInstallRecipe(entry.engine),
...(entry.cwd ? { cwd: entry.cwd } : {}),
...(extraArgs.length ? { extraArgs } : {}),
// The owner's own launch words, last on the command line (engineLaunch.ts `ownerArgs`).
...(ownerArgs?.length ? { ownerArgs } : {}),
...(clearEnv.length ? { clearEnv } : {}),
...(launchEnv.HARNESS_DSH ? { harnessNode: true } : {}),
})
// Windows: the variables the argv's `/usr/bin/env` prefix carries elsewhere, last (engineLaunchEnv).
const paneEnv = { ...launchEnv, ...engineLaunchEnv(entry.engine, overrides.native) }
return { argv, ...(overrides.native ? { nativeToken: overrides.native.token, current: overrides.native.current } : {}), ...(Object.keys(paneEnv).length ? { env: paneEnv } : {}),
// Windows: the workspace to start in and the shell the pane becomes after the engine (lib/windows/engineStart.ts).
paneLaunch: windowsPaneLaunch(entry.engine, { cwd: entry.cwd, clearEnv, native: overrides.native, held: isWindowsHeldPane(argv) }) }
},
})
// A move a dead daemon left before its switch left a pane marked as that move's, which no row names: closed now,
// before restore relaunches the row's own engine and discovery could mint that pane an agent beside it. One whose
// close is not confirmed may still run an engine on the conversation: its agent is held this start (not restored,
// not discovered, not moved), and so is the pane's route, until the next start closes it.
if (ptyHosts) {
const swept = await removeOrphanMovePanes(terminalBackends.filter((backend) => backend.name === 'ptyhost'), registry.list())
.catch((error) => {
console.warn(`[terminal] move: could not look for panes a stopped move left: ${error instanceof Error ? error.message : error}`)
return { removed: 0, unconfirmed: [] as string[], keptPanes: [] }
})
if (swept.removed) console.log(`[terminal] move: closed ${swept.removed} pane(s) a stopped move left`)
for (const pane of swept.keptPanes) agentReconciler.holdRoute(terminalRouteKey(pane), null)
for (const agentId of swept.unconfirmed) {
moveHeld.add(agentId)
const conversation = registry.byAgent(agentId)?.sessionId ?? stoppedAgents.get(agentId)?.sessionId
if (conversation) moveHeldConversations.set(conversation, agentId)
for (const runtime of registry.byAgent(agentId)?.runtimes ?? []) agentReconciler.holdRoute(terminalRouteKey(runtime), null)
console.warn(moveHeldLine(agentId))
}
}
// Later passes over held agents (core/agents/heldLaunches.ts) wait for this one.
await heldLaunches.boot(async (current) => {
// Restore runs where a backend can rebuild and relaunch a pane in place (tmux, the pty host): each row on the
// backend its pane is on (lib/restoreTerminals.ts).
if (terminalBackends.some(canRestart)) {
// Best effort, like the cwd repair above it: panes that cannot be rebuilt cost this boot its
// tiles, not the daemon. `restoreDegraded` then stops discovery retiring the rows whose panes
// restore never got to, so the next daemon can put them back.
try {
const restoreDeps: RestoreAgentsDeps = {
cancelled: (agentId) => !current() || restoreCancelled(agentId),
revision: (agentId) => restoreRevision(agentId),
paneOperation: restorePanes.run,
paneAllocations: restorePanes.runMany,
paneBusy: restorePanes.busy,
retainStopped: retainExitedSession,
keepAbandoned: keepAbandonedConversation,
registry,
engineStarted: (sessionId) => relaunchMarks.engineStarted(sessionId),
// "Alive" means the pane still runs THIS row's engine — not merely that tmux knows the id.
// A new tmux server hands out `%N` from zero again, so a stale id can name someone's shell;
// and a pane that outlived the daemon in a session discovery no longer lists still has its
// engine, which a second pane resuming the same session would collide with.
survey: restoreOn.survey,
restorable: restoreOn.restorable,
waitingPane: restoreOn.waitingPane,
liveProcess: restoreOn.liveProcess,
buildLaunch: restoreLaunch,
createPane: restoreOn.createPane,
respawn: restoreOn.respawn,
probeProcess: restoreOn.probeProcess,
paneState: restoreOn.paneState,
clearRemainOnExit: restoreOn.clearRemainOnExit,
holdRoute: (key, ms) => agentReconciler.holdRoute(key, ms),
releaseRoute: (key) => agentReconciler.releaseRoute(key),
triggerHint: async (runtime, engine) => { await agentReconciler.triggerHint(runtime, engine) },
log: (message) => console.log(message),
// A grid's or a saved API's launch asks models: not before the core is ready (core/agents/heldLaunches.ts).
// An older Swarm session's role (core/agents/restoreLaunch.ts): one unanswered read holds the rest of the pass unasked.
needs: (entry) => [...(externalResumePending(entry.externalResume) ? ['search'] : []), ...(entry.gridLaunch ? ['models'] : []), ...(entry.dsh ? ['store'] : []), ...(!isTerminalEngine(entry.engine) ? ['native'] : []), ...(adoptSwarmSkill?.needed?.(entry) ? ['superTabs'] : [])],
waitingLaunch: (entry, held) => ({ argv: heldPaneArgv(held.detail, entry.externalResume?.token ?? held.nativeToken) }),
killPane: restoreOn.killPane,
}
// Later passes launch the held agents, into the panes they wait in, outside this pass's transaction.
restoreOnly = (only, current) => restoreAgents({ ...restoreDeps, only, cancelled: id => !current() || restoreCancelled(id) })
const summary = await restoreAgents({ ...restoreDeps, defer: true })
// A row restore could not look at keeps its pane for discovery to judge, but not to retire this boot.
for (const agentId of summary.unsurveyed) restoreUnsurveyed.add(agentId)
if (summary.restored.length || summary.failed.length || summary.held.length || registry.rebootedSinceLastRun) {
console.log(`[restore] restored ${summary.restored.length} · skipped ${summary.skipped.length} · failed ${summary.failed.length}`
+ (summary.held.length ? ` · held ${summary.held.length} until the core is ready` : '')
+ (registry.rebootedSinceLastRun ? ' · after reboot' : ''))
}
} catch (error) {
restoreFailed = true
console.warn(`[restore] skipped · ${error instanceof Error ? error.message : error}`
+ ' · agents keep their rows and come back on the next start')
}
}
})
// Every DSH agent the registry kept gets its viewer and verdict watch back — restored or not, an
// agent whose pane is still up is still that harness.
for (const session of registry.list()) if (session.dsh) attachDsh(session)
await agentReconciler.start(env.TERMINAL_RECONCILE_INTERVAL_MS ?? env.TMUX_REAP_INTERVAL_MS)
// A file lock and a JSON parse, neither of which is worth the daemon: an unreadable queue means no
// pending Cursor tasks this boot, not no daemon.
const pendingCursorTasks = await loadPendingCursorTasks(env.ADAPTER_DATA_DIR).catch((error) => {
console.warn(`[cursor] pending tasks skipped · ${error instanceof Error ? error.message : error}`)
return []
})
for (const task of pendingCursorTasks) {
onCursorTaskStart(task.sessionId, task.toolUseId, task.input)
}
// Reconciliation is deliberately full: drain every transcript to EOF, inspect each live pane, then
// publish every session even when Model/Effort did not change. Reconnect runs the same path, while
// JSONL watcher events still provide immediate local-to-web updates between these safety passes.
let reconcileInFlight: Promise<void> | null = null
let reconcileNeedsDeviceAnnouncement = false
fullReconcile = (announceDevice = false): Promise<void> => {
reconcileNeedsDeviceAnnouncement ||= announceDevice
if (reconcileInFlight) return reconcileInFlight
reconcileInFlight = (async () => {
await runtimeProfiles.withoutChangeEvents(async () => {
await Promise.all(registry.advertised().map((session) => runtimeProfiles.ingestConfig(session, true)))
await watcher.pollAll()
await Promise.all(registry.advertised().map(session => runtimeProfiles.capturePane(session, captureTerminal, 120, true)))
})
await syncTerminalTitles()
const includeDevice = reconcileNeedsDeviceAnnouncement
reconcileNeedsDeviceAnnouncement = false
for (const session of registry.advertised()) {
if (includeDevice) announceSession(session)
else syncSession(session)
}
})().finally(() => { reconcileInFlight = null })
return reconcileInFlight
}
// Command Code keeps its reasoning level in a config FILE — nothing in the transcript, the pane or the
// session header announces a change — so without a tick of its own the chip showed a level up to five
// minutes stale, and never caught an effort the user changed in the CLI. Costs a small JSON read per
// Command Code session; ingestConfig only emits a change event when the value actually moved.
const COMMANDCODE_CONFIG_POLL_MS = 10_000
setInterval(() => {
for (const session of registry.list()) {
if (session.engine !== 'commandcode') continue
void runtimeProfiles.ingestConfig(session).catch(() => undefined)
}
}, COMMANDCODE_CONFIG_POLL_MS)
// Some engines announce a model change nowhere: no transcript row, no config file, no hook — the new
// model is simply drawn into the pane footer. The 5-minute reconcile was the only reader, so switching
// model in the terminal took up to five minutes to reach the device.
//
// devin — the footer is the ONLY source; nothing else ever reports the model.
// cursor — the transcript carries the model but never the reasoning level, and the level only exists
// in the footer. Without this poll a Cursor session picks up its effort once at attach and
// then never again.
//
// Read just the footer, and only while such a session exists. NOT silent: a real change has to push to
// the device, which is the whole point.
// agy joins these three: its model/effort exist only in the hook payload and the pane footer, never
// in the transcript, so the chip goes stale without a poll.
// opencode and its fork kilo belong here for the same stated reason and were simply missing: neither
// writes its model anywhere but the composer footer, so between reconciles their chips said nothing
// at all rather than going stale.
const PANE_POLLED_ENGINES = new Set(['devin', 'cursor', 'grok', 'agy', 'opencode', 'kilo'])
const PANE_POLL_MS = 15_000
setInterval(() => {
for (const session of registry.list()) {
if (!PANE_POLLED_ENGINES.has(session.engine)) continue
void runtimeProfiles.capturePane(session, captureTerminal, 60).catch(() => undefined)
}
}, PANE_POLL_MS)
const RUNTIME_RECONCILE_MS = 5 * 60_000
const runtimeReconcileTimer = setInterval(() => {
void fullReconcile().catch((err) => {
console.error('[runtime-profile] periodic reconcile failed:', err instanceof Error ? err.message : err)
})
}, RUNTIME_RECONCILE_MS)
const PANE_TITLE_SYNC_MS = 5_000
const paneTitleSyncTimer = setInterval(() => {
void syncTerminalTitles().catch((err) => {
console.error('[terminal-title] sync failed:', err instanceof Error ? err.message : err)
})
}, PANE_TITLE_SYNC_MS)
// A device joined mid-turn (count rise or join generation; no adapter heartbeat) → replay live state.
backend.onCommanderJoin = () => { mirror.replayAll(); questionWatcher.reset() } // re-announce an open question
backend.onCommanderPresenceChanged = (connected) => {
// Warm the voice-router worker while a device is connected (services/devices.ts).
ports.devices?.commanders(connected)
}
// Cancelling a turn (core/turns/cancel.ts).
const cancelAgent = createCancel({
beforeCancel: attach.beforeCancel,
resolve: (id) => registry.resolve(id),
normalizers,
cursorSubagents,
input,
device: () => wifiCore.feed,
stopHeartbeat,
questionWatcher,
mirror,
turnActivity,
turnStartedAt,
agentIdFor,
clients: backend,
})
backend.onCancel = id => { void cancelAgent(id) }
backend.cancelProvider = createCancelRequest((id) => { void cancelAgent(id) })
/**
* Web requested a new agent (`agent_create`): spawn a fresh tmux session running the chosen engine in
* the chosen folder, then hand it to the SAME discovery path organic sessions go through
* (`agentReconciler.triggerHint` → `onDiscovered` → registry + `announceSession`) rather than
* duplicating registration here.
*
* The freshly-exec'd engine process may not be visible to `ps` the instant tmux returns, so one probe
* pass can miss it — retry `triggerHint` a few times with backoff before giving up.
*/
// Watching a pane create or fork just opened until its engine is up, or why not (core/agents/newPane.ts).
const watchNewPane = createPaneWatcher({
registry,
announceSession,
triggerHint: async (runtime, engine) => { await agentReconciler.triggerHint(runtime, engine) },
captureTerminal,
retainExitedSession,
terminals,
})
// Opening a conversation Harness did not start, and taking it over from a terminal (core/agents/adopt.ts).
externalResumes = createExternalResumes({
// Its waiting pane opens where new panes are made, and is asked about and closed by the backend it is on.
registry, backend: createBackend, noBackendCode: createUnavailable, backendFor: (runtime) => terminals.backendFor(runtime),
stopped: () => stoppedAgents.list(), cancelled: id => restoreCancelled(id),
generation: () => searchGeneration,
waiting: row => heldIn(row, row.externalResume!.token, (runtime) => terminals.backendFor(runtime)).then(value => value === true),
inspect: request => ports.search?.inspect(request) ?? Promise.resolve(externalUnavailable()),
preflight: createExternalPreflight({ blocksFolder: cwd => backend.purgeAgentService?.blocksFolder(cwd),
native: prepareNativeLaunch, hookPort, hooksDisabled: env.DISABLE_HOOK_INSTALL, installOpencodePlugin: installOpencodePluginBeforeSpawn }),
announce: announceSession, launch: () => { void heldLaunches.restoreHeld('search') },
forget: id => forgetSession(id, { force: true }),
heldConversation: (sessionId) => moveHeldConversations.get(sessionId) ?? null,
})
// Creating an agent (core/agents/create.ts).
const creator = createAgentCreator({
...(swarm ? { swarmLaunch: swarm.SWARM_LAUNCH } : {}),
publishConfig: publishGridConfigDir,
native: prepareNativeLaunch,
dshLaunch,
createBackend,
recoverBackend,
noBackendCode: createUnavailable,
registry,
externalResume: externalResumes.create,
watchNewPane,
announceSession,
attachDsh,
prepareApiTools,
hookPort,
hooksDisabled: env.DISABLE_HOOK_INSTALL,
installOpencodePlugin: installOpencodePluginBeforeSpawn,
gridLaunchMachine,
buildGridLaunch: gridLaunch,
terminalHintMachineName,
blocksFolder: (cwd) => backend.purgeAgentService?.blocksFolder(cwd),
gridSetup: () => {
const models = ports.models
return models ? (request) => models.ensure(request) : null
},
// The backend's word, else what the models service works out (services/models.ts).
privateGridName: async () => backend.gridName() ?? await (ports.models ?? MODELS_OFF).privateGridName(),
})
backend.onCreateAgent = creator
// Forking an agent (core/agents/fork.ts).
backend.onForkAgent = createAgentForker({
native: prepareNativeLaunch,
prepareNative: launchOverridesDeps.prepareNative,
authority: launchAuthority,
dshLaunch,
createBackend,
noBackendCode: createUnavailable,
registry,
mirror,
pendingForkInherit,
watchNewPane,
announceSession,
attachDsh,
prepareApiTools,
relaunchOverrides,
gridName: () => backend.gridName(),
})
// Swapping a pane's engine process, for restart and retarget (core/agents/swap.ts).
const paneSwap = createPaneSwap({
restartJobs,
byAgent: (agentId) => registry.byAgent(agentId),
prepareSessionResume,
keepAbandonedConversation,
stopNative: (session, current) => nativeControls.stop(session, current),
})
// A message sent while an engine is being replaced waits for the new one instead of being refused.
terminals.whileChanging((agentId) => restorePanes.busy(agentId) || restartJobs.busy(agentId))
const sameRestartTarget = paneSwap.sameRestartTarget
const paneSwapDeps = paneSwap.paneSwapDeps
const liveBypassPermission = paneSwap.liveBypassPermission
// Moving a running agent onto a grid, or back to its own login (core/agents/retarget.ts).
backend.onRetargetAgent = createAgentRetargeter({
noBackendCode: createUnavailable,
adoptSwarmSkill,
sessionTurnOpen,
// A retarget swaps the engine too: not of an agent a stopped move may still run beside (`moveHeld`).
purgeBusy: (agentId) => restorePanes.busy(agentId) || backend.purgeAgentService?.busy(agentId) || moveHeld.has(registry.resolve(agentId)?.agentId ?? agentId),
terminals,
registry,
runtimeProfiles,
launchOverridesDeps,
acquireTerminalControl,
relaunchOverrides,
downgradedPermission,
agentReconciler,
restartJobs,
paneSwapDeps,
liveBypassPermission,
refreshGridAssignment: gridAssignments.refresh,
announceSession,
opencodeDb: OPENCODE_DB,
})
// Stopping, purging and resuming an agent (core/agents/lifecycle.ts).
const lifecycle = createAgentLifecycle({
adoptSwarmSkill,
settlePane: restorePanes.settle,
cancelExternal: externalResumes.cancel,
registry,
stoppedAgents,
restartJobs,
// A resumed harness opens where new panes are made; every pane is stopped and asked about on its own backend.
createBackend,
noBackendCode: createUnavailable,
backendFor: (runtime) => terminals.backendFor(runtime),
agentReconciler,
forgetSession,
markDeleted,
clearDeleted,
stopNative: (session, current, confirmUnused) => nativeControls.stop(session, current, confirmUnused),
atFolderTrust: async (session) => (await screens.read(session, await captureTerminal(session.agentId, 80)))?.messageHold === 'trust_open',
atEmptyComposer: async (session) => {
const reading = await screens.read(session, await captureTerminal(session.agentId, 80))
return !!reading && !reading.busy && !reading.question && reading.messageHold === null && reading.teamHold === null
},
sessionCheckpoints,
mirror,
sessionSearch,
send: (frame) => backend.send(frame),
pinnedControls,
retainExitedSession,
announceSession,
relaunchOverrides,
prepareSessionResume,
refreshGridWebSearch,
attachDsh,
attachSession: (session) => attachSession(session),
relaunchMarks,
// A harness closed or stopped: the harnesses it started close with it (services/agentCleanup.ts).
stopped: (agentId) => ports.agentCleanup?.closed(agentId),
moveHeld: (agentId) => moveHeld.has(agentId),
// The Lead of an active Swarm project is never stopped (owner, 2026-10-23); its host keeps the list (superTabs/retention.ts).
...(swarm ? { leadProtected: (agentId: string, leadSwitch?: string) => swarm.mayBeLead(env.ADAPTER_DATA_DIR, agentId, leadSwitch) } : {}),
})
const stopJobs = lifecycle.stopJobs
launchCancelled = id => stopJobs.has(id)
restoreCancelled = (agentId) => stopJobs.has(agentId) || pinnedControls.has(agentId) || moveHeld.has(agentId) || (restartJobs.operation(agentId) !== undefined && restartJobs.operation(agentId) !== 'restart')
binding.whileChanging((agentId) => restorePanes.busy(agentId) || restartJobs.busy(agentId) || stopJobs.has(agentId))
const stopAgent = lifecycle.stopAgent
const stopTerminalAgent = createStopRequest({ byAgent: (id) => registry.byAgent(id), stop: stopAgent })
backend.stopProvider = (payload) => cloud.stop(String(payload.agentId ?? payload.sessionId ?? '')) ?? stopTerminalAgent(payload)
backend.purgeAgentService = lifecycle.purgeAgentService
backend.purgeProvider = createPurgeRequest({ purgeAgentService: () => lifecycle.purgeAgentService, invalidateStorage: () => { void (ports.monitor ?? MONITOR_OFF).storage([], true) } })
// Closing agents no window shows, and the cleanup preview (core/agents/close.ts).
const closing = createAgentClosing({
readScreen: screens.read,
registry,
cleanupTabs,
watcher,
captureTerminal,
sessionTurnState,
openQuestions,
terminals,
sessionCheckpoints,
stopAgent,
announceSession,
engineReady: (engine, ms) => engineLinks.ready(engine, ms),
stoppedAgents,
// A Swarm Buddy keeps running when a window closes its view (Diego, 10-30); Stop Harness above still stops it.
...(swarm ? {
leadProtected: (agentId: string, changeId?: string) => swarm.leadCloseProtected(env.ADAPTER_DATA_DIR, agentId, changeId),
leadSwitching: (agentId: string, changeId: string) => swarm.leadSwitching(env.ADAPTER_DATA_DIR, agentId, changeId),
leadSwitchEnded: (agentId: string, changeId: string, stopped: boolean) => swarm.leadSwitchEnded(env.ADAPTER_DATA_DIR, agentId, changeId, stopped),
buddyProtected: (agentId: string, changeId?: string) => swarm.buddyCloseProtected(env.ADAPTER_DATA_DIR, agentId, changeId),
} : {}),
})
backend.closeAgentService = closing.closeAgentService
backend.closeAgentService.start()
const closeRequests = createCloseRequests({ cleanupPreview: closing.cleanupPreview, closeAgentService: () => closing.closeAgentService })
backend.cleanupPreviewProvider = closeRequests.preview
backend.closeProvider = closeRequests.close
// Restarting an agent in its own pane (core/agents/restart.ts).
const restartAgent = createAgentRestarter({
adoptSwarmSkill,
native: prepareNativeLaunch,
restartJobs,
registry,
purgeBusy: (agentId) => restorePanes.busy(agentId) || backend.purgeAgentService?.busy(agentId),
stopJobs,
pinnedControls,
terminals,
sameRestartTarget,
agentReconciler,
terminalHintMachineName,
refreshGridAssignment: gridAssignments.refresh,
announceSession,
relaunchOverrides,
downgradedPermission,
refreshGridWebSearch,
liveBypassPermission,
paneSwapDeps,
restartHeld: (agentId) => heldLaunches.restartHeld(agentId),
moveHeld: (agentId) => moveHeld.has(agentId),
})
// Agents on a drained pty host move, one at a time and only while nobody uses them, to the target host once it can seed
// a pane (lib/hostMove/mover.ts). Each move is the agent's lifecycle operation: a restart, stop or delete waits for it
// or cancels it, as it would another restart.
if (ptyHosts?.drain.length && ptyHostBackend) {
const target = ptyHostBackend
const moveActivity = (row: RegisteredSession) => activityFrameContextRef?.(row)?.state ?? 'unknown'
const moveLookedAt = (agentId: string) => terminalStreams.isLookedAt(agentId) || terminalWatch.isWatched(agentId)
const moveOne = createHostMove({
registry, terminals, createBackend: () => createBackend,
restore: restoreOn, buildLaunch: restoreLaunch, paneSwapDeps,
// Every stream open to the agent follows it: the windows' and phones', and Share viewers'.
retarget: async (agentId, runtime) => { await Promise.all([terminalStreams.retarget(agentId, runtime), terminalWatch.retarget(agentId, runtime)]) },
gate: moveGate,
// What the mover picked the agent for, asked again up to the old engine's stop: still idle, quiet, unwatched.
eligible: (agentId) => {
// Handing over: a move not yet past the old engine's stop cancels itself (`settleMovesForHandOver`).
if (hostMover?.stopped) return false
const row = registry.byAgent(agentId)
return !!row && moveActivity(row) === 'idle' && hostQuiet.quietFor(agentId) >= QUIET_MS && !moveLookedAt(agentId)
},
holdRoute: (key, ms) => agentReconciler.holdRoute(key, ms),
announce: announceSession,
invalidateControl: invalidateTerminalControl,
refreshGridAssignment: gridAssignments.refresh,
waitingArgv: () => moveWaitingArgv(),
log: (line) => console.log(line),
})
hostMover = new HostMover({
list: () => registry.list(),
isDrainRow: (row) => row.runtimes.some((runtime) => {
const on = terminals.backendFor(runtime)
return !!on && isDrainBackend(on)
}),
// Only while the target's host is the one new panes are made on, and it lists `seed`.
targetCanSeed: () => createBackend === target && target.canSeed,
target: ptyTarget?.instance ?? target.instanceId.replace(/^ptyhost:/, ''),
resumesConversation,
activity: moveActivity,
quiet: hostQuiet,
lookedAt: moveLookedAt,
busy: (agentId) => restartJobs.busy(agentId) || stopJobs.has(agentId) || restorePanes.busy(agentId) || pinnedControls.has(agentId)
|| moveHeld.has(agentId),
move: async (row) => {
let outcome: MoveOutcome | null = null
const reply = await restartJobs.run(row.agentId, async (current) => {
outcome = await moveOne(row, current)
return outcome.moved
? { ok: true, session: registry.byAgent(row.agentId) ?? row, resumed: outcome.resumed }
: { ok: false, error: 'MOVE_FAILED', detail: outcome.reason }
}, 'move')
if (outcome) return outcome
// Another lifecycle operation held the agent: nothing ran, so nothing failed. Anything else counts as a failure.
const reason = reply.ok ? 'the move did not run' : reply.detail ?? reply.error
return !reply.ok && reply.error === 'AGENT_BUSY'
? { moved: false, reason, fellBack: false, cancelled: true }
: { moved: false, reason, fellBack: false }
},
log: (line) => console.log(line),
})
}
// One host per guest, reached on its first launch and kept: a launch must not open a new pipe connection (and a new
// reconnect timer) for a host that is already there.
const guestHosts = new Map<string, Promise<ReturnType<typeof createGuestHostBackend> | null>>()
const guestBackendFor = (user: string): Promise<ReturnType<typeof createGuestHostBackend> | null> => {
const known = guestHosts.get(user)
if (known) return known
const reached = (async () => {
const backend = createGuestHostBackend({ user })
try {
const prepared = await backend.prepare({ ownedPanes: new Map() })
if (prepared.state !== 'ready') { backend.dispose(); return null }
} catch (error) {
// A task that is gone, or a host that cannot start, is no host: the create says "turn sharing on again"
// rather than throwing out of the request.
console.warn(`[guest] ${user} host unavailable · ${error instanceof Error ? error.message : String(error)}`)
backend.dispose()
return null
}
terminals.addBackend(backend)
return backend
})()
guestHosts.set(user, reached)
void reached.then((backend) => { if (!backend) guestHosts.delete(user) })
return reached
}
const guestCreate = createGuestCreate({
launch: (input) => (ports.sharedMachines ?? SHARED_MACHINES_OFF).guestLaunch(input),
tmuxBackend: () => tmuxBackend,
// Windows: a guest's panes are made on the guest's own host, which runs as that account; there is no owner
// pane to hand over (lib/windows/guestHostBackend.ts).
...(process.platform === 'win32' ? { guestBackend: guestBackendFor } : {}),
registry, announceSession, watchNewPane,
})
// The requests that start an agent's process, and the receipts of those asked with a creationId
// (core/agents/launches.ts). The orchestrator and the cable create and fork through the socket's slots.
const launches = createLaunchRequests({
...(swarm ? { swarmLaunch: swarm.SWARM_LAUNCH } : {}),
claudeHomeOffered: (home) => claudeHomeOffered(home, machineIdNow()),
receipts: new AgentCreationReceipts(join(env.ADAPTER_DATA_DIR, 'agent-creations')),
createAgent: () => backend.onCreateAgent, forkAgent: () => backend.onForkAgent,
prepareCreate: creator.prepare, prepareEngine: prepareNativeLaunch,
resumeAgent: () => lifecycle.resumeAgent, restartAgent: () => restartAgent,
byAgent: (id) => registry.byAgent(id), stoppedAgent: (id) => stoppedAgents.get(id) ?? undefined, toProject: (s) => backend.toProject(s),
modelTarget: (selection) => (ports.models ?? MODELS_OFF).launchTarget(selection),
// A guest's New Harness: built by shared machines, as the guest's own OS user (core/agents/guestCreate.ts).
guestCreate: () => guestCreate,
})
// A cloud agent is made by its service (core/agents/cloud.ts); every other engine launches here.
// Answered when the service answers, never in the connection's line: the window's next requests go on.
backend.createProvider = async (payload, asker, answer) => {
const made = cloud.create(payload)
if (made) void made.then(answer)
else await launches.create(payload, asker, answer)
}
backend.createStatusProvider = launches.createStatus
backend.cancelCreateProvider = launches.cancelCreate
backend.restartProvider = launches.relaunch
backend.forkProvider = launches.fork
const submitAgent = inputs.submitAgent
// Words for a cloud harness go to its service, and a delivery among them is settled as the pane's are.
backend.onMessage = (id, content, deliveryId) => {
// An Agent Messages turn its mailbox no longer wants written waits, as a pane's does (core/input.ts).
if (cloud.owns(id) && deliveryId?.startsWith('team:') && !(ports.messages?.canWrite(deliveryId) ?? false)) {
deliveries.settled({ deliveryId, sessionId: id, state: 'rejected', reason: 'team_waiting_control' })
return
}
const sent = cloud.deliver(id, content)
if (!sent) { submitAgent(id, content, deliveryId); return }
if (deliveryId) void sent.then((result) => deliveries.settled({ deliveryId, sessionId: id, state: result.ok ? 'delivered' : 'rejected', ...(result.ok ? {} : { reason: result.error }) }))
}
backend.messageProvider = (payload, receipt) => {
const agentId = typeof payload.agentId === 'string' ? payload.agentId : typeof payload.sessionId === 'string' ? payload.sessionId : ''
if (cloud.owns(agentId)) { void cloud.deliver(agentId, typeof payload.content === 'string' ? payload.content : ''); return }
inputs.messageRequest(payload, receipt)
}
backend.onCancelOrchestratorMessage = id => input.cancelDelivery(id)
deliveries.ready() // The input is wired: what was delivered meanwhile (Agent Messages' queue resuming) is written now.
// Keep the log file under its cap. This daemon writes it through an inherited stdout fd, so a size
// check on a timer is the only place that can see it grow — `prepareLogFile` at spawn time alone
// would let a long-lived, chatty daemon run unbounded between restarts.
// A core run by harnessd leaves this to its master, which outlives it (harnessd/master.ts).
const logTrimTimer = coreLink.supervised ? undefined : setInterval(() => {
if (trimLogFile(LOG_FILE)) console.log(`[log] ${tildify(LOG_FILE)} hit its size cap — dropped the oldest half`)
}, LOG_CHECK_INTERVAL_MS)
logTrimTimer?.unref?.() // never hold the event loop open for log upkeep
// Signed out, the backend is not dialed at all. The socket would only meet a missing session and back
// off forever, one log line at a time; a sign-in RESTARTS this process with the session in hand
// (`restartDaemonForIdentity`), so nothing here has to watch for one arriving.
if (session) {
backend.connect()
console.log(`[cli] dialing ${env.BACKEND_WS_URL}/api/adapter-ws · watching registered sessions for ${ENGINES.length} engines`)
} else {
backend.serveThisComputerOnly()
console.log(`[cli] not signed in — serving this computer only · watching registered sessions for ${ENGINES.length} engines`)
}
// ── self-update: a staged bundle restarts the daemon IMMEDIATELY (core/updateHandoff.ts). The handler
// stops being `bootHandoff` HERE, and not a line earlier: everything the teardown releases exists by now.
// A straight-line assignment, never a wait: if the body never reaches this line the handler stays
// `bootHandoff`, and the fix still lands.
const updateTeardown = (): TeardownStep[] => { heldLaunches.close(); installedHooks?.close(); externalResumes?.stop(); launches.stop(); return [
['the registry', () => registry.flush({ exiting: true })], ['the updater', () => daemonBoot.updaterBeside?.()],
['the reconciler', () => agentReconciler.stop()],
// The connection alone: the host and its panes stay up for the successor to reattach.
['the pty host connection', () => { ptyHostBackend?.dispose(); ptyDrain?.dispose() }],
['the timers', () => { clearInterval(logTrimTimer); clearInterval(runtimeReconcileTimer); clearInterval(paneTitleSyncTimer) }],
['the question watchers', () => questionWatcher.stopAll()],
['the turn heartbeats', () => { for (const t of heartbeats.values()) clearInterval(t); heartbeats.clear() }],
['the Cursor sub-agents', () => cursorSubagents.stop()], ['the normalizers', () => normalizers.stopPollers()],
['Cursor discovery', () => cursorDiscovery.stop()], ['the runtime profiles', () => runtimeProfiles.stop()], ['the transcript watcher', () => watcher.stop()],
// The FIXED hook port, released before the successor binds it (no fallback → EADDRINUSE otherwise).
// Process-owned agents stay in the persisted registry and are revalidated by its first discovery passes.
['the hook connections', () => (hookServer as unknown as { closeAllConnections?: () => void }).closeAllConnections?.()],
['Share', () => ports.sharing?.stop()],
['the local websocket', () => localWsServer.close()], ['the hook server', () => hookServer.close()],
// The claim just before the socket: a successor that saw the socket go must find the folder free.
['the data folder claim', () => dataFolderClaim?.release()], ['the local socket', () => localSocket?.close()],
['Codex activity', () => nativeControls.close()],
// The serial ports, the lane and the voice router's worker: a port held through the handoff makes the
// next daemon's dial, and esptool, fail as if the hardware had died.
['the devices', () => ports.devices?.stop()],
// The successor starts its own viewers for the agents it restores; ours must not hold the ports.
['external adoption', () => externalResumes?.stop()],
['usage observations', () => { usageLink.port.stop(); ports.usage?.stop() }],
['the viewers', () => ports.viewers?.stop()], ['the gateway', () => gateway.stop()],
// A graceful close releases the backend's one-machine claim, given a moment before the reclaim.
['the backend', () => backend.stop()], ['a grace', () => new Promise((r) => setTimeout(r, 1000))],
] }
daemonBoot.applyStagedUpdate = (v) => updateHandoff.restartForUpdate(v, updateTeardown())
// A core an older release's own handoff started (it spawned this `cli.js __run` and judged it) has no
// master, and so no updater: it would run this build until its next start. Once that release has gone,
// it hands the machine to a master on this build (core/updateHandoff.ts). Not a core HARNESS_NO_MASTER=1
// asked for, and not a dev or repo run.
if (!coreLink.supervised && process.env.ADAPTER_UPDATED_TO && process.env.HARNESS_NO_MASTER !== '1' && isInstalledCopy(SCRIPT_PATH, env.ADAPTER_CLI_DIR)) {
handOverOnceReleased({ startedBy: process.ppid, parent: () => process.ppid, alive: isAlive, handOver: () => { void updateHandoff.handOver(updateTeardown()) } })
}
/** Stopping for good — removed from the account, or connected from elsewhere: tell harnessd's master,
* which restarts any other exit (harnessd/protocol.ts). */
const shutdown = async (signal: string): Promise<void> => {
heldLaunches.close()
installedHooks?.close()
externalResumes?.stop()
launches.stop()
console.log(`\n[cli] ${signal} — shutting down`)
// A slow teardown may exhaust the master's grace. Persist already acknowledged bindings first.
registry.flush({ exiting: true })
const leave = (): never => {
try { if (readPid() === process.pid) rmSync(PID_FILE, { force: true }) } catch { /* ignore */ }
process.exit(coreLink.supervised && stopsForGood(signal) ? CORE_EXIT_STOP : 0)
}
// A core with no master keeps the master's grace on itself (core/stopDeadline.ts).
const deadline = stopDeadline({ supervised: coreLink.supervised, exit: leave, log: (line) => console.log(line) })
// Mid-handoff everything below is already being torn down, and nothing has been started yet: leave
// — a second teardown of closed servers is noise.
if (updateHandoff.restarting()) {
try { if (readPid() === process.pid) rmSync(PID_FILE, { force: true }) } catch { /* ignore */ }
process.exit(0)
}
// Release the serial port first. It is exclusive, and a daemon that exits still holding it makes
// esptool fail in a way that reads exactly like dead hardware.
void ports.devices?.stop()
daemonBoot.updaterBeside?.()
agentReconciler.stop()
ptyHostBackend?.dispose()
ptyDrain?.dispose()
clearInterval(logTrimTimer)
clearInterval(runtimeReconcileTimer)
clearInterval(paneTitleSyncTimer)
questionWatcher.stopAll()
for (const t of heartbeats.values()) clearInterval(t)
heartbeats.clear()
cursorSubagents.stop()
normalizers.stopPollers()
deadline.at('Cursor discovery')
await cursorDiscovery.stop()
deadline.at('the transcript watcher')
await watcher.stop()
runtimeProfiles.stop()
deadline.at('Share')
await ports.sharing?.stop()
// The data folder's socket first: a successor waiting for this core to leave (lib/localSocket.ts) can
// start as soon as it is gone, whatever the clients below take to close.
deadline.at('the local socket')
dataFolderClaim?.release()
await localSocket?.close()
deadline.at('the local websocket')
await localWsServer.close()
hookServer.close()
nativeControls.close()
externalResumes?.stop()
usageLink.port.stop(); ports.usage?.stop()
deadline.at('the viewers')
await ports.viewers?.stop()
deadline.at('the gateway')
await gateway.stop()
deadline.at('the backend')
await backend.stop()
leave()
}
daemonBoot.stopHere = (why) => void shutdown(why)
process.on('SIGINT', () => void shutdown('SIGINT'))
process.on('SIGTERM', () => void shutdown('SIGTERM'))
// Swarm v3 has no Team accounts: a Team account's daemon stops for good after a pass finds no agent running in it, an
// engine or a pane (superTabs/inCore/teamRetire.ts).
if (swarm) {
afterAgentsPass = swarm.teamRetirement({ teamAccount: swarm.isTeamAccount(), log: (line) => console.log(line),
live: () => registry.list().filter((session) => session.active || registry.terminalAvailable(session.agentId)).length,
stop: (reason) => void shutdown(reason) })
}
// A core whose master is gone stops, so nothing is left holding the port for a master that is not
// there to restart it.
coreLink.onMasterGone(() => void shutdown('the harnessd master is gone'))
// Windows: the master's stop is a message (harnessd/protocol.ts `harnessd:shutdown`), never a signal.
coreLink.onShutdown(() => void shutdown('the harnessd master asked this core to stop'))
// A machine revocation, a 401/403 on the backend link, or a refused SSO refresh ends this signed-in
// session: the daemon stops and comes back signed out. The sign-in is kept, marked signed out, and nothing
// reads it again until a new sign-in replaces it. 10-27: a sign-out nobody asked for stalled a whole Mac;
// only a person deletes it (lib/signOut.ts).
backend.onRevoked = () => {
console.log('[cli] this computer\'s sign-in was revoked or refused — signed out, keeping it until a new sign-in, and stopping')
// The web-tools cache lives exactly as long as the sign-in. `harness logout` and `reset` stop
// the daemon outright; this is the one sign-out the daemon learns of from inside.
ports.models?.signedOut()
swarmDoors?.cards.reset()
// Marked before the stop: the core that comes back must read it as signed out. The mark waits for a
// refresh another process has under way, so that refresh's save cannot write over it.
void markSignedOut('revoked')
.catch((error: unknown) => console.log(`[cli] could not mark the sign-in signed out (${error instanceof Error ? error.message : String(error)})`))
.finally(() => void shutdown('revoked'))
}
// Mirror the machine's display name to disk so `harness status` (a separate process) can print it.
backend.onMachineMeta = (name) => {
try {
if (name) writeFileSync(MACHINE_NAME_FILE, name + '\n')
else rmSync(MACHINE_NAME_FILE, { force: true })
} catch { /* best effort */ }
}
// This machine is already connected from ANOTHER machine (HTTP 409). The credential is valid — it's
// just in use elsewhere — so KEEP the token and stop (no retry loop, no token prompt). The
// '[backend] machine busy' marker is what the detached parent's waitForReady() greps for.
backend.onBusy = () => {
console.log('[backend] machine busy — this machine is already connected from another computer; stopping')
void shutdown('busy')
}
// ── the devices (services/devices.ts) ──────────────────────────────────────────────────────────────
//
// The dials on USB, the window bridges they speak through, the fleet's router every turn goes through
// (⌘K's too) with the lane to the owner's other machines, the voice router and the Devices tab. Behind
// their port: a device that fails costs the devices, never a session. Deliberately not fatal and not
// blocking: an unplugged cable is this daemon's ordinary state.
// In their own process they are told everything the windows said as they connect (core/devicesLink.ts):
// said here too, it reached a dial still opening its port, before its greeting.
// The Swarm cards the Super Tab service sent before this line had no devices to reach: they are shown now.
// A Harness Team daemon runs neither the dials nor the Wi-Fi device: every card goes to them before the Team guard could
// filter it (security re-check 1 of #2089).
if (teamDaemon) { /* no devices */ } else if (outOfProcess.has('devices')) { ports.devices = devicesLink.port; swarmDoors?.cards.replay() }
else {
serviceHost.start('devices', (core, started) => inline!.startDevices(core, started, {
logsDir: env.HARNESS_LOGS_DIR, testDialPort: harnessd.HARNESSD_TEST_DIAL_PORT,
dialSerials: process.env.HARNESS_DIAL_SERIALS?.split(',').map((serial) => serial.trim()).filter(Boolean),
cableDisabled: env.CABLE_DISABLE, faults: testFaults(harnessd.HARNESSD_TEST_FAULTS),
}), coreApi, DEVICES_FALLBACKS, DEVICES_REQUESTS)
// Everything the windows said while the devices were being built, and what the machine runs.
if (ports.devices) devicesLink.started(ports.devices)
}
// The Wi-Fi device (services/wifi.ts), with the dials: in their process by default (core/wifiLink.ts,
// resumed there as its link connects), or here.
if (!teamDaemon && !outOfProcess.has('wifi')) {
serviceHost.start('wifi', inline!.startWifi, coreApi, WIFI_FALLBACKS)
if (ports.wifi) wifiCore.started(appVoiceFocus ?? null)
}
devicePartsBuilt = true
// Worktrees Harness made that no live or stopped harness uses and nothing would miss
// (services/workspaces.ts): a few minutes after start, once restored agents are back in the
// registry, then twice a day. Only the end-to-end harness shortens the first wait.
setTimeout(() => ports.workspaces?.sweepUnused(), Number(harnessd.HARNESSD_TEST_SWEEP_AFTER_MS) || 5 * 60_000).unref()
setInterval(() => ports.workspaces?.sweepUnused(), 12 * 3600_000).unref()
// Every card bound for the Wi-Fi device goes to the devices too: the dial is told what the Wi-Fi device is,
// in the same order, so the two device surfaces cannot drift. Teeing beats emitting again at each call
// site: a new kind of card reaches the dial the day it reaches the socket. The tee runs before the frame
// is queued for the Wi-Fi device (BackendSocket.sendCommander): a device fault here must cost neither
// that frame nor whoever is sending it, which the guards and the devices' port see to.
// Not on a Harness Team daemon: there it would hand every card to the dials and the Wi-Fi device past the Team guard.
if (!teamDaemon) backend.onOutboundCommander = (frame) => {
const card = frame as Record<string, unknown>
// The Pro's extras ride to the devices alone: the Wi-Fi device gets the card as it always did, and a
// summary reaches the dial with the turn's whole answer, as it does the Wi-Fi device.
if (!isLocalOnly(card)) wifiCore.card(withoutUpdate(card))
const payload = card.payload as Record<string, unknown> | undefined
const full = card.type === 'commander_event' && payload?.kind === 'summary' && typeof card.agentId === 'string'
? mirror.lastFullText(registry.byAgent(card.agentId)?.sessionId ?? card.agentId) ?? cloudAgents?.said(card.agentId) : undefined
// An engine's question takes the place of a Super Tab wait on the devices, which shows again once it closes.
swarmDoors?.waits.before(card)
ports.devices?.card(full ? { ...card, payload: { ...payload, fullText: full } } : card)
swarmDoors?.waits.after(card)
}
// Last: every handler is wired and the restored agents are confirmed, so requests that arrived while
// starting — a client reconnecting the moment the port answered, the backend's first frames — are
// answered now, in order, by the handlers meant to answer them (see BackendSocket.openRequests).
// Only the end-to-end harness sets this: a start-up that hangs after binding, for the master's deadline.
if (harnessd.HARNESSD_TEST_HOLD_READY === '1') await new Promise<never>(() => {})
// A terminal host on probation is judged by this ready: a host whose version answers may still fail to serve (its
// conpty.dll, its endpoint), and kept, every new pane would fail on it. Not ready until the create backend is attached
// to the target's host; never, if it cannot be, and the master's ready timeout rolls the host back (lib/ptyHost/drain.ts).
if (ptyHosts && coreLink.supervised && ptyHostOnProbation(env.ADAPTER_RUNTIME_DIR)) {
const create = ptyHosts.create
await untilHostAttached(() => ptyTarget !== null && createBackend === create && create.attached, ptyTarget?.instance ?? null, (line) => console.log(line))
}
backend.openRequests()
daemonBoot.openRequests = null
coreLink.ready()
console.log('[cli] ready')
// Each launch confirms its own hooks. Startup never waits on any vendor's disk or probe.
installedHooks = env.DISABLE_HOOK_INSTALL ? undefined
: installEngineHooks(hookPort, { only: env.HOOK_INSTALL_ENGINES, loginShell: loginShellEnvPromise })
// Ready first, never after a service: the agents the boot held for one are launched now, in the background.
void heldLaunches.restoreHeld()
externalResumes.open()
launches.open()
}
/**
* The daemon's start-up threw. STAY UP anyway, waiting for a fix.
*
* Exiting here is what made one bad build unrecoverable: the desktop app answers a dead port by running
* `harness start` again — the same bytes, about once a minute, for ever. The updater is the master's, in a
* process of its own (services/updaterProcess.ts), and the request to hand over for its fix is listened for
* in the prologue (see `runForeground`); all this has to do is keep the process alive long enough for a
* published fix to land, and tell everyone what state the machine is in. A core with no master gets no fix
* here: its safe mode runs out (`ADAPTER_SAFE_MODE_MS`) and a clean start tries again.
*
* Three ways it earns its keep, in order: the bound control port answers `discoveryReady: false`, so
* the app reads the machine as not-ready instead of dead and STOPS respawning; the pid file stays
* ours, so `harness start` is a cheap no-op rather than a zombie factory; and the marker file lets
* `harness status` say what happened. `harness stop` still works throughout: by signal on a Mac or Linux; on Windows
* over its pipe (`daemonBoot.stopHere`, or its master's `harnessd:shutdown`), then by verified pid (lib/daemonStop.ts).
*/
const enterSafeMode = (err: unknown): void => {
const disposition = safeModeDisposition(err, { selfPid: process.pid, masterPid: coreLink.masterPid, readPid, isAlive })
if (!disposition.stay) {
console.error(`[safe-mode] not staying up — ${disposition.reason}`)
// Under harnessd, said for good: any other exit, the master restarts, and a core that another daemon
// keeps from running was restarted for as long as its master lived (e2e/twodaemons.e2e.ts). Except
// what stands in the way is leaving too: then the master starts this core again.
onError(err, coreLink.supervised && !disposition.retry ? CORE_EXIT_STOP : 1)
}
const detail = err instanceof Error ? (err.stack ?? err.message) : String(err)
console.error('Failed to start adapter:', err)
console.error(`[safe-mode] staying up on v${VERSION} — a published fix will be applied on its own.`
+ ' Nothing else on this machine works until then.')
writeSafeModeMarker(env.ADAPTER_DATA_DIR, { pid: process.pid, version: VERSION, at: Date.now(), error: detail })
daemonBoot.safeMode = disposition.reason
daemonBoot.markNotReady?.(disposition.reason)
// Requests queued behind a start-up that will not finish are answered now, by whatever is wired.
daemonBoot.openRequests?.()
const leave = (why: string, code: number): never => {
clearSafeModeMarker(env.ADAPTER_DATA_DIR)
removePidFileIf(process.pid)
console.log(`[safe-mode] ${why}`)
process.exit(code)
}
process.on('SIGINT', () => leave('SIGINT — leaving safe mode', 0))
process.on('SIGTERM', () => leave('SIGTERM — leaving safe mode', 0))
// `harness stop` on Windows, for a core no master runs: safe mode's own leave, which clears its marker too.
daemonBoot.stopHere = (why) => leave(`${why} — leaving safe mode`, 0)
// Up, though not ready: the master must neither give up waiting for a bind nor take it for hung, or the
// fix its updater stages would find no core to hand over. It hears why, and rolls back an
// update whose first core ends up here.
coreLink.bound(daemonPort())
coreLink.ready(disposition.reason)
coreLink.startHeartbeat()
coreLink.onMasterGone(() => leave('the harnessd master is gone — leaving safe mode', 0))
coreLink.onShutdown(() => leave('the harnessd master asked this core to stop — leaving safe mode', 0))
// The bound control port is a ref'd handle and holds the loop on its own. Without one — the bind
// itself was what failed, or we never got that far — take the port for the status alone, so the app
// still reads not-ready rather than down. A port we cannot take at all leaves only a ticking clock.
if (!daemonBoot.hookServer) {
const port = daemonPort()
const hosts = loopbackHosts(port)
const status = createServer((req, res) => {
if (!isLoopbackRequest(req, hosts)) { res.writeHead(403).end(); return }
const body = safeModeStatusBody({
version: VERSION, pid: process.pid, startedAt: Date.now(),
computerId: computerId(), error: disposition.reason,
})
res.writeHead(200, { 'content-type': 'application/json' })
res.end(JSON.stringify(body))
})
status.on('error', (e) => {
console.error(`[safe-mode] could not serve status on ${port}: ${e instanceof Error ? e.message : e}`)
// A ref'd timer: something has to hold the event loop open.
setInterval(() => console.log(`[safe-mode] still waiting for a fixed build · v${VERSION}`), 10 * 60_000)
})
status.listen(port, '127.0.0.1')
}
// Bounded on purpose. A cause that has since cleared — tmux not yet on PATH after a reboot, a lock
// file, a port held for a moment — would otherwise leave the machine wedged in a state nobody
// respawns over, because not-ready is exactly what stops the app trying again.
// Counted in AWAKE time: a plain timer spent a closed lid on this clock and exited the daemon on the
// first loop turn after the wake, taking every local terminal with it (see lib/sleepAware.ts).
if (env.ADAPTER_SAFE_MODE_MS > 0) {
awakeTimeout(() => leave(`no fix arrived within ${Math.round(env.ADAPTER_SAFE_MODE_MS / 60_000)}m — letting a clean start try`, 1),
env.ADAPTER_SAFE_MODE_MS)
}
}
/** `harness __run`: the core, as harnessd's master (or `harness start` without one) spawns it. */
export function runCore(scriptPath: string): void {
// First, before anything this core starts can inherit them: a tmux server, an engine, a shell
// (lib/harnessdEnv.ts).
holdHarnessdEnv()
dropAgentSessionEnv()
SCRIPT_PATH = scriptPath
// Inert unless the end-to-end suite asks for its event loop to be held (core/stall.ts).
startStalls(testFaults(harnessdEnv().HARNESSD_TEST_FAULTS))
// NOT `onError`: a daemon that dies here can never be updated. See `enterSafeMode`.
runForeground(readAuthSession()).catch(enterSafeMode)
}
/** `harness start -f` with `HARNESS_NO_MASTER=1`, and a start under tsx: the core alone, in the process of the command that asked for it. */
export function runCoreInForeground(session: AuthSession | null, scriptPath: string): Promise<void> {
holdHarnessdEnv()
dropAgentSessionEnv()
SCRIPT_PATH = scriptPath
return runForeground(session)
}