Something went wrong. Try again.
source dump of claude code forked from oppi.li/claude-code
Something went wrong. Try again.
116 kB · 2999 lines
TypeScript
at main
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000import { feature } from 'bun:bundle'import { randomUUID } from 'crypto'import { hostname, tmpdir } from 'os'import { basename, join, resolve } from 'path'import { getRemoteSessionUrl } from '../constants/product.js'import { shutdownDatadog } from '../services/analytics/datadog.js'import { shutdown1PEventLogging } from '../services/analytics/firstPartyEventLogger.js'import { checkGate_CACHED_OR_BLOCKING } from '../services/analytics/growthbook.js'import { type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, logEvent, logEventAsync,} from '../services/analytics/index.js'import { isInBundledMode } from '../utils/bundledMode.js'import { logForDebugging } from '../utils/debug.js'import { logForDiagnosticsNoPII } from '../utils/diagLogs.js'import { isEnvTruthy, isInProtectedNamespace } from '../utils/envUtils.js'import { errorMessage } from '../utils/errors.js'import { truncateToWidth } from '../utils/format.js'import { logError } from '../utils/log.js'import { sleep } from '../utils/sleep.js'import { createAgentWorktree, removeAgentWorktree } from '../utils/worktree.js'import { BridgeFatalError, createBridgeApiClient, isExpiredErrorType, isSuppressible403, validateBridgeId,} from './bridgeApi.js'import { formatDuration } from './bridgeStatusUtil.js'import { createBridgeLogger } from './bridgeUI.js'import { createCapacityWake } from './capacityWake.js'import { describeAxiosError } from './debugUtils.js'import { createTokenRefreshScheduler } from './jwtUtils.js'import { getPollIntervalConfig } from './pollConfig.js'import { toCompatSessionId, toInfraSessionId } from './sessionIdCompat.js'import { createSessionSpawner, safeFilenameId } from './sessionRunner.js'import { getTrustedDeviceToken } from './trustedDevice.js'import { BRIDGE_LOGIN_ERROR, type BridgeApiClient, type BridgeConfig, type BridgeLogger, DEFAULT_SESSION_TIMEOUT_MS, type SessionDoneStatus, type SessionHandle, type SessionSpawner, type SessionSpawnOpts, type SpawnMode,} from './types.js'import { buildCCRv2SdkUrl, buildSdkUrl, decodeWorkSecret, registerWorker, sameSessionId,} from './workSecret.js'
export type BackoffConfig = { connInitialMs: number connCapMs: number connGiveUpMs: number generalInitialMs: number generalCapMs: number generalGiveUpMs: number /** SIGTERM→SIGKILL grace period on shutdown. Default 30s. */ shutdownGraceMs?: number /** stopWorkWithRetry base delay (1s/2s/4s backoff). Default 1000ms. */ stopWorkBaseDelayMs?: number}
const DEFAULT_BACKOFF: BackoffConfig = { connInitialMs: 2_000, connCapMs: 120_000, // 2 minutes connGiveUpMs: 600_000, // 10 minutes generalInitialMs: 500, generalCapMs: 30_000, generalGiveUpMs: 600_000, // 10 minutes}
/** Status update interval for the live display (ms). */const STATUS_UPDATE_INTERVAL_MS = 1_000const SPAWN_SESSIONS_DEFAULT = 32
/** * GrowthBook gate for multi-session spawn modes (--spawn / --capacity / --create-session-in-dir). * Sibling of tengu_ccr_bridge_multi_environment (multiple envs per host:dir) — * this one enables multiple sessions per environment. * Rollout staged via targeting rules: ants first, then gradual external. * * Uses the blocking gate check so a stale disk-cache miss doesn't unfairly * deny access. The fast path (cache has true) is still instant; only the * cold-start path awaits the server fetch, and that fetch also seeds the * disk cache for next time. */async function isMultiSessionSpawnEnabled(): Promise<boolean> { return checkGate_CACHED_OR_BLOCKING('tengu_ccr_bridge_multi_session')}
/** * Returns the threshold for detecting system sleep/wake in the poll loop. * Must exceed the max backoff cap — otherwise normal backoff delays trigger * false sleep detection (resetting the error budget indefinitely). Using * 2× the connection backoff cap, matching the pattern in WebSocketTransport * and replBridge. */function pollSleepDetectionThresholdMs(backoff: BackoffConfig): number { return backoff.connCapMs * 2}
/** * Returns the args that must precede CLI flags when spawning a child claude * process. In compiled binaries, process.execPath is the claude binary itself * and args go directly to it. In npm installs (node running cli.js), * process.execPath is the node runtime — the child spawn must pass the script * path as the first arg, otherwise node interprets --sdk-url as a node option * and exits with "bad option: --sdk-url". See anthropics/claude-code#28334. */function spawnScriptArgs(): string[] { if (isInBundledMode() || !process.argv[1]) { return [] } return [process.argv[1]]}
/** Attempt to spawn a session; returns error string if spawn throws. */function safeSpawn( spawner: SessionSpawner, opts: SessionSpawnOpts, dir: string,): SessionHandle | string { try { return spawner.spawn(opts, dir) } catch (err) { const errMsg = errorMessage(err) logError(new Error(`Session spawn failed: ${errMsg}`)) return errMsg }}
export async function runBridgeLoop( config: BridgeConfig, environmentId: string, environmentSecret: string, api: BridgeApiClient, spawner: SessionSpawner, logger: BridgeLogger, signal: AbortSignal, backoffConfig: BackoffConfig = DEFAULT_BACKOFF, initialSessionId?: string, getAccessToken?: () => string | undefined | Promise<string | undefined>,): Promise<void> { // Local abort controller so that onSessionDone can stop the poll loop. // Linked to the incoming signal so external aborts also work. const controller = new AbortController() if (signal.aborted) { controller.abort() } else { signal.addEventListener('abort', () => controller.abort(), { once: true }) } const loopSignal = controller.signal
const activeSessions = new Map<string, SessionHandle>() const sessionStartTimes = new Map<string, number>() const sessionWorkIds = new Map<string, string>() // Compat-surface ID (session_*) computed once at spawn and cached so // cleanup and status-update ticks use the same key regardless of whether // the tengu_bridge_repl_v2_cse_shim_enabled gate flips mid-session. const sessionCompatIds = new Map<string, string>() // Session ingress JWTs for heartbeat auth, keyed by sessionId. // Stored separately from handle.accessToken because the token refresh // scheduler overwrites that field with the OAuth token (~3h55m in). const sessionIngressTokens = new Map<string, string>() const sessionTimers = new Map<string, ReturnType<typeof setTimeout>>() const completedWorkIds = new Set<string>() const sessionWorktrees = new Map< string, { worktreePath: string worktreeBranch?: string gitRoot?: string hookBased?: boolean } >() // Track sessions killed by the timeout watchdog so onSessionDone can // distinguish them from server-initiated or shutdown interrupts. const timedOutSessions = new Set<string>() // Sessions that already have a title (server-set or bridge-derived) so // onFirstUserMessage doesn't clobber a user-assigned --name / web rename. // Keyed by compatSessionId to match logger.setSessionTitle's key. const titledSessions = new Set<string>() // Signal to wake the at-capacity sleep early when a session completes, // so the bridge can immediately accept new work. const capacityWake = createCapacityWake(loopSignal)
/** * Heartbeat all active work items. * Returns 'ok' if at least one heartbeat succeeded, 'auth_failed' if any * got a 401/403 (JWT expired — re-queued via reconnectSession so the next * poll delivers fresh work), or 'failed' if all failed for other reasons. */ async function heartbeatActiveWorkItems(): Promise< 'ok' | 'auth_failed' | 'fatal' | 'failed' > { let anySuccess = false let anyFatal = false const authFailedSessions: string[] = [] for (const [sessionId] of activeSessions) { const workId = sessionWorkIds.get(sessionId) const ingressToken = sessionIngressTokens.get(sessionId) if (!workId || !ingressToken) { continue } try { await api.heartbeatWork(environmentId, workId, ingressToken) anySuccess = true } catch (err) { logForDebugging( `[bridge:heartbeat] Failed for sessionId=${sessionId} workId=${workId}: ${errorMessage(err)}`, ) if (err instanceof BridgeFatalError) { logEvent('tengu_bridge_heartbeat_error', { status: err.status as unknown as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, error_type: (err.status === 401 || err.status === 403 ? 'auth_failed' : 'fatal') as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, }) if (err.status === 401 || err.status === 403) { authFailedSessions.push(sessionId) } else { // 404/410 = environment expired or deleted — no point retrying anyFatal = true } } } } // JWT expired → trigger server-side re-dispatch. Without this, work stays // ACK'd out of the Redis PEL and poll returns empty forever (CC-1263). // The existingHandle path below delivers the fresh token to the child. // sessionId is already in the format /bridge/reconnect expects: it comes // from work.data.id, which matches the server's EnvironmentInstance store // (cse_* under the compat gate, session_* otherwise). for (const sessionId of authFailedSessions) { logger.logVerbose( `Session ${sessionId} token expired — re-queuing via bridge/reconnect`, ) try { await api.reconnectSession(environmentId, sessionId) logForDebugging( `[bridge:heartbeat] Re-queued sessionId=${sessionId} via bridge/reconnect`, ) } catch (err) { logger.logError( `Failed to refresh session ${sessionId} token: ${errorMessage(err)}`, ) logForDebugging( `[bridge:heartbeat] reconnectSession(${sessionId}) failed: ${errorMessage(err)}`, { level: 'error' }, ) } } if (anyFatal) { return 'fatal' } if (authFailedSessions.length > 0) { return 'auth_failed' } return anySuccess ? 'ok' : 'failed' }
// Sessions spawned with CCR v2 env vars. v2 children cannot use OAuth // tokens (CCR worker endpoints validate the JWT's session_id claim, // register_worker.go:32), so onRefresh triggers server re-dispatch // instead — the next poll delivers fresh work with a new JWT via the // existingHandle path below. const v2Sessions = new Set<string>()
// Proactive token refresh: schedules a timer 5min before the session // ingress JWT expires. v1 delivers OAuth directly; v2 calls // reconnectSession to trigger server re-dispatch (CC-1263: without // this, v2 daemon sessions silently die at ~5h since the server does // not auto-re-dispatch ACK'd work on lease expiry). const tokenRefresh = getAccessToken ? createTokenRefreshScheduler({ getAccessToken, onRefresh: (sessionId, oauthToken) => { const handle = activeSessions.get(sessionId) if (!handle) { return } if (v2Sessions.has(sessionId)) { logger.logVerbose( `Refreshing session ${sessionId} token via bridge/reconnect`, ) void api .reconnectSession(environmentId, sessionId) .catch((err: unknown) => { logger.logError( `Failed to refresh session ${sessionId} token: ${errorMessage(err)}`, ) logForDebugging( `[bridge:token] reconnectSession(${sessionId}) failed: ${errorMessage(err)}`, { level: 'error' }, ) }) } else { handle.updateAccessToken(oauthToken) } }, label: 'bridge', }) : null const loopStartTime = Date.now() // Track all in-flight cleanup promises (stopWork, worktree removal) so // the shutdown sequence can await them before process.exit(). const pendingCleanups = new Set<Promise<unknown>>() function trackCleanup(p: Promise<unknown>): void { pendingCleanups.add(p) void p.finally(() => pendingCleanups.delete(p)) } let connBackoff = 0 let generalBackoff = 0 let connErrorStart: number | null = null let generalErrorStart: number | null = null let lastPollErrorTime: number | null = null let statusUpdateTimer: ReturnType<typeof setInterval> | null = null // Set by BridgeFatalError and give-up paths so the shutdown block can // skip the resume message (resume is impossible after env expiry/auth // failure/sustained connection errors). let fatalExit = false
logForDebugging( `[bridge:work] Starting poll loop spawnMode=${config.spawnMode} maxSessions=${config.maxSessions} environmentId=${environmentId}`, ) logForDiagnosticsNoPII('info', 'bridge_loop_started', { max_sessions: config.maxSessions, spawn_mode: config.spawnMode, })
// For ant users, show where session debug logs will land so they can tail them. // sessionRunner.ts uses the same base path. File appears once a session spawns. if (process.env.USER_TYPE === 'ant') { let debugGlob: string if (config.debugFile) { const ext = config.debugFile.lastIndexOf('.') debugGlob = ext > 0 ? `${config.debugFile.slice(0, ext)}-*${config.debugFile.slice(ext)}` : `${config.debugFile}-*` } else { debugGlob = join(tmpdir(), 'claude', 'bridge-session-*.log') } logger.setDebugLogPath(debugGlob) }
logger.printBanner(config, environmentId)
// Seed the logger's session count + spawn mode before any render. Without // this, setAttached() below renders with the logger's default sessionMax=1, // showing "Capacity: 0/1" until the status ticker kicks in (which is gated // by !initialSessionId and only starts after the poll loop picks up work). logger.updateSessionCount(0, config.maxSessions, config.spawnMode)
// If an initial session was pre-created, show its URL from the start so // the user can click through immediately (matching /remote-control behavior). if (initialSessionId) { logger.setAttached(initialSessionId) }
/** Refresh the inline status display. Shows idle or active depending on state. */ function updateStatusDisplay(): void { // Push the session count (no-op when maxSessions === 1) so the // next renderStatusLine tick shows the current count. logger.updateSessionCount( activeSessions.size, config.maxSessions, config.spawnMode, )
// Push per-session activity into the multi-session display. for (const [sid, handle] of activeSessions) { const act = handle.currentActivity if (act) { logger.updateSessionActivity(sessionCompatIds.get(sid) ?? sid, act) } }
if (activeSessions.size === 0) { logger.updateIdleStatus() return }
// Show the most recently started session that is still actively working. // Sessions whose current activity is 'result' or 'error' are between // turns — the CLI emitted its result but the process stays alive waiting // for the next user message. Skip updating so the status line keeps // whatever state it had (Attached / session title). const [sessionId, handle] = [...activeSessions.entries()].pop()! const startTime = sessionStartTimes.get(sessionId) if (!startTime) return
const activity = handle.currentActivity if (!activity || activity.type === 'result' || activity.type === 'error') { // Session is between turns — keep current status (Attached/titled). // In multi-session mode, still refresh so bullet-list activities stay current. if (config.maxSessions > 1) logger.refreshDisplay() return }
const elapsed = formatDuration(Date.now() - startTime)
// Build trail from recent tool activities (last 5) const trail = handle.activities .filter(a => a.type === 'tool_start') .slice(-5) .map(a => a.summary)
logger.updateSessionStatus(sessionId, elapsed, activity, trail) }
/** Start the status display update ticker. */ function startStatusUpdates(): void { stopStatusUpdates() // Call immediately so the first transition (e.g. Connecting → Ready) // happens without delay, avoiding concurrent timer races. updateStatusDisplay() statusUpdateTimer = setInterval( updateStatusDisplay, STATUS_UPDATE_INTERVAL_MS, ) }
/** Stop the status display update ticker. */ function stopStatusUpdates(): void { if (statusUpdateTimer) { clearInterval(statusUpdateTimer) statusUpdateTimer = null } }
function onSessionDone( sessionId: string, startTime: number, handle: SessionHandle, ): (status: SessionDoneStatus) => void { return (rawStatus: SessionDoneStatus): void => { const workId = sessionWorkIds.get(sessionId) activeSessions.delete(sessionId) sessionStartTimes.delete(sessionId) sessionWorkIds.delete(sessionId) sessionIngressTokens.delete(sessionId) const compatId = sessionCompatIds.get(sessionId) ?? sessionId sessionCompatIds.delete(sessionId) logger.removeSession(compatId) titledSessions.delete(compatId) v2Sessions.delete(sessionId) // Clear per-session timeout timer const timer = sessionTimers.get(sessionId) if (timer) { clearTimeout(timer) sessionTimers.delete(sessionId) } // Clear token refresh timer tokenRefresh?.cancel(sessionId) // Wake the at-capacity sleep so the bridge can accept new work immediately capacityWake.wake()
// If the session was killed by the timeout watchdog, treat it as a // failed session (not a server/shutdown interrupt) so we still call // stopWork and archiveSession below. const wasTimedOut = timedOutSessions.delete(sessionId) const status: SessionDoneStatus = wasTimedOut && rawStatus === 'interrupted' ? 'failed' : rawStatus const durationMs = Date.now() - startTime
logForDebugging( `[bridge:session] sessionId=${sessionId} workId=${workId ?? 'unknown'} exited status=${status} duration=${formatDuration(durationMs)}`, ) logEvent('tengu_bridge_session_done', { status: status as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, duration_ms: durationMs, }) logForDiagnosticsNoPII('info', 'bridge_session_done', { status, duration_ms: durationMs, })
// Clear the status display before printing final log logger.clearStatus() stopStatusUpdates()
// Build error message from stderr if available const stderrSummary = handle.lastStderr.length > 0 ? handle.lastStderr.join('\n') : undefined let failureMessage: string | undefined
switch (status) { case 'completed': logger.logSessionComplete(sessionId, durationMs) break case 'failed': // Skip failure log during shutdown — the child exits non-zero when // killed, which is expected and not a real failure. // Also skip for timeout-killed sessions — the timeout watchdog // already logged a clear timeout message. if (!wasTimedOut && !loopSignal.aborted) { failureMessage = stderrSummary ?? 'Process exited with error' logger.logSessionFailed(sessionId, failureMessage) logError(new Error(`Bridge session failed: ${failureMessage}`)) } break case 'interrupted': logger.logVerbose(`Session ${sessionId} interrupted`) break }
// Notify the server that this work item is done. Skip for interrupted // sessions — interrupts are either server-initiated (the server already // knows) or caused by bridge shutdown (which calls stopWork() separately). if (status !== 'interrupted' && workId) { trackCleanup( stopWorkWithRetry( api, environmentId, workId, logger, backoffConfig.stopWorkBaseDelayMs, ), ) completedWorkIds.add(workId) }
// Clean up worktree if one was created for this session const wt = sessionWorktrees.get(sessionId) if (wt) { sessionWorktrees.delete(sessionId) trackCleanup( removeAgentWorktree( wt.worktreePath, wt.worktreeBranch, wt.gitRoot, wt.hookBased, ).catch((err: unknown) => logger.logVerbose( `Failed to remove worktree ${wt.worktreePath}: ${errorMessage(err)}`, ), ), ) }
// Lifecycle decision: in multi-session mode, keep the bridge running // after a session completes. In single-session mode, abort the poll // loop so the bridge exits cleanly. if (status !== 'interrupted' && !loopSignal.aborted) { if (config.spawnMode !== 'single-session') { // Multi-session: archive the completed session so it doesn't linger // as stale in the web UI. archiveSession is idempotent (409 if already // archived), so double-archiving at shutdown is safe. // sessionId arrived as cse_* from the work poll (infrastructure-layer // tag). archiveSession hits /v1/sessions/{id}/archive which is the // compat surface and validates TagSession (session_*). Re-tag — same // UUID underneath. trackCleanup( api .archiveSession(compatId) .catch((err: unknown) => logger.logVerbose( `Failed to archive session ${sessionId}: ${errorMessage(err)}`, ), ), ) logForDebugging( `[bridge:session] Session ${status}, returning to idle (multi-session mode)`, ) } else { // Single-session: coupled lifecycle — tear down environment logForDebugging( `[bridge:session] Session ${status}, aborting poll loop to tear down environment`, ) controller.abort() return } }
if (!loopSignal.aborted) { startStatusUpdates() } } }
// Start the idle status display immediately — unless we have a pre-created // session, in which case setAttached() already set up the display and the // poll loop will start status updates when it picks up the session. if (!initialSessionId) { startStatusUpdates() }
while (!loopSignal.aborted) { // Fetched once per iteration — the GrowthBook cache refreshes every // 5 min, so a loop running at the at-capacity rate picks up config // changes within one sleep cycle. const pollConfig = getPollIntervalConfig()
try { const work = await api.pollForWork( environmentId, environmentSecret, loopSignal, pollConfig.reclaim_older_than_ms, )
// Log reconnection if we were previously disconnected const wasDisconnected = connErrorStart !== null || generalErrorStart !== null if (wasDisconnected) { const disconnectedMs = Date.now() - (connErrorStart ?? generalErrorStart ?? Date.now()) logger.logReconnected(disconnectedMs) logForDebugging( `[bridge:poll] Reconnected after ${formatDuration(disconnectedMs)}`, ) logEvent('tengu_bridge_reconnected', { disconnected_ms: disconnectedMs, }) }
connBackoff = 0 generalBackoff = 0 connErrorStart = null generalErrorStart = null lastPollErrorTime = null
// Null response = no work available in the queue. // Add a minimum delay to avoid hammering the server. if (!work) { // Use live check (not a snapshot) since sessions can end during poll. const atCap = activeSessions.size >= config.maxSessions if (atCap) { const atCapMs = pollConfig.multisession_poll_interval_ms_at_capacity // Heartbeat loops WITHOUT polling. When at-capacity polling is also // enabled (atCapMs > 0), the loop tracks a deadline and breaks out // to poll at that interval — heartbeat and poll compose instead of // one suppressing the other. We break out to poll when: // - Poll deadline reached (atCapMs > 0 only) // - Auth fails (JWT expired → poll refreshes tokens) // - Capacity wake fires (session ended → poll for new work) // - Loop aborted (shutdown) if (pollConfig.non_exclusive_heartbeat_interval_ms > 0) { logEvent('tengu_bridge_heartbeat_mode_entered', { active_sessions: activeSessions.size, heartbeat_interval_ms: pollConfig.non_exclusive_heartbeat_interval_ms, }) // Deadline computed once at entry — GB updates to atCapMs don't // shift an in-flight deadline (next entry picks up the new value). const pollDeadline = atCapMs > 0 ? Date.now() + atCapMs : null let hbResult: 'ok' | 'auth_failed' | 'fatal' | 'failed' = 'ok' let hbCycles = 0 while ( !loopSignal.aborted && activeSessions.size >= config.maxSessions && (pollDeadline === null || Date.now() < pollDeadline) ) { // Re-read config each cycle so GrowthBook updates take effect const hbConfig = getPollIntervalConfig() if (hbConfig.non_exclusive_heartbeat_interval_ms <= 0) break
// Capture capacity signal BEFORE the async heartbeat call so // a session ending during the HTTP request is caught by the // subsequent sleep (instead of being lost to a replaced controller). const cap = capacityWake.signal()
hbResult = await heartbeatActiveWorkItems() if (hbResult === 'auth_failed' || hbResult === 'fatal') { cap.cleanup() break }
hbCycles++ await sleep( hbConfig.non_exclusive_heartbeat_interval_ms, cap.signal, ) cap.cleanup() }
// Determine exit reason for telemetry const exitReason = hbResult === 'auth_failed' || hbResult === 'fatal' ? hbResult : loopSignal.aborted ? 'shutdown' : activeSessions.size < config.maxSessions ? 'capacity_changed' : pollDeadline !== null && Date.now() >= pollDeadline ? 'poll_due' : 'config_disabled' logEvent('tengu_bridge_heartbeat_mode_exited', { reason: exitReason as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, heartbeat_cycles: hbCycles, active_sessions: activeSessions.size, }) if (exitReason === 'poll_due') { // bridgeApi throttles empty-poll logs (EMPTY_POLL_LOG_INTERVAL=100) // so the once-per-10min poll_due poll is invisible at counter=2. // Log it here so verification runs see both endpoints in the debug log. logForDebugging( `[bridge:poll] Heartbeat poll_due after ${hbCycles} cycles — falling through to pollForWork`, ) }
// On auth_failed or fatal, sleep before polling to avoid a tight // poll+heartbeat loop. Auth_failed: heartbeatActiveWorkItems // already called reconnectSession — the sleep gives the server // time to propagate the re-queue. Fatal (404/410): may be a // single work item GCd while the environment is still valid. // Use atCapMs if enabled, else the heartbeat interval as a floor // (guaranteed > 0 here) so heartbeat-only configs don't tight-loop. if (hbResult === 'auth_failed' || hbResult === 'fatal') { const cap = capacityWake.signal() await sleep( atCapMs > 0 ? atCapMs : pollConfig.non_exclusive_heartbeat_interval_ms, cap.signal, ) cap.cleanup() } } else if (atCapMs > 0) { // Heartbeat disabled: slow poll as liveness signal. const cap = capacityWake.signal() await sleep(atCapMs, cap.signal) cap.cleanup() } } else { const interval = activeSessions.size > 0 ? pollConfig.multisession_poll_interval_ms_partial_capacity : pollConfig.multisession_poll_interval_ms_not_at_capacity await sleep(interval, loopSignal) } continue }
// At capacity — we polled to keep the heartbeat alive, but cannot // accept new work right now. We still enter the switch below so that // token refreshes for existing sessions are processed (the case // 'session' handler checks for existing sessions before the inner // capacity guard). const atCapacityBeforeSwitch = activeSessions.size >= config.maxSessions
// Skip work items that have already been completed and stopped. // The server may re-deliver stale work before processing our stop // request, which would otherwise cause a duplicate session spawn. if (completedWorkIds.has(work.id)) { logForDebugging( `[bridge:work] Skipping already-completed workId=${work.id}`, ) // Respect capacity throttle — without a sleep here, persistent stale // redeliveries would tight-loop at poll-request speed (the !work // branch above is the only sleep, and work != null skips it). if (atCapacityBeforeSwitch) { const cap = capacityWake.signal() if (pollConfig.non_exclusive_heartbeat_interval_ms > 0) { await heartbeatActiveWorkItems() await sleep( pollConfig.non_exclusive_heartbeat_interval_ms, cap.signal, ) } else if (pollConfig.multisession_poll_interval_ms_at_capacity > 0) { await sleep( pollConfig.multisession_poll_interval_ms_at_capacity, cap.signal, ) } cap.cleanup() } else { await sleep(1000, loopSignal) } continue }
// Decode the work secret for session spawning and to extract the JWT // used for the ack call below. let secret try { secret = decodeWorkSecret(work.secret) } catch (err) { const errMsg = errorMessage(err) logger.logError( `Failed to decode work secret for workId=${work.id}: ${errMsg}`, ) logEvent('tengu_bridge_work_secret_failed', {}) // Can't ack (needs the JWT we failed to decode). stopWork uses OAuth, // so it's callable here — prevents XAUTOCLAIM from re-delivering this // poisoned item every reclaim_older_than_ms cycle. completedWorkIds.add(work.id) trackCleanup( stopWorkWithRetry( api, environmentId, work.id, logger, backoffConfig.stopWorkBaseDelayMs, ), ) // Respect capacity throttle before retrying — without a sleep here, // repeated decode failures at capacity would tight-loop at // poll-request speed (work != null skips the !work sleep above). if (atCapacityBeforeSwitch) { const cap = capacityWake.signal() if (pollConfig.non_exclusive_heartbeat_interval_ms > 0) { await heartbeatActiveWorkItems() await sleep( pollConfig.non_exclusive_heartbeat_interval_ms, cap.signal, ) } else if (pollConfig.multisession_poll_interval_ms_at_capacity > 0) { await sleep( pollConfig.multisession_poll_interval_ms_at_capacity, cap.signal, ) } cap.cleanup() } continue }
// Explicitly acknowledge after committing to handle the work — NOT // before. The at-capacity guard inside case 'session' can break // without spawning; acking there would permanently lose the work. // Ack failures are non-fatal: server re-delivers, and existingHandle // / completedWorkIds paths handle the dedup. const ackWork = async (): Promise<void> => { logForDebugging(`[bridge:work] Acknowledging workId=${work.id}`) try { await api.acknowledgeWork( environmentId, work.id, secret.session_ingress_token, ) } catch (err) { logForDebugging( `[bridge:work] Acknowledge failed workId=${work.id}: ${errorMessage(err)}`, ) } }
const workType: string = work.data.type switch (work.data.type) { case 'healthcheck': await ackWork() logForDebugging('[bridge:work] Healthcheck received') logger.logVerbose('Healthcheck received') break case 'session': { const sessionId = work.data.id try { validateBridgeId(sessionId, 'session_id') } catch { await ackWork() logger.logError(`Invalid session_id received: ${sessionId}`) break }
// If the session is already running, deliver the fresh token so // the child process can reconnect its WebSocket with the new // session ingress token. This handles the case where the server // re-dispatches work for an existing session after the WS drops. const existingHandle = activeSessions.get(sessionId) if (existingHandle) { existingHandle.updateAccessToken(secret.session_ingress_token) sessionIngressTokens.set(sessionId, secret.session_ingress_token) sessionWorkIds.set(sessionId, work.id) // Re-schedule next refresh from the fresh JWT's expiry. onRefresh // branches on v2Sessions so both v1 and v2 are safe here. tokenRefresh?.schedule(sessionId, secret.session_ingress_token) logForDebugging( `[bridge:work] Updated access token for existing sessionId=${sessionId} workId=${work.id}`, ) await ackWork() break }
// At capacity — token refresh for existing sessions is handled // above, but we cannot spawn new ones. The post-switch capacity // sleep will throttle the loop; just break here. if (activeSessions.size >= config.maxSessions) { logForDebugging( `[bridge:work] At capacity (${activeSessions.size}/${config.maxSessions}), cannot spawn new session for workId=${work.id}`, ) break }
await ackWork() const spawnStartTime = Date.now()
// CCR v2 path: register this bridge as the session worker, get the // epoch, and point the child at /v1/code/sessions/{id}. The child // already has the full v2 client (SSETransport + CCRClient) — same // code path environment-manager launches in containers. // // v1 path: Session-Ingress WebSocket. Uses config.sessionIngressUrl // (not secret.api_base_url, which may point to a remote proxy tunnel // that doesn't know about locally-created sessions). let sdkUrl: string let useCcrV2 = false let workerEpoch: number | undefined // Server decides per-session via the work secret; env var is the // ant-dev override (e.g. forcing v2 before the server flag is on). if ( secret.use_code_sessions === true || isEnvTruthy(process.env.CLAUDE_BRIDGE_USE_CCR_V2) ) { sdkUrl = buildCCRv2SdkUrl(config.apiBaseUrl, sessionId) // Retry once on transient failure (network blip, 500) before // permanently giving up and killing the session. for (let attempt = 1; attempt <= 2; attempt++) { try { workerEpoch = await registerWorker( sdkUrl, secret.session_ingress_token, ) useCcrV2 = true logForDebugging( `[bridge:session] CCR v2: registered worker sessionId=${sessionId} epoch=${workerEpoch} attempt=${attempt}`, ) break } catch (err) { const errMsg = errorMessage(err) if (attempt < 2) { logForDebugging( `[bridge:session] CCR v2: registerWorker attempt ${attempt} failed, retrying: ${errMsg}`, ) await sleep(2_000, loopSignal) if (loopSignal.aborted) break continue } logger.logError( `CCR v2 worker registration failed for session ${sessionId}: ${errMsg}`, ) logError(new Error(`registerWorker failed: ${errMsg}`)) completedWorkIds.add(work.id) trackCleanup( stopWorkWithRetry( api, environmentId, work.id, logger, backoffConfig.stopWorkBaseDelayMs, ), ) } } if (!useCcrV2) break } else { sdkUrl = buildSdkUrl(config.sessionIngressUrl, sessionId) }
// In worktree mode, on-demand sessions get an isolated git worktree // so concurrent sessions don't interfere with each other's file // changes. The pre-created initial session (if any) runs in // config.dir so the user's first session lands in the directory they // invoked `rc` from — matching the old single-session UX. // In same-dir and single-session modes, all sessions share config.dir. // Capture spawnMode before the await below — the `w` key handler // mutates config.spawnMode directly, and createAgentWorktree can // take 1-2s, so reading config.spawnMode after the await can // produce contradictory analytics (spawn_mode:'same-dir', in_worktree:true). const spawnModeAtDecision = config.spawnMode let sessionDir = config.dir let worktreeCreateMs = 0 if ( spawnModeAtDecision === 'worktree' && (initialSessionId === undefined || !sameSessionId(sessionId, initialSessionId)) ) { const wtStart = Date.now() try { const wt = await createAgentWorktree( `bridge-${safeFilenameId(sessionId)}`, ) worktreeCreateMs = Date.now() - wtStart sessionWorktrees.set(sessionId, { worktreePath: wt.worktreePath, worktreeBranch: wt.worktreeBranch, gitRoot: wt.gitRoot, hookBased: wt.hookBased, }) sessionDir = wt.worktreePath logForDebugging( `[bridge:session] Created worktree for sessionId=${sessionId} at ${wt.worktreePath}`, ) } catch (err) { const errMsg = errorMessage(err) logger.logError( `Failed to create worktree for session ${sessionId}: ${errMsg}`, ) logError(new Error(`Worktree creation failed: ${errMsg}`)) completedWorkIds.add(work.id) trackCleanup( stopWorkWithRetry( api, environmentId, work.id, logger, backoffConfig.stopWorkBaseDelayMs, ), ) break } }
logForDebugging( `[bridge:session] Spawning sessionId=${sessionId} sdkUrl=${sdkUrl}`, )
// compat-surface session_* form for logger/Sessions-API calls. // Work poll returns cse_* under v2 compat; convert before spawn so // the onFirstUserMessage callback can close over it. const compatSessionId = toCompatSessionId(sessionId)
const spawnResult = safeSpawn( spawner, { sessionId, sdkUrl, accessToken: secret.session_ingress_token, useCcrV2, workerEpoch, onFirstUserMessage: text => { // Server-set titles (--name, web rename) win. fetchSessionTitle // runs concurrently; if it already populated titledSessions, // skip. If it hasn't resolved yet, the derived title sticks — // acceptable since the server had no title at spawn time. if (titledSessions.has(compatSessionId)) return titledSessions.add(compatSessionId) const title = deriveSessionTitle(text) logger.setSessionTitle(compatSessionId, title) logForDebugging( `[bridge:title] derived title for ${compatSessionId}: ${title}`, ) void import('./createSession.js') .then(({ updateBridgeSessionTitle }) => updateBridgeSessionTitle(compatSessionId, title, { baseUrl: config.apiBaseUrl, }), ) .catch(err => logForDebugging( `[bridge:title] failed to update title for ${compatSessionId}: ${err}`, { level: 'error' }, ), ) }, }, sessionDir, ) if (typeof spawnResult === 'string') { logger.logError( `Failed to spawn session ${sessionId}: ${spawnResult}`, ) // Clean up worktree if one was created for this session const wt = sessionWorktrees.get(sessionId) if (wt) { sessionWorktrees.delete(sessionId) trackCleanup( removeAgentWorktree( wt.worktreePath, wt.worktreeBranch, wt.gitRoot, wt.hookBased, ).catch((err: unknown) => logger.logVerbose( `Failed to remove worktree ${wt.worktreePath}: ${errorMessage(err)}`, ), ), ) } completedWorkIds.add(work.id) trackCleanup( stopWorkWithRetry( api, environmentId, work.id, logger, backoffConfig.stopWorkBaseDelayMs, ), ) break } const handle = spawnResult
const spawnDurationMs = Date.now() - spawnStartTime logEvent('tengu_bridge_session_started', { active_sessions: activeSessions.size, spawn_mode: spawnModeAtDecision as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, in_worktree: sessionWorktrees.has(sessionId), spawn_duration_ms: spawnDurationMs, worktree_create_ms: worktreeCreateMs, inProtectedNamespace: isInProtectedNamespace(), }) logForDiagnosticsNoPII('info', 'bridge_session_started', { spawn_mode: spawnModeAtDecision, in_worktree: sessionWorktrees.has(sessionId), spawn_duration_ms: spawnDurationMs, worktree_create_ms: worktreeCreateMs, })
activeSessions.set(sessionId, handle) sessionWorkIds.set(sessionId, work.id) sessionIngressTokens.set(sessionId, secret.session_ingress_token) sessionCompatIds.set(sessionId, compatSessionId)
const startTime = Date.now() sessionStartTimes.set(sessionId, startTime)
// Use a generic prompt description since we no longer get startup_context logger.logSessionStart(sessionId, `Session ${sessionId}`)
// Compute the actual debug file path (mirrors sessionRunner.ts logic) const safeId = safeFilenameId(sessionId) let sessionDebugFile: string | undefined if (config.debugFile) { const ext = config.debugFile.lastIndexOf('.') if (ext > 0) { sessionDebugFile = `${config.debugFile.slice(0, ext)}-${safeId}${config.debugFile.slice(ext)}` } else { sessionDebugFile = `${config.debugFile}-${safeId}` } } else if (config.verbose || process.env.USER_TYPE === 'ant') { sessionDebugFile = join( tmpdir(), 'claude', `bridge-session-${safeId}.log`, ) }
if (sessionDebugFile) { logger.logVerbose(`Debug log: ${sessionDebugFile}`) }
// Register in the sessions Map before starting status updates so the // first render tick shows the correct count and bullet list in sync. logger.addSession( compatSessionId, getRemoteSessionUrl(compatSessionId, config.sessionIngressUrl), )
// Start live status updates and transition to "Attached" state. startStatusUpdates() logger.setAttached(compatSessionId)
// One-shot title fetch. If the session already has a title (set via // --name, web rename, or /remote-control), display it and mark as // titled so the first-user-message fallback doesn't overwrite it. // Otherwise onFirstUserMessage derives one from the first prompt. void fetchSessionTitle(compatSessionId, config.apiBaseUrl) .then(title => { if (title && activeSessions.has(sessionId)) { titledSessions.add(compatSessionId) logger.setSessionTitle(compatSessionId, title) logForDebugging( `[bridge:title] server title for ${compatSessionId}: ${title}`, ) } }) .catch(err => logForDebugging( `[bridge:title] failed to fetch title for ${compatSessionId}: ${err}`, { level: 'error' }, ), )
// Start per-session timeout watchdog const timeoutMs = config.sessionTimeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS if (timeoutMs > 0) { const timer = setTimeout( onSessionTimeout, timeoutMs, sessionId, timeoutMs, logger, timedOutSessions, handle, ) sessionTimers.set(sessionId, timer) }
// Schedule proactive token refresh before the JWT expires. // onRefresh branches on v2Sessions: v1 delivers OAuth to the // child, v2 triggers server re-dispatch via reconnectSession. if (useCcrV2) { v2Sessions.add(sessionId) } tokenRefresh?.schedule(sessionId, secret.session_ingress_token)
void handle.done.then(onSessionDone(sessionId, startTime, handle)) break } default: await ackWork() // Gracefully ignore unknown work types. The backend may send new // types before the bridge client is updated. logForDebugging( `[bridge:work] Unknown work type: ${workType}, skipping`, ) break }
// When at capacity, throttle the loop. The switch above still runs so // existing-session token refreshes are processed, but we sleep here // to avoid busy-looping. Include the capacity wake signal so the // sleep is interrupted immediately when a session completes. if (atCapacityBeforeSwitch) { const cap = capacityWake.signal() if (pollConfig.non_exclusive_heartbeat_interval_ms > 0) { await heartbeatActiveWorkItems() await sleep( pollConfig.non_exclusive_heartbeat_interval_ms, cap.signal, ) } else if (pollConfig.multisession_poll_interval_ms_at_capacity > 0) { await sleep( pollConfig.multisession_poll_interval_ms_at_capacity, cap.signal, ) } cap.cleanup() } } catch (err) { if (loopSignal.aborted) { break }
// Fatal errors (401/403) — no point retrying, auth won't fix itself if (err instanceof BridgeFatalError) { fatalExit = true // Server-enforced expiry gets a clean status message, not an error if (isExpiredErrorType(err.errorType)) { logger.logStatus(err.message) } else if (isSuppressible403(err)) { // Cosmetic 403 errors (e.g., external_poll_sessions scope, // environments:manage permission) — don't show to user logForDebugging(`[bridge:work] Suppressed 403 error: ${err.message}`) } else { logger.logError(err.message) logError(err) } logEvent('tengu_bridge_fatal_error', { status: err.status, error_type: err.errorType as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, }) logForDiagnosticsNoPII( isExpiredErrorType(err.errorType) ? 'info' : 'error', 'bridge_fatal_error', { status: err.status, error_type: err.errorType }, ) break }
const errMsg = describeAxiosError(err)
if (isConnectionError(err) || isServerError(err)) { const now = Date.now()
// Detect system sleep/wake: if the gap since the last poll error // greatly exceeds the expected backoff, the machine likely slept. // Reset error tracking so the bridge retries with a fresh budget. if ( lastPollErrorTime !== null && now - lastPollErrorTime > pollSleepDetectionThresholdMs(backoffConfig) ) { logForDebugging( `[bridge:work] Detected system sleep (${Math.round((now - lastPollErrorTime) / 1000)}s gap), resetting error budget`, ) logForDiagnosticsNoPII('info', 'bridge_poll_sleep_detected', { gapMs: now - lastPollErrorTime, }) connErrorStart = null connBackoff = 0 generalErrorStart = null generalBackoff = 0 } lastPollErrorTime = now
if (!connErrorStart) { connErrorStart = now } const elapsed = now - connErrorStart if (elapsed >= backoffConfig.connGiveUpMs) { logger.logError( `Server unreachable for ${Math.round(elapsed / 60_000)} minutes, giving up.`, ) logEvent('tengu_bridge_poll_give_up', { error_type: 'connection' as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, elapsed_ms: elapsed, }) logForDiagnosticsNoPII('error', 'bridge_poll_give_up', { error_type: 'connection', elapsed_ms: elapsed, }) fatalExit = true break }
// Reset the other track when switching error types generalErrorStart = null generalBackoff = 0
connBackoff = connBackoff ? Math.min(connBackoff * 2, backoffConfig.connCapMs) : backoffConfig.connInitialMs const delay = addJitter(connBackoff) logger.logVerbose( `Connection error, retrying in ${formatDelay(delay)} (${Math.round(elapsed / 1000)}s elapsed): ${errMsg}`, ) logger.updateReconnectingStatus( formatDelay(delay), formatDuration(elapsed), ) // The poll_due heartbeat-loop exit leaves a healthy lease exposed to // this backoff path. Heartbeat before each sleep so /poll outages // (the VerifyEnvironmentSecretAuth DB path heartbeat was introduced // to avoid) don't kill the 300s lease TTL. No-op when activeSessions // is empty or heartbeat is disabled. if (getPollIntervalConfig().non_exclusive_heartbeat_interval_ms > 0) { await heartbeatActiveWorkItems() } await sleep(delay, loopSignal) } else { const now = Date.now()
// Sleep detection for general errors (same logic as connection errors) if ( lastPollErrorTime !== null && now - lastPollErrorTime > pollSleepDetectionThresholdMs(backoffConfig) ) { logForDebugging( `[bridge:work] Detected system sleep (${Math.round((now - lastPollErrorTime) / 1000)}s gap), resetting error budget`, ) logForDiagnosticsNoPII('info', 'bridge_poll_sleep_detected', { gapMs: now - lastPollErrorTime, }) connErrorStart = null connBackoff = 0 generalErrorStart = null generalBackoff = 0 } lastPollErrorTime = now
if (!generalErrorStart) { generalErrorStart = now } const elapsed = now - generalErrorStart if (elapsed >= backoffConfig.generalGiveUpMs) { logger.logError( `Persistent errors for ${Math.round(elapsed / 60_000)} minutes, giving up.`, ) logEvent('tengu_bridge_poll_give_up', { error_type: 'general' as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, elapsed_ms: elapsed, }) logForDiagnosticsNoPII('error', 'bridge_poll_give_up', { error_type: 'general', elapsed_ms: elapsed, }) fatalExit = true break }
// Reset the other track when switching error types connErrorStart = null connBackoff = 0
generalBackoff = generalBackoff ? Math.min(generalBackoff * 2, backoffConfig.generalCapMs) : backoffConfig.generalInitialMs const delay = addJitter(generalBackoff) logger.logVerbose( `Poll failed, retrying in ${formatDelay(delay)} (${Math.round(elapsed / 1000)}s elapsed): ${errMsg}`, ) logger.updateReconnectingStatus( formatDelay(delay), formatDuration(elapsed), ) if (getPollIntervalConfig().non_exclusive_heartbeat_interval_ms > 0) { await heartbeatActiveWorkItems() } await sleep(delay, loopSignal) } } }
// Clean up stopStatusUpdates() logger.clearStatus()
const loopDurationMs = Date.now() - loopStartTime logEvent('tengu_bridge_shutdown', { active_sessions: activeSessions.size, loop_duration_ms: loopDurationMs, }) logForDiagnosticsNoPII('info', 'bridge_shutdown', { active_sessions: activeSessions.size, loop_duration_ms: loopDurationMs, })
// Graceful shutdown: kill active sessions, report them as interrupted, // archive sessions, then deregister the environment so the web UI shows // the bridge as offline.
// Collect all session IDs to archive on exit. This includes: // 1. Active sessions (snapshot before killing — onSessionDone clears maps) // 2. The initial auto-created session (may never have had work dispatched) // api.archiveSession is idempotent (409 if already archived), so // double-archiving is safe. const sessionsToArchive = new Set(activeSessions.keys()) if (initialSessionId) { sessionsToArchive.add(initialSessionId) } // Snapshot before killing — onSessionDone clears sessionCompatIds. const compatIdSnapshot = new Map(sessionCompatIds)
if (activeSessions.size > 0) { logForDebugging( `[bridge:shutdown] Shutting down ${activeSessions.size} active session(s)`, ) logger.logStatus( `Shutting down ${activeSessions.size} active session(s)\u2026`, )
// Snapshot work IDs before killing — onSessionDone clears the maps when // each child exits, so we need a copy for the stopWork calls below. const shutdownWorkIds = new Map(sessionWorkIds)
for (const [sessionId, handle] of activeSessions.entries()) { logForDebugging( `[bridge:shutdown] Sending SIGTERM to sessionId=${sessionId}`, ) handle.kill() }
const timeout = new AbortController() await Promise.race([ Promise.allSettled([...activeSessions.values()].map(h => h.done)), sleep(backoffConfig.shutdownGraceMs ?? 30_000, timeout.signal), ]) timeout.abort()
// SIGKILL any processes that didn't respond to SIGTERM within the grace window for (const [sid, handle] of activeSessions.entries()) { logForDebugging(`[bridge:shutdown] Force-killing stuck sessionId=${sid}`) handle.forceKill() }
// Clear any remaining session timeout and refresh timers for (const timer of sessionTimers.values()) { clearTimeout(timer) } sessionTimers.clear() tokenRefresh?.cancelAll()
// Clean up any remaining worktrees from active sessions. // Snapshot and clear the map first so onSessionDone (which may fire // during the await below when handle.done resolves) won't try to // remove the same worktrees again. if (sessionWorktrees.size > 0) { const remainingWorktrees = [...sessionWorktrees.values()] sessionWorktrees.clear() logForDebugging( `[bridge:shutdown] Cleaning up ${remainingWorktrees.length} worktree(s)`, ) await Promise.allSettled( remainingWorktrees.map(wt => removeAgentWorktree( wt.worktreePath, wt.worktreeBranch, wt.gitRoot, wt.hookBased, ), ), ) }
// Stop all active work items so the server knows they're done await Promise.allSettled( [...shutdownWorkIds.entries()].map(([sessionId, workId]) => { return api .stopWork(environmentId, workId, true) .catch(err => logger.logVerbose( `Failed to stop work ${workId} for session ${sessionId}: ${errorMessage(err)}`, ), ) }), ) }
// Ensure all in-flight cleanup (stopWork, worktree removal) from // onSessionDone completes before deregistering — otherwise // process.exit() can kill them mid-flight. if (pendingCleanups.size > 0) { await Promise.allSettled([...pendingCleanups]) }
// In single-session mode with a known session, leave the session and // environment alive so `claude remote-control --session-id=<id>` can resume. // The backend GCs stale environments via a 4h TTL (BRIDGE_LAST_POLL_TTL). // Archiving the session or deregistering the environment would make the // printed resume command a lie — deregister deletes Firestore + Redis stream. // Skip when the loop exited fatally (env expired, auth failed, give-up) — // resume is impossible in those cases and the message would contradict the // error already printed. // feature('KAIROS') gate: --session-id is ant-only; without the gate, // revert to the pre-PR behavior (archive + deregister on every shutdown). if ( feature('KAIROS') && config.spawnMode === 'single-session' && initialSessionId && !fatalExit ) { logger.logStatus( `Resume this session by running \`claude remote-control --continue\``, ) logForDebugging( `[bridge:shutdown] Skipping archive+deregister to allow resume of session ${initialSessionId}`, ) return }
// Archive all known sessions so they don't linger as idle/running on the // server after the bridge goes offline. if (sessionsToArchive.size > 0) { logForDebugging( `[bridge:shutdown] Archiving ${sessionsToArchive.size} session(s)`, ) await Promise.allSettled( [...sessionsToArchive].map(sessionId => api .archiveSession( compatIdSnapshot.get(sessionId) ?? toCompatSessionId(sessionId), ) .catch(err => logger.logVerbose( `Failed to archive session ${sessionId}: ${errorMessage(err)}`, ), ), ), ) }
// Deregister the environment so the web UI shows the bridge as offline // and the Redis stream is cleaned up. try { await api.deregisterEnvironment(environmentId) logForDebugging( `[bridge:shutdown] Environment deregistered, bridge offline`, ) logger.logVerbose('Environment deregistered.') } catch (err) { logger.logVerbose(`Failed to deregister environment: ${errorMessage(err)}`) }
// Clear the crash-recovery pointer — the env is gone, pointer would be // stale. The early return above (resumable SIGINT shutdown) skips this, // leaving the pointer as a backup for the printed --session-id hint. const { clearBridgePointer } = await import('./bridgePointer.js') await clearBridgePointer(config.dir)
logger.logVerbose('Environment offline.')}
const CONNECTION_ERROR_CODES = new Set([ 'ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'ENETUNREACH', 'EHOSTUNREACH',])
export function isConnectionError(err: unknown): boolean { if ( err && typeof err === 'object' && 'code' in err && typeof err.code === 'string' && CONNECTION_ERROR_CODES.has(err.code) ) { return true } return false}
/** Detect HTTP 5xx errors from axios (code: 'ERR_BAD_RESPONSE'). */export function isServerError(err: unknown): boolean { return ( !!err && typeof err === 'object' && 'code' in err && typeof err.code === 'string' && err.code === 'ERR_BAD_RESPONSE' )}
/** Add ±25% jitter to a delay value. */function addJitter(ms: number): number { return Math.max(0, ms + ms * 0.25 * (2 * Math.random() - 1))}
function formatDelay(ms: number): string { return ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${Math.round(ms)}ms`}
/** * Retry stopWork with exponential backoff (3 attempts, 1s/2s/4s). * Ensures the server learns the work item ended, preventing server-side zombies. */async function stopWorkWithRetry( api: BridgeApiClient, environmentId: string, workId: string, logger: BridgeLogger, baseDelayMs = 1000,): Promise<void> { const MAX_ATTEMPTS = 3
for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) { try { await api.stopWork(environmentId, workId, false) logForDebugging( `[bridge:work] stopWork succeeded for workId=${workId} on attempt ${attempt}/${MAX_ATTEMPTS}`, ) return } catch (err) { // Auth/permission errors won't be fixed by retrying if (err instanceof BridgeFatalError) { if (isSuppressible403(err)) { logForDebugging( `[bridge:work] Suppressed stopWork 403 for ${workId}: ${err.message}`, ) } else { logger.logError(`Failed to stop work ${workId}: ${err.message}`) } logForDiagnosticsNoPII('error', 'bridge_stop_work_failed', { attempts: attempt, fatal: true, }) return } const errMsg = errorMessage(err) if (attempt < MAX_ATTEMPTS) { const delay = addJitter(baseDelayMs * Math.pow(2, attempt - 1)) logger.logVerbose( `Failed to stop work ${workId} (attempt ${attempt}/${MAX_ATTEMPTS}), retrying in ${formatDelay(delay)}: ${errMsg}`, ) await sleep(delay) } else { logger.logError( `Failed to stop work ${workId} after ${MAX_ATTEMPTS} attempts: ${errMsg}`, ) logForDiagnosticsNoPII('error', 'bridge_stop_work_failed', { attempts: MAX_ATTEMPTS, }) } } }}
function onSessionTimeout( sessionId: string, timeoutMs: number, logger: BridgeLogger, timedOutSessions: Set<string>, handle: SessionHandle,): void { logForDebugging( `[bridge:session] sessionId=${sessionId} timed out after ${formatDuration(timeoutMs)}`, ) logEvent('tengu_bridge_session_timeout', { timeout_ms: timeoutMs, }) logger.logSessionFailed( sessionId, `Session timed out after ${formatDuration(timeoutMs)}`, ) timedOutSessions.add(sessionId) handle.kill()}
export type ParsedArgs = { verbose: boolean sandbox: boolean debugFile?: string sessionTimeoutMs?: number permissionMode?: string name?: string /** Value passed to --spawn (if any); undefined if no --spawn flag was given. */ spawnMode: SpawnMode | undefined /** Value passed to --capacity (if any); undefined if no --capacity flag was given. */ capacity: number | undefined /** --[no-]create-session-in-dir override; undefined = use default (on). */ createSessionInDir: boolean | undefined /** Resume an existing session instead of creating a new one. */ sessionId?: string /** Resume the last session in this directory (reads bridge-pointer.json). */ continueSession: boolean help: boolean error?: string}
const SPAWN_FLAG_VALUES = ['session', 'same-dir', 'worktree'] as const
function parseSpawnValue(raw: string | undefined): SpawnMode | string { if (raw === 'session') return 'single-session' if (raw === 'same-dir') return 'same-dir' if (raw === 'worktree') return 'worktree' return `--spawn requires one of: ${SPAWN_FLAG_VALUES.join(', ')} (got: ${raw ?? '<missing>'})`}
function parseCapacityValue(raw: string | undefined): number | string { const n = raw === undefined ? NaN : parseInt(raw, 10) if (isNaN(n) || n < 1) { return `--capacity requires a positive integer (got: ${raw ?? '<missing>'})` } return n}
export function parseArgs(args: string[]): ParsedArgs { let verbose = false let sandbox = false let debugFile: string | undefined let sessionTimeoutMs: number | undefined let permissionMode: string | undefined let name: string | undefined let help = false let spawnMode: SpawnMode | undefined let capacity: number | undefined let createSessionInDir: boolean | undefined let sessionId: string | undefined let continueSession = false
for (let i = 0; i < args.length; i++) { const arg = args[i]! if (arg === '--help' || arg === '-h') { help = true } else if (arg === '--verbose' || arg === '-v') { verbose = true } else if (arg === '--sandbox') { sandbox = true } else if (arg === '--no-sandbox') { sandbox = false } else if (arg === '--debug-file' && i + 1 < args.length) { debugFile = resolve(args[++i]!) } else if (arg.startsWith('--debug-file=')) { debugFile = resolve(arg.slice('--debug-file='.length)) } else if (arg === '--session-timeout' && i + 1 < args.length) { sessionTimeoutMs = parseInt(args[++i]!, 10) * 1000 } else if (arg.startsWith('--session-timeout=')) { sessionTimeoutMs = parseInt(arg.slice('--session-timeout='.length), 10) * 1000 } else if (arg === '--permission-mode' && i + 1 < args.length) { permissionMode = args[++i]! } else if (arg.startsWith('--permission-mode=')) { permissionMode = arg.slice('--permission-mode='.length) } else if (arg === '--name' && i + 1 < args.length) { name = args[++i]! } else if (arg.startsWith('--name=')) { name = arg.slice('--name='.length) } else if ( feature('KAIROS') && arg === '--session-id' && i + 1 < args.length ) { sessionId = args[++i]! if (!sessionId) { return makeError('--session-id requires a value') } } else if (feature('KAIROS') && arg.startsWith('--session-id=')) { sessionId = arg.slice('--session-id='.length) if (!sessionId) { return makeError('--session-id requires a value') } } else if (feature('KAIROS') && (arg === '--continue' || arg === '-c')) { continueSession = true } else if (arg === '--spawn' || arg.startsWith('--spawn=')) { if (spawnMode !== undefined) { return makeError('--spawn may only be specified once') } const raw = arg.startsWith('--spawn=') ? arg.slice('--spawn='.length) : args[++i] const v = parseSpawnValue(raw) if (v === 'single-session' || v === 'same-dir' || v === 'worktree') { spawnMode = v } else { return makeError(v) } } else if (arg === '--capacity' || arg.startsWith('--capacity=')) { if (capacity !== undefined) { return makeError('--capacity may only be specified once') } const raw = arg.startsWith('--capacity=') ? arg.slice('--capacity='.length) : args[++i] const v = parseCapacityValue(raw) if (typeof v === 'number') capacity = v else return makeError(v) } else if (arg === '--create-session-in-dir') { createSessionInDir = true } else if (arg === '--no-create-session-in-dir') { createSessionInDir = false } else { return makeError( `Unknown argument: ${arg}\nRun 'claude remote-control --help' for usage.`, ) } }
// Note: gate check for --spawn/--capacity/--create-session-in-dir is in bridgeMain // (gate-aware error). Flag cross-validation happens here.
// --capacity only makes sense for multi-session modes. if (spawnMode === 'single-session' && capacity !== undefined) { return makeError( `--capacity cannot be used with --spawn=session (single-session mode has fixed capacity 1).`, ) }
// --session-id / --continue resume a specific session on its original // environment; incompatible with spawn-related flags (which configure // fresh session creation), and mutually exclusive with each other. if ( (sessionId || continueSession) && (spawnMode !== undefined || capacity !== undefined || createSessionInDir !== undefined) ) { return makeError( `--session-id and --continue cannot be used with --spawn, --capacity, or --create-session-in-dir.`, ) } if (sessionId && continueSession) { return makeError(`--session-id and --continue cannot be used together.`) }
return { verbose, sandbox, debugFile, sessionTimeoutMs, permissionMode, name, spawnMode, capacity, createSessionInDir, sessionId, continueSession, help, }
function makeError(error: string): ParsedArgs { return { verbose, sandbox, debugFile, sessionTimeoutMs, permissionMode, name, spawnMode, capacity, createSessionInDir, sessionId, continueSession, help, error, } }}
async function printHelp(): Promise<void> { // Use EXTERNAL_PERMISSION_MODES for help text — internal modes (bubble) // are ant-only and auto is feature-gated; they're still accepted by validation. const { EXTERNAL_PERMISSION_MODES } = await import('../types/permissions.js') const modes = EXTERNAL_PERMISSION_MODES.join(', ') const showServer = await isMultiSessionSpawnEnabled() const serverOptions = showServer ? ` --spawn <mode> Spawn mode: same-dir, worktree, session (default: same-dir) --capacity <N> Max concurrent sessions in worktree or same-dir mode (default: ${SPAWN_SESSIONS_DEFAULT}) --[no-]create-session-in-dir Pre-create a session in the current directory; in worktree mode this session stays in cwd while on-demand sessions get isolated worktrees (default: on)` : '' const serverDescription = showServer ? ` Remote Control runs as a persistent server that accepts multiple concurrent sessions in the current directory. One session is pre-created on start so you have somewhere to type immediately. Use --spawn=worktree to isolate each on-demand session in its own git worktree, or --spawn=session for the classic single-session mode (exits when that session ends). Press 'w' during runtime to toggle between same-dir and worktree.` : '' const serverNote = showServer ? ` - Worktree mode requires a git repository or WorktreeCreate/WorktreeRemove hooks` : '' const help = `Remote Control - Connect your local environment to claude.ai/code
USAGE claude remote-control [options]OPTIONS --name <name> Name for the session (shown in claude.ai/code)${ feature('KAIROS') ? ` -c, --continue Resume the last session in this directory --session-id <id> Resume a specific session by ID (cannot be used with spawn flags or --continue)` : ''} --permission-mode <mode> Permission mode for spawned sessions (${modes}) --debug-file <path> Write debug logs to file -v, --verbose Enable verbose output -h, --help Show this help${serverOptions}DESCRIPTION Remote Control allows you to control sessions on your local device from claude.ai/code (https://claude.ai/code). Run this command in the directory you want to work in, then connect from the Claude app or web.${serverDescription}NOTES - You must be logged in with a Claude account that has a subscription - Run \`claude\` first in the directory to accept the workspace trust dialog${serverNote}` // biome-ignore lint/suspicious/noConsole: intentional help output console.log(help)}
const TITLE_MAX_LEN = 80
/** Derive a session title from a user message: first line, truncated. */function deriveSessionTitle(text: string): string { // Collapse whitespace — newlines/tabs would break the single-line status display. const flat = text.replace(/\s+/g, ' ').trim() return truncateToWidth(flat, TITLE_MAX_LEN)}
/** * One-shot fetch of a session's title via GET /v1/sessions/{id}. * * Uses `getBridgeSession` from createSession.ts (ccr-byoc headers + org UUID) * rather than the environments-level bridgeApi client, whose headers make the * Sessions API return 404. Returns undefined if the session has no title yet * or the fetch fails — the caller falls back to deriving a title from the * first user message. */async function fetchSessionTitle( compatSessionId: string, baseUrl: string,): Promise<string | undefined> { const { getBridgeSession } = await import('./createSession.js') const session = await getBridgeSession(compatSessionId, { baseUrl }) return session?.title || undefined}
export async function bridgeMain(args: string[]): Promise<void> { const parsed = parseArgs(args)
if (parsed.help) { await printHelp() return } if (parsed.error) { // biome-ignore lint/suspicious/noConsole: intentional error output console.error(`Error: ${parsed.error}`) // eslint-disable-next-line custom-rules/no-process-exit process.exit(1) }
const { verbose, sandbox, debugFile, sessionTimeoutMs, permissionMode, name, spawnMode: parsedSpawnMode, capacity: parsedCapacity, createSessionInDir: parsedCreateSessionInDir, sessionId: parsedSessionId, continueSession, } = parsed // Mutable so --continue can set it from the pointer file. The #20460 // resume flow below then treats it the same as an explicit --session-id. let resumeSessionId = parsedSessionId // When --continue found a pointer, this is the directory it came from // (may be a worktree sibling, not `dir`). On resume-flow deterministic // failure, clear THIS file so --continue doesn't keep hitting the same // dead session. Undefined for explicit --session-id (leaves pointer alone). let resumePointerDir: string | undefined
const usedMultiSessionFeature = parsedSpawnMode !== undefined || parsedCapacity !== undefined || parsedCreateSessionInDir !== undefined
// Validate permission mode early so the user gets an error before // the bridge starts polling for work. if (permissionMode !== undefined) { const { PERMISSION_MODES } = await import('../types/permissions.js') const valid: readonly string[] = PERMISSION_MODES if (!valid.includes(permissionMode)) { // biome-ignore lint/suspicious/noConsole: intentional error output console.error( `Error: Invalid permission mode '${permissionMode}'. Valid modes: ${valid.join(', ')}`, ) // eslint-disable-next-line custom-rules/no-process-exit process.exit(1) } }
const dir = resolve('.')
// The bridge fast-path bypasses init.ts, so we must enable config reading // before any code that transitively calls getGlobalConfig() const { enableConfigs, checkHasTrustDialogAccepted } = await import( '../utils/config.js' ) enableConfigs()
// Initialize analytics and error reporting sinks. The bridge bypasses the // setup() init flow, so we call initSinks() directly to attach sinks here. const { initSinks } = await import('../utils/sinks.js') initSinks()
// Gate-aware validation: --spawn / --capacity / --create-session-in-dir require // the multi-session gate. parseArgs has already validated flag combinations; // here we only check the gate since that requires an async GrowthBook call. // Runs after enableConfigs() (GrowthBook cache reads global config) and after // initSinks() so the denial event can be enqueued. const multiSessionEnabled = await isMultiSessionSpawnEnabled() if (usedMultiSessionFeature && !multiSessionEnabled) { await logEventAsync('tengu_bridge_multi_session_denied', { used_spawn: parsedSpawnMode !== undefined, used_capacity: parsedCapacity !== undefined, used_create_session_in_dir: parsedCreateSessionInDir !== undefined, }) // logEventAsync only enqueues — process.exit() discards buffered events. // Flush explicitly, capped at 500ms to match gracefulShutdown.ts. // (sleep() doesn't unref its timer, but process.exit() follows immediately // so the ref'd timer can't delay shutdown.) await Promise.race([ Promise.all([shutdown1PEventLogging(), shutdownDatadog()]), sleep(500, undefined, { unref: true }), ]).catch(() => {}) // biome-ignore lint/suspicious/noConsole: intentional error output console.error( 'Error: Multi-session Remote Control is not enabled for your account yet.', ) // eslint-disable-next-line custom-rules/no-process-exit process.exit(1) }
// Set the bootstrap CWD so that trust checks, project config lookups, and // git utilities (getBranch, getRemoteUrl) resolve against the correct path. const { setOriginalCwd, setCwdState } = await import('../bootstrap/state.js') setOriginalCwd(dir) setCwdState(dir)
// The bridge bypasses main.tsx (which renders the interactive TrustDialog via showSetupScreens), // so we must verify trust was previously established by a normal `claude` session. if (!checkHasTrustDialogAccepted()) { // biome-ignore lint/suspicious/noConsole:: intentional console output console.error( `Error: Workspace not trusted. Please run \`claude\` in ${dir} first to review and accept the workspace trust dialog.`, ) // eslint-disable-next-line custom-rules/no-process-exit process.exit(1) }
// Resolve auth const { clearOAuthTokenCache, checkAndRefreshOAuthTokenIfNeeded } = await import('../utils/auth.js') const { getBridgeAccessToken, getBridgeBaseUrl } = await import( './bridgeConfig.js' )
const bridgeToken = getBridgeAccessToken() if (!bridgeToken) { // biome-ignore lint/suspicious/noConsole:: intentional console output console.error(BRIDGE_LOGIN_ERROR) // eslint-disable-next-line custom-rules/no-process-exit process.exit(1) }
// First-time remote dialog — explain what bridge does and get consent const { getGlobalConfig, saveGlobalConfig, getCurrentProjectConfig, saveCurrentProjectConfig, } = await import('../utils/config.js') if (!getGlobalConfig().remoteDialogSeen) { const readline = await import('readline') const rl = readline.createInterface({ input: process.stdin, output: process.stdout, }) // biome-ignore lint/suspicious/noConsole:: intentional console output console.log( '\nRemote Control lets you access this CLI session from the web (claude.ai/code)\nor the Claude app, so you can pick up where you left off on any device.\n\nYou can disconnect remote access anytime by running /remote-control again.\n', ) const answer = await new Promise<string>(resolve => { rl.question('Enable Remote Control? (y/n) ', resolve) }) rl.close() saveGlobalConfig(current => { if (current.remoteDialogSeen) return current return { ...current, remoteDialogSeen: true } }) if (answer.toLowerCase() !== 'y' && answer.toLowerCase() !== 'yes') { // eslint-disable-next-line custom-rules/no-process-exit process.exit(0) } }
// --continue: resolve the most recent session from the crash-recovery // pointer and chain into the #20460 --session-id flow. Worktree-aware: // checks current dir first (fast path, zero exec), then fans out to git // worktree siblings if that misses — the REPL bridge writes to // getOriginalCwd() which EnterWorktreeTool/activeWorktreeSession can // point at a worktree while the user's shell is at the repo root. // KAIROS-gated at parseArgs — continueSession is always false in external // builds, so this block tree-shakes. if (feature('KAIROS') && continueSession) { const { readBridgePointerAcrossWorktrees } = await import( './bridgePointer.js' ) const found = await readBridgePointerAcrossWorktrees(dir) if (!found) { // biome-ignore lint/suspicious/noConsole: intentional error output console.error( `Error: No recent session found in this directory or its worktrees. Run \`claude remote-control\` to start a new one.`, ) // eslint-disable-next-line custom-rules/no-process-exit process.exit(1) } const { pointer, dir: pointerDir } = found const ageMin = Math.round(pointer.ageMs / 60_000) const ageStr = ageMin < 60 ? `${ageMin}m` : `${Math.round(ageMin / 60)}h` const fromWt = pointerDir !== dir ? ` from worktree ${pointerDir}` : '' // biome-ignore lint/suspicious/noConsole: intentional info output console.error( `Resuming session ${pointer.sessionId} (${ageStr} ago)${fromWt}\u2026`, ) resumeSessionId = pointer.sessionId // Track where the pointer came from so the #20460 exit(1) paths below // clear the RIGHT file on deterministic failure — otherwise --continue // would keep hitting the same dead session. May be a worktree sibling. resumePointerDir = pointerDir }
// In production, baseUrl is the Anthropic API (from OAuth config). // CLAUDE_BRIDGE_BASE_URL overrides this for ant local dev only. const baseUrl = getBridgeBaseUrl()
// For non-localhost targets, require HTTPS to protect credentials. if ( baseUrl.startsWith('http://') && !baseUrl.includes('localhost') && !baseUrl.includes('127.0.0.1') ) { // biome-ignore lint/suspicious/noConsole:: intentional console output console.error( 'Error: Remote Control base URL uses HTTP. Only HTTPS or localhost HTTP is allowed.', ) // eslint-disable-next-line custom-rules/no-process-exit process.exit(1) }
// Session ingress URL for WebSocket connections. In production this is the // same as baseUrl (Envoy routes /v1/session_ingress/* to session-ingress). // Locally, session-ingress runs on a different port (9413) than the // contain-provide-api (8211), so CLAUDE_BRIDGE_SESSION_INGRESS_URL must be // set explicitly. Ant-only, matching CLAUDE_BRIDGE_BASE_URL. const sessionIngressUrl = process.env.USER_TYPE === 'ant' && process.env.CLAUDE_BRIDGE_SESSION_INGRESS_URL ? process.env.CLAUDE_BRIDGE_SESSION_INGRESS_URL : baseUrl
const { getBranch, getRemoteUrl, findGitRoot } = await import( '../utils/git.js' )
// Precheck worktree availability for the first-run dialog and the `w` // toggle. Unconditional so we know upfront whether worktree is an option. const { hasWorktreeCreateHook } = await import('../utils/hooks.js') const worktreeAvailable = hasWorktreeCreateHook() || findGitRoot(dir) !== null
// Load saved per-project spawn-mode preference. Gated by multiSessionEnabled // so a GrowthBook rollback cleanly reverts users to single-session — // otherwise a saved pref would silently re-enable multi-session behavior // (worktree isolation, 32 max sessions, w toggle) despite the gate being off. // Also guard against a stale worktree pref left over from when this dir WAS // a git repo (or the user copied config) — clear it on disk so the warning // doesn't repeat on every launch. let savedSpawnMode = multiSessionEnabled ? getCurrentProjectConfig().remoteControlSpawnMode : undefined if (savedSpawnMode === 'worktree' && !worktreeAvailable) { // biome-ignore lint/suspicious/noConsole: intentional warning output console.error( 'Warning: Saved spawn mode is worktree but this directory is not a git repository. Falling back to same-dir.', ) savedSpawnMode = undefined saveCurrentProjectConfig(current => { if (current.remoteControlSpawnMode === undefined) return current return { ...current, remoteControlSpawnMode: undefined } }) }
// First-run spawn-mode choice: ask once per project when the choice is // meaningful (gate on, both modes available, no explicit override, not // resuming). Saves to ProjectConfig so subsequent runs skip this. if ( multiSessionEnabled && !savedSpawnMode && worktreeAvailable && parsedSpawnMode === undefined && !resumeSessionId && process.stdin.isTTY ) { const readline = await import('readline') const rl = readline.createInterface({ input: process.stdin, output: process.stdout, }) // biome-ignore lint/suspicious/noConsole: intentional dialog output console.log( `\nClaude Remote Control is launching in spawn mode which lets you create new sessions in this project from Claude Code on Web or your Mobile app. Learn more here: https://code.claude.com/docs/en/remote-control\n\n` + `Spawn mode for this project:\n` + ` [1] same-dir \u2014 sessions share the current directory (default)\n` + ` [2] worktree \u2014 each session gets an isolated git worktree\n\n` + `This can be changed later or explicitly set with --spawn=same-dir or --spawn=worktree.\n`, ) const answer = await new Promise<string>(resolve => { rl.question('Choose [1/2] (default: 1): ', resolve) }) rl.close() const chosen: 'same-dir' | 'worktree' = answer.trim() === '2' ? 'worktree' : 'same-dir' savedSpawnMode = chosen logEvent('tengu_bridge_spawn_mode_chosen', { spawn_mode: chosen as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, }) saveCurrentProjectConfig(current => { if (current.remoteControlSpawnMode === chosen) return current return { ...current, remoteControlSpawnMode: chosen } }) }
// Determine effective spawn mode. // Precedence: resume > explicit --spawn > saved project pref > gate default // - resuming via --continue / --session-id: always single-session (resume // targets one specific session in its original directory) // - explicit --spawn flag: use that value directly (does not persist) // - saved ProjectConfig.remoteControlSpawnMode: set by first-run dialog or `w` // - default with gate on: same-dir (persistent multi-session, shared cwd) // - default with gate off: single-session (unchanged legacy behavior) // Track how spawn mode was determined, for rollout analytics. type SpawnModeSource = 'resume' | 'flag' | 'saved' | 'gate_default' let spawnModeSource: SpawnModeSource let spawnMode: SpawnMode if (resumeSessionId) { spawnMode = 'single-session' spawnModeSource = 'resume' } else if (parsedSpawnMode !== undefined) { spawnMode = parsedSpawnMode spawnModeSource = 'flag' } else if (savedSpawnMode !== undefined) { spawnMode = savedSpawnMode spawnModeSource = 'saved' } else { spawnMode = multiSessionEnabled ? 'same-dir' : 'single-session' spawnModeSource = 'gate_default' } const maxSessions = spawnMode === 'single-session' ? 1 : (parsedCapacity ?? SPAWN_SESSIONS_DEFAULT) // Pre-create an empty session on start so the user has somewhere to type // immediately, running in the current directory (exempted from worktree // creation in the spawn loop). On by default; --no-create-session-in-dir // opts out for a pure on-demand server where every session is isolated. // The effectiveResumeSessionId guard at the creation site handles the // resume case (skip creation when resume succeeded; fall through to // fresh creation on env-mismatch fallback). const preCreateSession = parsedCreateSessionInDir ?? true
// Without --continue: a leftover pointer means the previous run didn't // shut down cleanly (crash, kill -9, terminal closed). Clear it so the // stale env doesn't linger past its relevance. Runs in all modes // (clearBridgePointer is a no-op when no file exists) — covers the // gate-transition case where a user crashed in single-session mode then // starts fresh in worktree mode. Only single-session mode writes new // pointers. if (!resumeSessionId) { const { clearBridgePointer } = await import('./bridgePointer.js') await clearBridgePointer(dir) }
// Worktree mode requires either git or WorktreeCreate/WorktreeRemove hooks. // Only reachable via explicit --spawn=worktree (default is same-dir); // saved worktree pref was already guarded above. if (spawnMode === 'worktree' && !worktreeAvailable) { // biome-ignore lint/suspicious/noConsole: intentional error output console.error( `Error: Worktree mode requires a git repository or WorktreeCreate hooks configured. Use --spawn=session for single-session mode.`, ) // eslint-disable-next-line custom-rules/no-process-exit process.exit(1) }
const branch = await getBranch() const gitRepoUrl = await getRemoteUrl() const machineName = hostname() const bridgeId = randomUUID()
const { handleOAuth401Error } = await import('../utils/auth.js') const api = createBridgeApiClient({ baseUrl, getAccessToken: getBridgeAccessToken, runnerVersion: MACRO.VERSION, onDebug: logForDebugging, onAuth401: handleOAuth401Error, getTrustedDeviceToken, })
// When resuming a session via --session-id, fetch it to learn its // environment_id and reuse that for registration (idempotent on the // backend). Left undefined otherwise — the backend rejects // client-generated UUIDs and will allocate a fresh environment. // feature('KAIROS') gate: --session-id is ant-only; parseArgs already // rejects the flag when the gate is off, so resumeSessionId is always // undefined here in external builds — this guard is for tree-shaking. let reuseEnvironmentId: string | undefined if (feature('KAIROS') && resumeSessionId) { try { validateBridgeId(resumeSessionId, 'sessionId') } catch { // biome-ignore lint/suspicious/noConsole: intentional error output console.error( `Error: Invalid session ID "${resumeSessionId}". Session IDs must not contain unsafe characters.`, ) // eslint-disable-next-line custom-rules/no-process-exit process.exit(1) } // Proactively refresh the OAuth token — getBridgeSession uses raw axios // without the withOAuthRetry 401-refresh logic. An expired-but-present // token would otherwise produce a misleading "not found" error. await checkAndRefreshOAuthTokenIfNeeded() clearOAuthTokenCache() const { getBridgeSession } = await import('./createSession.js') const session = await getBridgeSession(resumeSessionId, { baseUrl, getAccessToken: getBridgeAccessToken, }) if (!session) { // Session gone on server → pointer is stale. Clear it so the user // isn't re-prompted next launch. (Explicit --session-id leaves the // pointer alone — it's an independent file they may not even have.) // resumePointerDir may be a worktree sibling — clear THAT file. if (resumePointerDir) { const { clearBridgePointer } = await import('./bridgePointer.js') await clearBridgePointer(resumePointerDir) } // biome-ignore lint/suspicious/noConsole: intentional error output console.error( `Error: Session ${resumeSessionId} not found. It may have been archived or expired, or your login may have lapsed (run \`claude /login\`).`, ) // eslint-disable-next-line custom-rules/no-process-exit process.exit(1) } if (!session.environment_id) { if (resumePointerDir) { const { clearBridgePointer } = await import('./bridgePointer.js') await clearBridgePointer(resumePointerDir) } // biome-ignore lint/suspicious/noConsole: intentional error output console.error( `Error: Session ${resumeSessionId} has no environment_id. It may never have been attached to a bridge.`, ) // eslint-disable-next-line custom-rules/no-process-exit process.exit(1) } reuseEnvironmentId = session.environment_id logForDebugging( `[bridge:init] Resuming session ${resumeSessionId} on environment ${reuseEnvironmentId}`, ) }
const config: BridgeConfig = { dir, machineName, branch, gitRepoUrl, maxSessions, spawnMode, verbose, sandbox, bridgeId, workerType: 'claude_code', environmentId: randomUUID(), reuseEnvironmentId, apiBaseUrl: baseUrl, sessionIngressUrl, debugFile, sessionTimeoutMs, }
logForDebugging( `[bridge:init] bridgeId=${bridgeId}${reuseEnvironmentId ? ` reuseEnvironmentId=${reuseEnvironmentId}` : ''} dir=${dir} branch=${branch} gitRepoUrl=${gitRepoUrl} machine=${machineName}`, ) logForDebugging( `[bridge:init] apiBaseUrl=${baseUrl} sessionIngressUrl=${sessionIngressUrl}`, ) logForDebugging( `[bridge:init] sandbox=${sandbox}${debugFile ? ` debugFile=${debugFile}` : ''}`, )
// Register the bridge environment before entering the poll loop. let environmentId: string let environmentSecret: string try { const reg = await api.registerBridgeEnvironment(config) environmentId = reg.environment_id environmentSecret = reg.environment_secret } catch (err) { logEvent('tengu_bridge_registration_failed', { status: err instanceof BridgeFatalError ? err.status : undefined, }) // Registration failures are fatal — print a clean message instead of a stack trace. // biome-ignore lint/suspicious/noConsole:: intentional console output console.error( err instanceof BridgeFatalError && err.status === 404 ? 'Remote Control environments are not available for your account.' : `Error: ${errorMessage(err)}`, ) // eslint-disable-next-line custom-rules/no-process-exit process.exit(1) }
// Tracks whether the --session-id resume flow completed successfully. // Used below to skip fresh session creation and seed initialSessionId. // Cleared on env mismatch so we gracefully fall back to a new session. let effectiveResumeSessionId: string | undefined if (feature('KAIROS') && resumeSessionId) { if (reuseEnvironmentId && environmentId !== reuseEnvironmentId) { // Backend returned a different environment_id — the original env // expired or was reaped. Reconnect won't work against the new env // (session is bound to the old one). Log to sentry for visibility // and fall through to fresh session creation on the new env. logError( new Error( `Bridge resume env mismatch: requested ${reuseEnvironmentId}, backend returned ${environmentId}. Falling back to fresh session.`, ), ) // biome-ignore lint/suspicious/noConsole: intentional warning output console.warn( `Warning: Could not resume session ${resumeSessionId} — its environment has expired. Creating a fresh session instead.`, ) // Don't deregister — we're going to use this new environment. // effectiveResumeSessionId stays undefined → fresh session path below. } else { // Force-stop any stale worker instances for this session and re-queue // it so our poll loop picks it up. Must happen after registration so // the backend knows a live worker exists for the environment. // // The pointer stores a session_* ID but /bridge/reconnect looks // sessions up by their infra tag (cse_*) when ccr_v2_compat_enabled // is on. Try both; the conversion is a no-op if already cse_*. const infraResumeId = toInfraSessionId(resumeSessionId) const reconnectCandidates = infraResumeId === resumeSessionId ? [resumeSessionId] : [resumeSessionId, infraResumeId] let reconnected = false let lastReconnectErr: unknown for (const candidateId of reconnectCandidates) { try { await api.reconnectSession(environmentId, candidateId) logForDebugging( `[bridge:init] Session ${candidateId} re-queued via bridge/reconnect`, ) effectiveResumeSessionId = resumeSessionId reconnected = true break } catch (err) { lastReconnectErr = err logForDebugging( `[bridge:init] reconnectSession(${candidateId}) failed: ${errorMessage(err)}`, ) } } if (!reconnected) { const err = lastReconnectErr
// Do NOT deregister on transient reconnect failure — at this point // environmentId IS the session's own environment. Deregistering // would make retry impossible. The backend's 4h TTL cleans up. const isFatal = err instanceof BridgeFatalError // Clear pointer only on fatal reconnect failure. Transient failures // ("try running the same command again") should keep the pointer so // next launch re-prompts — that IS the retry mechanism. if (resumePointerDir && isFatal) { const { clearBridgePointer } = await import('./bridgePointer.js') await clearBridgePointer(resumePointerDir) } // biome-ignore lint/suspicious/noConsole: intentional error output console.error( isFatal ? `Error: ${errorMessage(err)}` : `Error: Failed to reconnect session ${resumeSessionId}: ${errorMessage(err)}\nThe session may still be resumable — try running the same command again.`, ) // eslint-disable-next-line custom-rules/no-process-exit process.exit(1) } } }
logForDebugging( `[bridge:init] Registered, server environmentId=${environmentId}`, ) const startupPollConfig = getPollIntervalConfig() logEvent('tengu_bridge_started', { max_sessions: config.maxSessions, has_debug_file: !!config.debugFile, sandbox: config.sandbox, verbose: config.verbose, heartbeat_interval_ms: startupPollConfig.non_exclusive_heartbeat_interval_ms, spawn_mode: config.spawnMode as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, spawn_mode_source: spawnModeSource as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, multi_session_gate: multiSessionEnabled, pre_create_session: preCreateSession, worktree_available: worktreeAvailable, }) logForDiagnosticsNoPII('info', 'bridge_started', { max_sessions: config.maxSessions, sandbox: config.sandbox, spawn_mode: config.spawnMode, })
const spawner = createSessionSpawner({ execPath: process.execPath, scriptArgs: spawnScriptArgs(), env: process.env, verbose, sandbox, debugFile, permissionMode, onDebug: logForDebugging, onActivity: (sessionId, activity) => { logForDebugging( `[bridge:activity] sessionId=${sessionId} ${activity.type} ${activity.summary}`, ) }, onPermissionRequest: (sessionId, request, _accessToken) => { logForDebugging( `[bridge:perm] sessionId=${sessionId} tool=${request.request.tool_name} request_id=${request.request_id} (not auto-approving)`, ) }, })
const logger = createBridgeLogger({ verbose }) const { parseGitHubRepository } = await import('../utils/detectRepository.js') const ownerRepo = gitRepoUrl ? parseGitHubRepository(gitRepoUrl) : null // Use the repo name from the parsed owner/repo, or fall back to the dir basename const repoName = ownerRepo ? ownerRepo.split('/').pop()! : basename(dir) logger.setRepoInfo(repoName, branch)
// `w` toggle is available iff we're in a multi-session mode AND worktree // is a valid option. When unavailable, the mode suffix and hint are hidden. const toggleAvailable = spawnMode !== 'single-session' && worktreeAvailable if (toggleAvailable) { // Safe cast: spawnMode is not single-session (checked above), and the // saved-worktree-in-non-git guard + exit check above ensure worktree // is only reached when available. logger.setSpawnModeDisplay(spawnMode as 'same-dir' | 'worktree') }
// Listen for keys: space toggles QR code, w toggles spawn mode const onStdinData = (data: Buffer): void => { if (data[0] === 0x03 || data[0] === 0x04) { // Ctrl+C / Ctrl+D — trigger graceful shutdown process.emit('SIGINT') return } if (data[0] === 0x20 /* space */) { logger.toggleQr() return } if (data[0] === 0x77 /* 'w' */) { if (!toggleAvailable) return const newMode: 'same-dir' | 'worktree' = config.spawnMode === 'same-dir' ? 'worktree' : 'same-dir' config.spawnMode = newMode logEvent('tengu_bridge_spawn_mode_toggled', { spawn_mode: newMode as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, }) logger.logStatus( newMode === 'worktree' ? 'Spawn mode: worktree (new sessions get isolated git worktrees)' : 'Spawn mode: same-dir (new sessions share the current directory)', ) logger.setSpawnModeDisplay(newMode) logger.refreshDisplay() saveCurrentProjectConfig(current => { if (current.remoteControlSpawnMode === newMode) return current return { ...current, remoteControlSpawnMode: newMode } }) return } } if (process.stdin.isTTY) { process.stdin.setRawMode(true) process.stdin.resume() process.stdin.on('data', onStdinData) }
const controller = new AbortController() const onSigint = (): void => { logForDebugging('[bridge:shutdown] SIGINT received, shutting down') controller.abort() } const onSigterm = (): void => { logForDebugging('[bridge:shutdown] SIGTERM received, shutting down') controller.abort() } process.on('SIGINT', onSigint) process.on('SIGTERM', onSigterm)
// Auto-create an empty session so the user has somewhere to type // immediately (matching /remote-control behavior). Controlled by // preCreateSession: on by default; --no-create-session-in-dir opts out. // When a --session-id resume succeeded, skip creation entirely — the // session already exists and bridge/reconnect has re-queued it. // When resume was requested but failed on env mismatch, effectiveResumeSessionId // is undefined, so we fall through to fresh session creation (honoring the // "Creating a fresh session instead" warning printed above). let initialSessionId: string | null = feature('KAIROS') && effectiveResumeSessionId ? effectiveResumeSessionId : null if (preCreateSession && !(feature('KAIROS') && effectiveResumeSessionId)) { const { createBridgeSession } = await import('./createSession.js') try { initialSessionId = await createBridgeSession({ environmentId, title: name, events: [], gitRepoUrl, branch, signal: controller.signal, baseUrl, getAccessToken: getBridgeAccessToken, permissionMode, }) if (initialSessionId) { logForDebugging( `[bridge:init] Created initial session ${initialSessionId}`, ) } } catch (err) { logForDebugging( `[bridge:init] Session creation failed (non-fatal): ${errorMessage(err)}`, ) } }
// Crash-recovery pointer: write immediately so kill -9 at any point // after this leaves a recoverable trail. Covers both fresh sessions and // resumed ones (so a second crash after resume is still recoverable). // Cleared when runBridgeLoop falls through to archive+deregister; left in // place on the SIGINT resumable-shutdown return (backup for when the user // closes the terminal before copying the printed --session-id hint). // Refreshed hourly so a 5h+ session that crashes still has a fresh // pointer (staleness checks file mtime, backend TTL is rolling-from-poll). let pointerRefreshTimer: ReturnType<typeof setInterval> | null = null // Single-session only: --continue forces single-session mode on resume, // so a pointer written in multi-session mode would contradict the user's // config when they try to resume. The resumable-shutdown path is also // gated to single-session (line ~1254) so the pointer would be orphaned. if (initialSessionId && spawnMode === 'single-session') { const { writeBridgePointer } = await import('./bridgePointer.js') const pointerPayload = { sessionId: initialSessionId, environmentId, source: 'standalone' as const, } await writeBridgePointer(config.dir, pointerPayload) pointerRefreshTimer = setInterval( writeBridgePointer, 60 * 60 * 1000, config.dir, pointerPayload, ) // Don't let the interval keep the process alive on its own. pointerRefreshTimer.unref?.() }
try { await runBridgeLoop( config, environmentId, environmentSecret, api, spawner, logger, controller.signal, undefined, initialSessionId ?? undefined, async () => { // Clear the memoized OAuth token cache so we re-read from secure // storage, picking up tokens refreshed by child processes. clearOAuthTokenCache() // Proactively refresh the token if it's expired on disk too. await checkAndRefreshOAuthTokenIfNeeded() return getBridgeAccessToken() }, ) } finally { if (pointerRefreshTimer !== null) { clearInterval(pointerRefreshTimer) } process.off('SIGINT', onSigint) process.off('SIGTERM', onSigterm) process.stdin.off('data', onStdinData) if (process.stdin.isTTY) { process.stdin.setRawMode(false) } process.stdin.pause() }
// The bridge bypasses init.ts (and its graceful shutdown handler), so we // must exit explicitly. // eslint-disable-next-line custom-rules/no-process-exit process.exit(0)}
// ─── Headless bridge (daemon worker) ────────────────────────────────────────
/** * Thrown by runBridgeHeadless for configuration issues the supervisor should * NOT retry (trust not accepted, worktree unavailable, http-not-https). The * daemon worker catches this and exits with EXIT_CODE_PERMANENT so the * supervisor parks the worker instead of respawning it on backoff. */export class BridgeHeadlessPermanentError extends Error { constructor(message: string) { super(message) this.name = 'BridgeHeadlessPermanentError' }}
export type HeadlessBridgeOpts = { dir: string name?: string spawnMode: 'same-dir' | 'worktree' capacity: number permissionMode?: string sandbox: boolean sessionTimeoutMs?: number createSessionOnStart: boolean getAccessToken: () => string | undefined onAuth401: (failedToken: string) => Promise<boolean> log: (s: string) => void}
/** * Non-interactive bridge entrypoint for the `remoteControl` daemon worker. * * Linear subset of bridgeMain(): no readline dialogs, no stdin key handlers, * no TUI, no process.exit(). Config comes from the caller (daemon.json), auth * comes via IPC (supervisor's AuthManager), logs go to the worker's stdout * pipe. Throws on fatal errors — the worker catches and maps permanent vs * transient to the right exit code. * * Resolves cleanly when `signal` aborts and the poll loop tears down. */export async function runBridgeHeadless( opts: HeadlessBridgeOpts, signal: AbortSignal,): Promise<void> { const { dir, log } = opts
// Worker inherits the supervisor's CWD. chdir first so git utilities // (getBranch/getRemoteUrl) — which read from bootstrap CWD state set // below — resolve against the right repo. process.chdir(dir) const { setOriginalCwd, setCwdState } = await import('../bootstrap/state.js') setOriginalCwd(dir) setCwdState(dir)
const { enableConfigs, checkHasTrustDialogAccepted } = await import( '../utils/config.js' ) enableConfigs() const { initSinks } = await import('../utils/sinks.js') initSinks()
if (!checkHasTrustDialogAccepted()) { throw new BridgeHeadlessPermanentError( `Workspace not trusted: ${dir}. Run \`claude\` in that directory first to accept the trust dialog.`, ) }
if (!opts.getAccessToken()) { // Transient — supervisor's AuthManager may pick up a token on next cycle. throw new Error(BRIDGE_LOGIN_ERROR) }
const { getBridgeBaseUrl } = await import('./bridgeConfig.js') const baseUrl = getBridgeBaseUrl() if ( baseUrl.startsWith('http://') && !baseUrl.includes('localhost') && !baseUrl.includes('127.0.0.1') ) { throw new BridgeHeadlessPermanentError( 'Remote Control base URL uses HTTP. Only HTTPS or localhost HTTP is allowed.', ) } const sessionIngressUrl = process.env.USER_TYPE === 'ant' && process.env.CLAUDE_BRIDGE_SESSION_INGRESS_URL ? process.env.CLAUDE_BRIDGE_SESSION_INGRESS_URL : baseUrl
const { getBranch, getRemoteUrl, findGitRoot } = await import( '../utils/git.js' ) const { hasWorktreeCreateHook } = await import('../utils/hooks.js')
if (opts.spawnMode === 'worktree') { const worktreeAvailable = hasWorktreeCreateHook() || findGitRoot(dir) !== null if (!worktreeAvailable) { throw new BridgeHeadlessPermanentError( `Worktree mode requires a git repository or WorktreeCreate hooks. Directory ${dir} has neither.`, ) } }
const branch = await getBranch() const gitRepoUrl = await getRemoteUrl() const machineName = hostname() const bridgeId = randomUUID()
const config: BridgeConfig = { dir, machineName, branch, gitRepoUrl, maxSessions: opts.capacity, spawnMode: opts.spawnMode, verbose: false, sandbox: opts.sandbox, bridgeId, workerType: 'claude_code', environmentId: randomUUID(), apiBaseUrl: baseUrl, sessionIngressUrl, sessionTimeoutMs: opts.sessionTimeoutMs, }
const api = createBridgeApiClient({ baseUrl, getAccessToken: opts.getAccessToken, runnerVersion: MACRO.VERSION, onDebug: log, onAuth401: opts.onAuth401, getTrustedDeviceToken, })
let environmentId: string let environmentSecret: string try { const reg = await api.registerBridgeEnvironment(config) environmentId = reg.environment_id environmentSecret = reg.environment_secret } catch (err) { // Transient — let supervisor backoff-retry. throw new Error(`Bridge registration failed: ${errorMessage(err)}`) }
const spawner = createSessionSpawner({ execPath: process.execPath, scriptArgs: spawnScriptArgs(), env: process.env, verbose: false, sandbox: opts.sandbox, permissionMode: opts.permissionMode, onDebug: log, })
const logger = createHeadlessBridgeLogger(log) logger.printBanner(config, environmentId)
let initialSessionId: string | undefined if (opts.createSessionOnStart) { const { createBridgeSession } = await import('./createSession.js') try { const sid = await createBridgeSession({ environmentId, title: opts.name, events: [], gitRepoUrl, branch, signal, baseUrl, getAccessToken: opts.getAccessToken, permissionMode: opts.permissionMode, }) if (sid) { initialSessionId = sid log(`created initial session ${sid}`) } } catch (err) { log(`session pre-creation failed (non-fatal): ${errorMessage(err)}`) } }
await runBridgeLoop( config, environmentId, environmentSecret, api, spawner, logger, signal, undefined, initialSessionId, async () => opts.getAccessToken(), )}
/** BridgeLogger adapter that routes everything to a single line-log fn. */function createHeadlessBridgeLogger(log: (s: string) => void): BridgeLogger { const noop = (): void => {} return { printBanner: (cfg, envId) => log( `registered environmentId=${envId} dir=${cfg.dir} spawnMode=${cfg.spawnMode} capacity=${cfg.maxSessions}`, ), logSessionStart: (id, _prompt) => log(`session start ${id}`), logSessionComplete: (id, ms) => log(`session complete ${id} (${ms}ms)`), logSessionFailed: (id, err) => log(`session failed ${id}: ${err}`), logStatus: log, logVerbose: log, logError: s => log(`error: ${s}`), logReconnected: ms => log(`reconnected after ${ms}ms`), addSession: (id, _url) => log(`session attached ${id}`), removeSession: id => log(`session detached ${id}`), updateIdleStatus: noop, updateReconnectingStatus: noop, updateSessionStatus: noop, updateSessionActivity: noop, updateSessionCount: noop, updateFailedStatus: noop, setSpawnModeDisplay: noop, setRepoInfo: noop, setDebugLogPath: noop, setAttached: noop, setSessionTitle: noop, clearStatus: noop, toggleQr: noop, refreshDisplay: noop, }}