/* eslint-disable max-lines -- Why: OrcaRuntimeService still owns the mutable live graph, PTY handles, waiters, mobile floor/layout state, and managed-worktree reconciliation. Stateless browser and file command adapters live beside it; the remaining split points need state-owner extraction before enforcing max-lines. */ /* eslint-disable unicorn/no-useless-spread -- Why: waiter sets and handle keys are cloned intentionally before mutation so resolution and rejection can safely remove entries while iterating. */ /* eslint-disable no-control-regex -- Why: terminal normalization must strip ANSI and OSC control sequences from PTY output before returning bounded text to agents. */ import { extractLastOscTitle, detectAgentStatusFromTitle, isClaudeManagementTitle, isShellProcess } from '../../shared/agent-detection' import { extractOscTitleScanTail } from '../../shared/osc-title-scan-tail' import type { AgentStatus } from '../../shared/agent-detection' import type { TerminalOscLinkRange } from '../../shared/terminal-osc-link-ranges' import { AGENT_STATUS_STALE_AFTER_MS, type AgentStatusIpcPayload, type ParsedAgentStatusPayload, type AgentStatusOrchestrationContext, type AgentStatusEntry } from '../../shared/agent-status-types' import { normalizeCompatibleAgentStatusEntryForOwner, normalizeCompatibleAgentTitleForOwner } from '../../shared/agent-title-owner' import { createAgentStatusOscProcessor, type ProcessedAgentStatusChunk } from '../../shared/agent-status-osc' import { buildOrchestrationTaskDisplayMetadata } from '../../shared/orchestration-task-display' import { isTerminalInputTooLargeWithYield, TERMINAL_INPUT_TOO_LARGE_ERROR, iterateTerminalInputChunks } from '../../shared/terminal-input' import { gitExecFileAsync, wslAwareSpawn } from '../git/runner' import { cleanupClaimedCloneTarget, claimCloneTarget, deriveValidatedClonePath, getClonePathComparisonKey } from '../git/repo-clone-path' import { getGitCloneFailureMessage } from '../../shared/git-clone-failure-message' import { createHash, randomUUID } from 'node:crypto' import { homedir } from 'node:os' import { isAbsolute, join, resolve } from 'node:path' import { mkdir, readFile, readdir, rm, stat } from 'node:fs/promises' import { OrchestrationDb } from './orchestration/db' import { formatMessagesForInjection } from './orchestration/formatter' import type { Automation, AutomationCreateInput, AutomationRun, AutomationUpdateInput, AutomationWorkspaceMode } from '../../shared/automations-types' import type { AutomationWorkspaceProvenance, BaseRefSearchResult, CreateWorktreeResult, DetectedWorktree, DetectedWorktreeListResult, ForceDeleteWorktreeBranchResult, GitHubPrStartPoint, GitPushTarget, GitWorktreeInfo, GitHubCreateIssueFields, GitHubOwnerRepo, GlobalSettings, PersistedUIState, Project, ProjectUpdateArgs, ProjectHostSetup, ProjectHostSetupCloneArgs, ProjectHostSetupCreateArgs, ProjectHostSetupCreateResult, ProjectHostSetupDeleteArgs, ProjectHostSetupDeleteResult, ProjectHostSetupExistingFolderArgs, ProjectHostSetupResult, ProjectHostSetupUpdateArgs, ProjectHostSetupUpdateResult, Repo, RemoveWorktreeResult, StatsSummary, Worktree, WorktreeLineage, WorkspaceLineage, WorkspaceKey, WorktreeLineageWarning, WorktreeMeta, WorktreeBaseStatusEvent, WorktreeRemoteBranchConflictEvent, WorktreeStartupLaunch, LinearCustomViewModel, JiraConnectArgs, JiraCreateIssueArgs, JiraIssueFilter, JiraIssueUpdate, JiraSiteSelection, LinearIssueUpdate, LinearProjectSummary, LinearWorkspaceSelection, NestedRepoScanResult, ProjectGroup, FolderWorkspace, ProjectGroupImportMode, ProjectGroupImportResult, MemorySnapshot, Tab, TabGroupLayoutNode, TerminalLayoutSnapshot, TerminalPaneLayoutNode, TerminalTab, TuiAgent, WorkspaceCreateTelemetrySource, WorkspaceSessionState, DirEntry } from '../../shared/types' import type { SleepingAgentLaunchConfig } from '../../shared/agent-session-resume' import type { RuntimeClientEvent } from '../../shared/runtime-client-events' import { toRuntimeActivateWorktreeEvent } from '../../shared/runtime-client-events' import type { LinearCurrentIssueContextHints, LinearAttachResult, LinearCommentAddResult, LinearCreateResult, LinearErrorCode, LinearIssueListFilter, LinearIssueListResult, LinearProjectListResult, LinearIssueSummary, LinearIssueRequest, LinearIssueTaskUpdateRequest, LinearIssueTaskUpdateResult, LinearTeamLabelsResult, LinearTeamListResult, LinearTeamMembersResult, LinearTeamStatesResult, LinearStatusSetResult } from '../../shared/linear-agent-access' import { LINEAR_SEARCH_MAX_LIMIT, LINEAR_WRITE_BODY_CAP, clampLinearSearchLimit } from '../../shared/linear-agent-access' import { isLinearUuid } from '../../shared/linear-uuid' import type { FeatureInteractionId } from '../../shared/feature-interactions' import type { TerminalPaneSplitSource } from '../../shared/feature-education-telemetry' import { FOLDER_WORKSPACE_INSTANCE_SEPARATOR, splitWorktreeId, splitWorktreeIdForFilesystem } from '../../shared/worktree-id' import { getProjectHostSetupForRepo, getProjectHostSetupWorktreeMeta } from '../../shared/project-host-setup-projection' import { parsePtySessionId } from '../../shared/pty-session-id-format' import { clampLinearIssueListLimit } from '../../shared/linear-issue-read-limits' import { isFolderRepo } from '../../shared/repo-kind' import { DEFAULT_WORKSPACE_STATUS_ID } from '../../shared/workspace-statuses' import { buildSetupRunnerCommand, getSetupRunnerCommandPlatformForPath } from '../../shared/setup-runner-command' import { createSequencedSetupAgentCommands, SETUP_AGENT_SEQUENCE_STARTUP_COMMAND_ENV } from '../../shared/setup-agent-sequencing' import { TASK_PROVIDERS } from '../../shared/task-providers' import { FIRST_PANE_ID } from '../../shared/pane-key' import { isTerminalLeafId, makePaneKey, parsePaneKey } from '../../shared/stable-pane-id' import { parseAppSshPtyId } from '../../shared/ssh-pty-id' import { isValidHostTerminalTabId } from '../../shared/terminal-tab-id' import { buildAgentDraftLaunchPlan, buildAgentStartupPlan } from '../../shared/tui-agent-startup' import { repoIsRemote } from '../../shared/agent-launch-remote' import { isAgentForegroundWrapperProcess, isExpectedAgentProcess, recognizeAgentProcess } from '../../shared/agent-process-recognition' import { isTuiAgentEnabled, pickTuiAgent } from '../../shared/tui-agent-selection' import { resolveTuiAgentLaunchArgs, resolveTuiAgentLaunchEnv } from '../../shared/tui-agent-launch-defaults' import { isTuiAgent, TUI_AGENT_CONFIG } from '../../shared/tui-agent-config' import { createDraftPasteReadyScanner } from '../../shared/draft-paste-ready-scanner' import { detectInstalledAgentsWithShellPathHydration, detectRemoteAgents } from '../ipc/preflight' import { markCodexProjectTrusted, markCopilotFolderTrusted, markCursorWorkspaceTrusted } from '../agent-trust-presets' import { markRemoteAgentWorkspaceTrusted } from '../remote-agent-trust-presets' import { applyAgentStatusHooksEnabled } from '../agent-hooks/managed-agent-hook-controls' import { isWindowsAbsolutePathLike, isPathInsideOrEqual, normalizeRuntimePathForComparison } from '../../shared/cross-platform-path' import { isWslUncPath } from '../../shared/wsl-paths' import { folderWorkspaceKey, isWorkspaceKey, parseWorkspaceKey, worktreeWorkspaceKey } from '../../shared/workspace-scope' import { folderWorkspaceToWorktree } from '../../shared/folder-workspace-worktree' import type { FolderWorkspacePathStatus, FolderWorkspacePathStatusRequest } from '../../shared/folder-workspace-path-status' import { buildKnownOrcaWorkspaceLayouts, isLegacyRepoForExternalWorktreeVisibility, toDetectedWorktree } from '../../shared/worktree-ownership' import { BROWSER_HEADLESS_RUNTIME_CAPABILITY, MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION, RUNTIME_CAPABILITIES, RUNTIME_PROTOCOL_VERSION, type RuntimeCapability } from '../../shared/protocol-version' import type { WorkspacePortKillRequest, WorkspacePortKillResult, WorkspacePortProbe, WorkspacePortScanResult } from '../../shared/workspace-ports' import { filterWorkspacePortProbes, killWorkspacePort, scanWorkspacePortProbes } from '../ports/workspace-port-ownership' import { advertisedUrlWatcher } from '../ports/advertised-url-watcher' import type { RuntimeGraphStatus, RuntimeRepoSearchRefs, RuntimeTerminalRead, RuntimeTerminalRename, RuntimeTerminalAgentStatus, RuntimeTerminalSend, RuntimeTerminalCreate, RuntimeTerminalPresentation, RuntimeTerminalSplit, RuntimeTerminalFocus, RuntimeTerminalClose, RuntimeTerminalListResult, RuntimeTerminalResolvePane, RuntimeTerminalState, RuntimeStatus, RuntimeSyncWindowGraphResult, RuntimeTerminalWait, RuntimeTerminalWaitBlockedReason, RuntimeTerminalWaitCondition, RuntimeWorktreePsSummary, RuntimeWorktreeAgentRow, RuntimeWorktreeStatus, RuntimeSpeechModelSummary, RuntimeSpeechSetupState, RuntimeTerminalShow, RuntimeTerminalSummary, RuntimeTerminalVisualGroupNode, RuntimeTerminalVisualLayout, RuntimeTerminalVisualLayoutNode, RuntimeTerminalVisualPaneNode, RuntimeTerminalVisualTab, RuntimeSyncedLeaf, RuntimeSyncedTab, RuntimeMarkdownReadTabResult, RuntimeMarkdownSaveTabResult, RuntimeMobileSessionCreateTerminalResult, RuntimeMobileSessionClientTab, RuntimeMobileSessionMarkdownTab, RuntimeMobileSessionTabMove, RuntimeMobileSessionTabMoveResult, RuntimeMobileSessionTabGroup, RuntimeMobileSessionSnapshotTab, RuntimeMobileSessionTerminalTab, RuntimeMobileSessionBrowserTab, RuntimeMobileSessionTabsRemovedResult, RuntimeMobileSessionTabsResult, RuntimeMobileSessionTabsSnapshot, RuntimeBrowserDriverState, RuntimeTerminalDriverState, RuntimeSyncWindowGraph, RuntimeWorktreeListResult, BrowserTabInfo, BrowserScreencastResult } from '../../shared/runtime-types' import type { AutomationService } from '../automations/service' import { RuntimeBrowserCommands } from './orca-runtime-browser' import { buildHeadlessTerminalSplitLayout } from './headless-terminal-split-layout' import { buildHeadlessTabGroupMove, buildHeadlessTabGroupSplit } from './headless-tab-group-split-layout' import { RuntimeEmulatorCommands, setEmulatorBridge } from './orca-runtime-emulator' import { serveSimStateWatcher } from '../emulator/serve-sim-state-watcher' import type { EmulatorBridge } from '../emulator/emulator-bridge' import { RuntimeFileCommands } from './orca-runtime-files' import { RuntimeGitCommands } from './orca-runtime-git' import { ClaudeAgentTeamsService } from './claude-agent-teams-service' import type { AgentTeamsTmuxCompatRequest, AgentTeamsTmuxCompatResponse } from './claude-agent-teams-service' import { buildClaudeAgentTeamsLaunchPlan, ensureClaudeAgentTeamsShimDir, resolveClaudeAgentTeamsShimBin } from './claude-agent-teams-shim-env' import { addClaudeTeammateModeAuto, addClaudeTeammateModeInProcess, type ClaudeAgentTeamsMode } from '../../shared/claude-agent-teams-tmux-compat' import { joinWorktreeRelativePath } from './runtime-relative-paths' import { collectMemorySnapshot } from '../memory/collector' import { BrowserWindow, ipcMain } from 'electron' import type { AgentBrowserBridge } from '../browser/agent-browser-bridge' import type { BrowserBackend } from '../browser/browser-backend' import { BrowserError } from '../browser/cdp-bridge' import { getPRForBranch, getRepoSlug, getRepoUpstream, getWorkItem, listIssues as listGitHubIssues, listWorkItems, countWorkItems, getPRChecks, getPRCheckDetails, rerunPRChecks, getPRComments, getIssue, resolveReviewThread, setPRFileViewed, getWorkItemByOwnerRepo, updatePRTitle, updatePRDetails, mergePR, setPRAutoMerge, updatePRState, requestPRReviewers, removePRReviewers, createIssue, updateIssue, addIssueComment, addPRReviewComment, addPRReviewCommentReply, listLabels, listAssignableUsers } from '../github/client' import type { GitHubPRBranchLookupOptions } from '../github/client' import { resolveGitHubPrStartPoint } from '../github/pr-start-point' import { fetchPrHeadTrackingRef } from '../github/pr-head-tracking-ref' import { getWorkItemDetails, getPRFileContents } from '../github/work-item-details' import { getRateLimit } from '../github/rate-limit' import { closeMR as closeGitLabMR, createIssue as createGitLabIssue, diagnoseAuth as diagnoseGitLabAuthClient, getJobTrace as getGitLabJobTrace, getProjectRefForRemote as getGitLabProjectRefForRemote, getRateLimit as getGitLabRateLimit, getWorkItemByProjectRef as getGitLabWorkItemByProjectRef, addIssueComment as addGitLabIssueComment, addMRInlineComment as addGitLabMRInlineComment, addMRComment as addGitLabMRComment, listTodos as listGitLabTodos, listIssues as listGitLabIssues, listLabels as listGitLabLabels, listMergeRequests as listGitLabMergeRequests, listWorkItems as listGitLabWorkItems, mergeMR as mergeGitLabMR, reopenMR as reopenGitLabMR, resolveMRDiscussion as resolveGitLabMRDiscussion, retryJob as retryGitLabJob, updateMR as updateGitLabMR, updateMRReviewers as updateGitLabMRReviewers, updateIssue as updateGitLabIssue } from '../gitlab/client' import { getGlabKnownHosts } from '../gitlab/gl-utils' import { getWorkItemDetails as getGitLabWorkItemDetails } from '../gitlab/work-item-details' import { normalizeGitLabIssueListArgs, normalizeGitLabMRListState, normalizeGitLabPositiveInteger, type GitLabIssueListState } from '../gitlab/gitlab-preload-args' import { recordGitLabProjectRecent } from '../gitlab/gitlab-project-recents' import type { GitHubIssueUpdate, GitHubPullRequestStateUpdate, GitHubPRFile, GitHubPRReviewCommentInput, GitLabIssueUpdate, GitLabMRInlineCommentInput, GitLabProjectRef, GitLabWorkItem, MRListState } from '../../shared/types' import { inspectSetupScriptImportCandidates } from '../../shared/setup-script-imports' import type { CreateHostedReviewInput, CreateHostedReviewResult, HostedReviewCreationEligibility, HostedReviewCreationEligibilityArgs, HostedReviewInfo } from '../../shared/hosted-review' import { getHostedReviewForBranch as getHostedReviewForBranchFromRepo } from '../source-control/hosted-review' import type { ForgeProviderId } from '../source-control/forge-provider' import { createHostedReview as createHostedReviewFromRepo, getHostedReviewCreationEligibility as getHostedReviewCreationEligibilityFromRepo } from '../source-control/hosted-review-creation' import { getLocalProjectGitExecOptions, getLocalProjectWorktreeGitOptions, resolveLocalProjectRuntimeForRepo } from '../project-runtime-git-options' import type { ProjectExecutionRuntimeResolution } from '../../shared/project-execution-runtime' import { getLocalWorktreePathAccess, removeLocalWorktreePath, toLocalWorktreeRuntimePath } from '../local-worktree-filesystem' import { pruneStaleLocalWorktreeRegistrationAfterFilesystemRemoval, recoverLocalWindowsLongPathWorktreeRemoval } from '../local-worktree-removal-recovery' import { connect as connectLinear, disconnect as disconnectLinear, getStatus as getLinearStatus, isAuthError as isLinearAuthError, selectWorkspace as selectLinearWorkspace, testConnection as testLinearConnection } from '../linear/client' import { addIssueComment as addLinearIssueComment, addIssueCommentForAgent as addLinearIssueCommentForAgent, createIssueAttachment as createLinearIssueAttachment, createIssueForAgent as createLinearIssueForAgent, createIssue as createLinearIssue, getAttachmentByUuidForAgent as getLinearAttachmentByUuidForAgent, getCommentByUuidForAgent as getLinearCommentByUuidForAgent, getIssue as getLinearIssue, getIssueByUuidForAgent as getLinearIssueByUuidForAgent, getIssueCommentThreadRoot as getLinearIssueCommentThreadRoot, getIssueComments as getLinearIssueComments, listIssues as listLinearIssues, searchIssues as searchLinearIssues, updateIssueForAgent as updateLinearIssueForAgent, updateIssue as updateLinearIssue, LinearWriteFailure, type LinearListFilter } from '../linear/issues' import { LinearAgentAccessError, getLinearCurrentIssueFromWorktree, readLinearIssueContext, resolveLegacyLinearLinkWorkspace, searchLinearIssuesForAgents } from '../linear/issue-context' import { classifyLinearError, linearError, linearMessage, sanitizeLinearErrorMessage } from '../linear/issue-context-errors' import { createProject as createLinearProject, getCustomView as getLinearCustomView, getProject as getLinearProject, listCustomViewIssues as listLinearCustomViewIssues, listCustomViewProjects as listLinearCustomViewProjects, listCustomViews as listLinearCustomViews, listProjectsByExactName as listLinearProjectsByExactName, listProjectIssues as listLinearProjectIssues, listProjectTeams as listLinearProjectTeams, listProjects as listLinearProjects, type LinearProjectCreateInput } from '../linear/projects' import { getTeamLabels as getLinearTeamLabels, getTeamLabelsOrThrow as getLinearTeamLabelsOrThrow, getTeamMembers as getLinearTeamMembers, getTeamMembersOrThrow as getLinearTeamMembersOrThrow, getTeamStates as getLinearTeamStates, getTeamStatesOrThrow as getLinearTeamStatesOrThrow, getViewerForWorkspaceOrThrow as getLinearViewerForWorkspaceOrThrow, listTeamsForAgent as listLinearTeamsForAgent, listTeams as listLinearTeams, listTeamsOrThrow as listLinearTeamsOrThrow } from '../linear/teams' import { connect as connectJira, disconnect as disconnectJira, getStatus as getJiraStatus, selectSite as selectJiraSite, testConnection as testJiraConnection } from '../jira/client' import { addIssueComment as addJiraIssueComment, createIssue as createJiraIssue, getIssue as getJiraIssue, getIssueComments as getJiraIssueComments, listAssignableUsers as listJiraAssignableUsers, listCreateFields as listJiraCreateFields, listIssueTypes as listJiraIssueTypes, listIssues as listJiraIssues, listPriorities as listJiraPriorities, listProjects as listJiraProjects, listTransitions as listJiraTransitions, searchIssues as searchJiraIssues, updateIssue as updateJiraIssue } from '../jira/issues' import { clearProjectItemFieldValue, getProjectViewTable, getWorkItemDetailsBySlug, listAccessibleProjects, listProjectViews, resolveProjectRef, addIssueCommentBySlug, deleteIssueCommentBySlug, listAssignableUsersBySlug, listIssueTypesBySlug, listLabelsBySlug, updateIssueCommentBySlug, updateIssueBySlug, updateIssueTypeBySlug, updateProjectItemFieldValue, updatePullRequestBySlug } from '../github/project-view' import type { ClearProjectItemFieldArgs, GetProjectViewTableArgs, ListAssignableUsersBySlugArgs, ListIssueTypesBySlugArgs, ListLabelsBySlugArgs, ListProjectViewsArgs, ProjectWorkItemDetailsBySlugArgs, ResolveProjectRefArgs, AddIssueCommentBySlugArgs, DeleteIssueCommentBySlugArgs, UpdateIssueBySlugArgs, UpdateIssueCommentBySlugArgs, UpdateIssueTypeBySlugArgs, UpdateProjectItemFieldArgs, UpdatePullRequestBySlugArgs } from '../../shared/github-project-types' import { getGitUsername, getBaseRefDefault, getDefaultBaseRef, getDefaultRemote, getBranchConflictKind, isGitRepo, getRepoName, searchBaseRefDetails, getRemoteCount, normalizeRefSearchQuery, parseAndFilterSearchRefDetails, parseRemoteCount, resolveDefaultBaseRefViaExec, buildSearchBaseRefsArgv, isForEachRefExcludeUnsupportedError, mergeBaseRefSearchResultGroups, getRemoteDrift, getRecentDriftSubjects } from '../git/repo' import { hasLocalCommitObject } from '../git/commit-object-ref' import { listWorktrees, listWorktreesStrict, addWorktree, addSparseWorktree, assertWorktreeCleanForRemoval, forceDeleteLocalBranch, removeWorktree } from '../git/worktree' import type { AddWorktreeOptions, AddWorktreeResult } from '../git/worktree' import { isENOENT } from '../ipc/filesystem-auth' import { createSetupRunnerScript, getDefaultTabCommandTrustContent, getDefaultTabsLaunch, getEffectiveHooks, getEffectiveSetupRunPolicy, hasUnrecognizedOrcaYamlKeys, hasHooksFile, loadHooks, parseOrcaYaml, readIssueCommand, runHook, shouldRunSetupForCreate, writeIssueCommand } from '../hooks' import { DEFAULT_REPO_BADGE_COLOR, FLOATING_TERMINAL_WORKTREE_ID, getDefaultVoiceSettings } from '../../shared/constants' import { listRepoWorktrees } from '../repo-worktrees' import { createWorktreeLinkedPaths, removeWorktreeLinkedPaths } from '../ipc/worktree-symlinks' import { deleteWorktreeHistoryDir } from '../terminal-history' import { cleanupUnusedWorktreePushTargetRemote, cleanupUnusedWorktreePushTargetRemoteSsh, createRemoteWorktree, configureCreatedWorktreePushTarget, prepareWorktreePushTarget } from '../ipc/worktree-remote' import { getBranchNameOverrideCandidate, getWorktreeCreateCandidate, WORKTREE_CREATE_MAX_SUFFIX_ATTEMPTS } from '../worktree-create-candidates' import { normalizeSparseDirectories } from '../ipc/sparse-checkout-directories' import type { Store } from '../persistence' import type { StatsCollector } from '../stats/collector' import { AgentDetector } from '../stats/agent-detector' import { computeBranchName, computeWorktreePath, computeWorkspaceRoot, ensurePathWithinWorkspace, formatWorktreeRemovalError, getWorktreeCreationLayout, getWorktreePathSettings, isOrphanCompatiblePreflightError, isOrphanedWorktreeError, mergeWorktree, sanitizeWorktreeName, shouldSetDisplayName, areWorktreePathsEqual } from '../ipc/worktree-logic' import { assertWorktreeDoesNotContainRegisteredWorktree, canCleanupUnregisteredOrcaLeftoverDirectory, canCleanupUnregisteredOrcaWorktreeDirectory, canSafelyRemoveOrphanedWorktreeDirectory, findRegisteredDeletableWorktree, isDangerousWorktreeRemovalPath, isWorktreePathMissing, ORPHANED_WORKTREE_DIRECTORY_MESSAGE, stripOrcaProvenanceMetaUpdates, UNREGISTERED_MISSING_WORKTREE_MESSAGE } from '../worktree-removal-safety' import { prefetchWorktreeCreateBase } from '../worktree-create-base-prefetch' import { invalidateAuthorizedRootsCache } from '../ipc/filesystem-auth' import { prepareLocalWorktreeRootForRepo } from '../worktree-root-preparation' import { closeLocalWatcherForWorktreePath } from '../ipc/filesystem-watcher' import { HeadlessEmulator } from '../daemon/headless-emulator' import { killAllProcessesForWorktree } from './worktree-teardown' import { MOBILE_SUBSCRIBE_SCROLLBACK_ROWS } from './scrollback-limits' import type { IFilesystemProvider, IPtyProvider } from '../providers/types' import { getSshFilesystemProvider } from '../providers/ssh-filesystem-dispatch' import { assertFolderWorkspacePathUsable, getFolderWorkspacePathStatus, getFolderWorkspacePathStatusForPath, inferFolderWorkspacePathConnection } from '../project-groups/folder-workspace-path-status' import { getSshGitProvider, requireSshGitProvider } from '../providers/ssh-git-dispatch' import { detectRepoIconAndUpstream } from '../repo-icon-autodetect' import { enrichMissingRepoGitRemoteIdentities } from '../repo-git-remote-identity-enrichment' import { githubAvatarIcon } from '../../shared/repo-icon' import type { ClaudeAccountService } from '../claude-accounts/service' import type { CodexAccountService } from '../codex-accounts/service' import type { RateLimitService } from '../rate-limits/service' import type { ClaudeRateLimitAccountsState, CodexRateLimitAccountsState } from '../../shared/types' import type { RateLimitState } from '../../shared/rate-limit-types' import type { VoiceSettings } from '../../shared/speech-types' import { getSpeechModelManager, getSpeechSttService } from '../speech/speech-runtime-service' import { getCatalogModel, isLocalSpeechModel, SPEECH_MODEL_CATALOG } from '../speech/model-catalog' import { deleteLocalSpeechModel, getSpeechModelDeletionErrorCode } from '../speech/speech-model-deletion' import type { CommitMessageAgentEnvironmentResolvers } from '../text-generation/commit-message-agent-environment' import { scanNestedRepos } from '../project-groups/nested-repo-discovery' import { createNestedProjectGroupResolver, resolveNestedRepoSelection } from '../project-groups/nested-repo-import' import { createNestedRepoImportTargetResolver } from '../project-groups/nested-repo-import-target' function sanitizeNestedRepoRuntimeImportError(context: string, error: unknown): string { console.warn(`[project-groups] ${context}`, error) return 'Repository could not be imported' } type RuntimeAccountServices = { claudeAccounts: ClaudeAccountService codexAccounts: CodexAccountService rateLimits: RateLimitService } export type RemoteFetchResult = { ok: true } | { ok: false; errorKind: 'git_error' } export type RemoteTrackingBase = { remote: string branch: string ref: string base: string } export type AccountsSnapshot = { claude: ClaudeRateLimitAccountsState codex: CodexRateLimitAccountsState rateLimits: RateLimitState } type RuntimeStore = { getRepos: Store['getRepos'] getRepo: Store['getRepo'] addRepo: Store['addRepo'] updateRepo: Store['updateRepo'] getProjects?: Store['getProjects'] updateProject?: Store['updateProject'] getProjectHostSetups?: Store['getProjectHostSetups'] createProjectHostSetup?: Store['createProjectHostSetup'] updateProjectHostSetup?: Store['updateProjectHostSetup'] deleteProjectHostSetup?: Store['deleteProjectHostSetup'] getProjectGroups?: Store['getProjectGroups'] createProjectGroup?: Store['createProjectGroup'] updateProjectGroup?: Store['updateProjectGroup'] deleteProjectGroup?: Store['deleteProjectGroup'] moveProjectToGroup?: Store['moveProjectToGroup'] getFolderWorkspaces?: Store['getFolderWorkspaces'] createFolderWorkspace?: Store['createFolderWorkspace'] updateFolderWorkspace?: Store['updateFolderWorkspace'] removeFolderWorkspace?: Store['removeFolderWorkspace'] removeProject?: Store['removeProject'] reorderRepos?: Store['reorderRepos'] getAllWorktreeMeta: Store['getAllWorktreeMeta'] getWorktreeMeta: Store['getWorktreeMeta'] setWorktreeMeta: Store['setWorktreeMeta'] removeWorktreeMeta: Store['removeWorktreeMeta'] getWorktreeLineage?: Store['getWorktreeLineage'] getAllWorktreeLineage?: Store['getAllWorktreeLineage'] setWorktreeLineage?: Store['setWorktreeLineage'] removeWorktreeLineage?: Store['removeWorktreeLineage'] getAllWorkspaceLineage?: Store['getAllWorkspaceLineage'] setWorkspaceLineage?: Store['setWorkspaceLineage'] removeWorkspaceLineage?: Store['removeWorkspaceLineage'] getGitHubCache: Store['getGitHubCache'] getWorkspaceSession?: Store['getWorkspaceSession'] setWorkspaceSession?: Store['setWorkspaceSession'] persistPtyBinding?: Store['persistPtyBinding'] getUI?: Store['getUI'] updateUI?: Store['updateUI'] recordFeatureInteraction?: Store['recordFeatureInteraction'] listAutomations?: Store['listAutomations'] listAutomationRuns?: Store['listAutomationRuns'] createAutomation?: Store['createAutomation'] updateAutomation?: Store['updateAutomation'] deleteAutomation?: Store['deleteAutomation'] getSparsePresets?: Store['getSparsePresets'] saveSparsePreset?: Store['saveSparsePreset'] getSettings(): { workspaceDir: string nestWorkspaces: boolean refreshLocalBaseRefOnWorktreeCreate: boolean localBaseRefSuggestionDismissed?: boolean branchPrefix: string branchPrefixCustom: string defaultTuiAgent?: GlobalSettings['defaultTuiAgent'] disabledTuiAgents?: GlobalSettings['disabledTuiAgents'] agentCmdOverrides?: GlobalSettings['agentCmdOverrides'] agentDefaultArgs?: GlobalSettings['agentDefaultArgs'] agentDefaultEnv?: GlobalSettings['agentDefaultEnv'] agentStatusHooksEnabled?: GlobalSettings['agentStatusHooksEnabled'] defaultTaskSource?: GlobalSettings['defaultTaskSource'] defaultTaskViewPreset?: GlobalSettings['defaultTaskViewPreset'] visibleTaskProviders?: GlobalSettings['visibleTaskProviders'] defaultRepoSelection?: GlobalSettings['defaultRepoSelection'] defaultLinearTeamSelection?: GlobalSettings['defaultLinearTeamSelection'] githubProjects?: GlobalSettings['githubProjects'] experimentalNewWorktreeCardStyle?: GlobalSettings['experimentalNewWorktreeCardStyle'] compactWorktreeCards?: GlobalSettings['compactWorktreeCards'] gitlabProjects?: GlobalSettings['gitlabProjects'] experimentalWorktreeSymlinks?: boolean mobileAutoRestoreFitMs?: number | null mobileEmulatorEnabled?: boolean mobileEmulatorDefaultDeviceUdid?: string | null voice?: VoiceSettings claudeAgentTeamsMode?: GlobalSettings['claudeAgentTeamsMode'] } // Why: narrow to `unknown` return so test mocks can return void without // a cast. The runtime never reads the return value — the persisted value // is read back via getSettings() on the next access. updateSettings?: ( updates: Partial, options?: { notifyListeners?: boolean; originWebContentsId?: number } ) => unknown } export type RuntimeAutomationCreateInput = Omit< AutomationCreateInput, 'projectId' | 'workspaceId' | 'workspaceMode' | 'timezone' > & { repo?: string workspace?: string workspaceMode?: AutomationWorkspaceMode timezone?: string } export type RuntimeAutomationUpdateInput = Omit< AutomationUpdateInput, 'projectId' | 'workspaceId' > & { repo?: string workspace?: string } function normalizeSparsePresetName(name: string): string { const trimmed = name.trim() if (!trimmed) { throw new Error('Preset name is required.') } if (trimmed.length > 80) { throw new Error('Preset name is too long.') } return trimmed } function normalizeSparsePresetDirectoriesForSave(directories: string[]): string[] { let normalized: string[] try { normalized = normalizeSparseDirectories(directories) } catch (err) { if ( err instanceof Error && err.message === 'Sparse checkout directories must be repo-relative paths.' ) { throw new Error('Preset directories must be repo-relative paths.') } throw err } if (normalized.length === 0) { throw new Error('Preset must have at least one directory.') } return normalized } function hasRuntimeAutomationUpdateValue( updates: RuntimeAutomationUpdateInput, key: K ): boolean { return Object.hasOwn(updates, key) && updates[key] !== undefined } type RuntimeLeafRecord = RuntimeSyncedLeaf & { ptyGeneration: number connected: boolean writable: boolean lastOutputAt: number | null lastExitCode: number | null tailBuffer: string[] tailPartialLine: string tailPendingAnsi: string tailRedrawCursor: RetainedTailRedrawCursor | null tailTruncated: boolean tailLinesTotal: number preview: string waitBlockedAt: number | null lastAgentStatus: AgentStatus | null // Why: the most recent OSC title observed on this leaf's PTY data. Used by // worktree.ps so daemon-hosted terminals (no renderer pushing pane titles) // still recompute working/idle from the live title each call instead of // serving a stale `lastAgentStatus` after the agent process exits and the // shell takes over the title — the bug behind issue #1437. lastOscTitle: string | null lastOscTitleAt: number | null paneTitleUpdatedAt: number | null } function isCursorAgentOrchestrationTarget( leaf: RuntimeLeafRecord, tabTitle: string | null | undefined ): boolean { return [leaf.lastOscTitle, leaf.paneTitle, tabTitle].some(isCursorAgentTitle) } function isCursorAgentTitle(title: string | null | undefined): boolean { if (typeof title !== 'string') { return false } const trimmed = title.trim() const lower = trimmed.toLowerCase() if ( lower === 'cursor agent' || lower === 'cursor ready' || lower === 'cursor - action required' ) { return true } // Why: display labels can mention Cursor in another agent's task text. Only // treat the controlled synthetic Cursor spinner title as Cursor identity. return /^[\u2800-\u28ff] Cursor Agent$/u.test(trimmed) } type RuntimePtyWorktreeRecord = { ptyId: string worktreeId: string connectionId: string | null // Why: background CLI PTYs can outlive a failed renderer reveal. Preserve the // spawn-time tab/pane identity so later reveals can adopt under the env key. tabId: string | null paneKey: string | null launchConfig: SleepingAgentLaunchConfig | null launchToken: string | null launchAgent: TuiAgent | null foregroundAgent: TuiAgent | null connected: boolean disconnectedAt: number | null lastExitCode: number | null lastAgentStatus: AgentStatus | null lastOscTitle: string | null lastOscTitleAt: number | null managementTitle: string | null managementTitleAt: number | null title: string | null titleUpdatedAt: number | null lastOutputAt: number | null tailBuffer: string[] tailPartialLine: string tailPendingAnsi: string tailRedrawCursor: RetainedTailRedrawCursor | null tailTruncated: boolean tailLinesTotal: number preview: string waitBlockedAt: number | null } function copySleepingAgentLaunchConfig( config: SleepingAgentLaunchConfig ): SleepingAgentLaunchConfig { return { ...(config.agentCommand ? { agentCommand: config.agentCommand } : {}), agentArgs: config.agentArgs, agentEnv: { ...config.agentEnv } } } function inferCapturedClaudeAgentTeamsMode( launchConfig: SleepingAgentLaunchConfig | undefined, command: string | undefined, currentMode: ClaudeAgentTeamsMode | undefined ): ClaudeAgentTeamsMode | undefined { const capturedCommand = launchConfig?.agentCommand?.trim() || command?.trim() || '' const capturedArgs = launchConfig?.agentArgs?.trim() ?? '' const capturedLaunch = `${capturedCommand} ${capturedArgs}`.trim() if (/(^|\s)--teammate-mode(?:=|\s+)auto(?:\s|$)/.test(capturedLaunch)) { return 'native-panes-shim' } if (/(^|\s)--teammate-mode(?:=|\s+)in-process(?:\s|$)/.test(capturedLaunch)) { return 'in-process' } if (launchConfig && /(^|\s)--resume(?:\s|=|$)/.test(command?.trim() ?? '')) { return 'off' } return currentMode } export type RuntimeTerminalAgentStatusEvent = { ptyId: string source: 'mounted-leaf' | 'pty-record' paneKey: string tabId?: string worktreeId?: string connectionId?: string | null payload: ParsedAgentStatusPayload } // Why: the full OSC 9999 payload flows through emitTerminalAgentStatusEvents and // is then forwarded to the renderer and dropped. Mobile is served by the main // process and has no renderer store, so we retain the latest payload per pane // here to feed worktree.ps's inline agent rows (1:1 with the desktop sidebar). type RuntimeAgentRowSnapshot = { paneKey: string ptyId: string worktreeId?: string tabId?: string payload: ParsedAgentStatusPayload // When the current payload.state was first observed for this pane (ms). stateStartedAt: number updatedAt: number } type RuntimeHeadlessTerminal = { emulator: HeadlessEmulator // Why: serialize can race with newer writes appended to writeChain; return // the seq actually painted into this emulator, not the latest PTY seq. outputSequence: number writeChain: Promise } type HeadlessSeedMetadata = { cwd?: string | null oscLinks?: TerminalOscLinkRange[] } type RuntimePtyController = { spawn?(opts: { cols: number rows: number cwd?: string command?: string commandDelivery?: 'renderer' | 'provider' startupCommandDelivery?: WorktreeStartupLaunch['startupCommandDelivery'] env?: Record envToDelete?: string[] telemetry?: WorktreeStartupLaunch['telemetry'] connectionId?: string | null worktreeId?: string preAllocatedHandle?: string tabId?: string leafId?: string sessionId?: string persistHostSessionBinding?: boolean }): Promise<{ id: string }> write(ptyId: string, data: string): boolean kill(ptyId: string): boolean stopAndWait?(ptyId: string, opts?: { keepHistory?: boolean }): Promise getForegroundProcess(ptyId: string): Promise hasChildProcesses?(ptyId: string): Promise clearBuffer?(ptyId: string): Promise resize?(ptyId: string, cols: number, rows: number): boolean listProcesses?(): Promise<{ id: string; cwd: string; title: string }[]> serializeBuffer?( ptyId: string, opts?: { scrollbackRows?: number; altScreenForcesZeroRows?: boolean } ): Promise<{ data: string; cols: number; rows: number; lastTitle?: string } | null> // Why: synchronous probe used by maybeHydrateHeadlessFromRenderer to skip // hydration when no renderer is authoritative for this PTY. See // docs/mobile-prefer-renderer-scrollback.md. hasRendererSerializer?(ptyId: string): boolean getSize?(ptyId: string): { cols: number; rows: number } | null } type WorktreeStartupDraftPaste = { agent: TuiAgent content: string } type WorktreeStartupFollowup = { expectedProcess: string prompt: string } function getAgentLaunchPlatformForRepo( repo: Pick, projectRuntime?: ProjectExecutionRuntimeResolution ): NodeJS.Platform { if (!repo.connectionId) { if (projectRuntime?.status === 'repair-required') { return projectRuntime.repair.preferredRuntime.kind === 'wsl' ? 'linux' : process.platform } if (projectRuntime?.status === 'resolved' && projectRuntime.runtime.kind === 'wsl') { return 'linux' } return process.platform } return isWindowsAbsolutePathLike(repo.path) ? 'win32' : 'linux' } const FOREGROUND_AGENT_WRAPPER_RETRY_INTERVAL_MS = 150 const FOREGROUND_AGENT_WRAPPER_RETRY_TIMEOUT_MS = 6_500 const BRACKETED_PASTE_BEGIN = '\x1b[200~' const BRACKETED_PASTE_END = '\x1b[201~' const BRACKETED_PASTE_QUIET_MS = 1500 const DRAFT_PASTE_READY_TIMEOUT_MS = 8000 const MOBILE_TERMINAL_SURFACE_TIMEOUT_MS = 10_000 const MOBILE_TERMINAL_READY_FALLBACK_MS = 1000 const RECENT_PTY_OUTPUT_LIMIT = 4096 function createTerminalRevealWarning(handle: string, error?: unknown): string { const reason = error instanceof Error && error.message.trim().length > 0 ? ` Reason: ${error.message.trim()}.` : '' return [ `Terminal ${handle} is running, but Orca could not make it discoverable.${reason}`, `Run \`orca terminal focus --terminal ${handle}\` to reveal and focus it.` ].join(' ') } function resolveTerminalPresentation(opts: { presentation?: RuntimeTerminalPresentation focus?: boolean activate?: boolean }): RuntimeTerminalPresentation | undefined { if (opts.presentation) { return opts.presentation } if (opts.focus === true || opts.activate === true) { return 'focused' } return undefined } type RuntimeNotifier = { worktreesChanged(repoId: string, renamed?: { oldWorktreeId: string; newWorktreeId: string }): void worktreeBaseStatus?(event: WorktreeBaseStatusEvent): void worktreeRemoteBranchConflict?(event: WorktreeRemoteBranchConflictEvent): void reposChanged(): void activateWorktree( repoId: string, worktreeId: string, setup?: CreateWorktreeResult['setup'], startup?: WorktreeStartupLaunch, defaultTabs?: CreateWorktreeResult['defaultTabs'] ): void createTerminal( worktreeId: string, opts: { command?: string env?: Record title?: string presentation?: RuntimeTerminalPresentation } ): void revealTerminalSession?( worktreeId: string, opts: { ptyId: string title?: string | null launchConfig?: SleepingAgentLaunchConfig launchToken?: string launchAgent?: TuiAgent activate?: boolean presentation?: RuntimeTerminalPresentation tabId?: string leafId?: string splitFromLeafId?: string splitDirection?: 'horizontal' | 'vertical' splitTelemetrySource?: TerminalPaneSplitSource } ): | Promise<{ tabId: string; title?: string | null }> | { tabId: string; title?: string | null } | void splitTerminal( tabId: string, paneRuntimeId: number, opts: { direction: 'horizontal' | 'vertical' command?: string telemetrySource?: TerminalPaneSplitSource } ): void renameTerminal(tabId: string, title: string | null): void focusTerminal(tabId: string, worktreeId: string, leafId?: string | null): void focusEditorTab?(tabId: string, worktreeId: string): void closeSessionTab?(tabId: string, worktreeId: string): void moveSessionTab?(worktreeId: string, move: RuntimeMobileSessionTabMove): void openFile?( worktreeId: string, filePath: string, relativePath: string, runtimeEnvironmentId?: string | null ): void openDiff?( worktreeId: string, filePath: string, relativePath: string, staged: boolean, runtimeEnvironmentId?: string | null ): void readMobileMarkdownTab?(worktreeId: string, tabId: string): Promise saveMobileMarkdownTab?( worktreeId: string, tabId: string, baseVersion: string, content: string ): Promise closeTerminal(tabId: string, paneRuntimeId?: number): void sleepWorktree(worktreeId: string): void terminalFitOverrideChanged( ptyId: string, mode: 'mobile-fit' | 'desktop-fit', cols: number, rows: number ): void // Why: presence-based lock signal — desktop renderer mounts the lock // banner when `driver.kind === 'mobile'` and unmounts otherwise. The // structured payload (vs a `locked: boolean`) carries the active mobile // actor's clientId so the renderer can disambiguate multi-phone scenarios // and so a future write coordinator can use the same signal as scheduling // input. See docs/mobile-presence-lock.md. terminalDriverChanged(ptyId: string, driver: DriverState): void browserDriverChanged?(browserPageId: string, driver: RuntimeBrowserDriverState): void } type TerminalHandleRecord = { handle: string runtimeId: string rendererGraphEpoch: number worktreeId: string tabId: string leafId: string ptyId: string | null ptyGeneration: number } type TerminalWaiter = { handle: string condition: RuntimeTerminalWaitCondition resolve: (result: RuntimeTerminalWait) => void reject: (error: Error) => void timeout: NodeJS.Timeout | null pollInterval: NodeJS.Timeout | null abortCleanup: (() => void) | null } type MessageWaiter = { handle: string typeFilter: string[] | undefined resolve: (result: void) => void timeout: NodeJS.Timeout | null abortCleanup: (() => void) | null } function omitUndefinedProperties>(value: T): Partial { return Object.fromEntries( Object.entries(value).filter(([, entry]) => entry !== undefined) ) as Partial } async function isRuntimeWorktreePathMissing( repo: Repo, worktreePath: string, localWorktreeGitOptions: { wslDistro?: string } = {} ): Promise { if (!repo.connectionId) { const access = getLocalWorktreePathAccess(localWorktreeGitOptions) return isWorktreePathMissing( toLocalWorktreeRuntimePath(worktreePath, localWorktreeGitOptions), access.statPath ) } const fsProvider = getSshFilesystemProvider(repo.connectionId) if (!fsProvider) { return false } return isWorktreePathMissing(worktreePath, (path) => fsProvider.stat(path)) } async function isLocalRuntimeGitRepository( runtimeWorktreePath: string, localWorktreeGitOptions: { wslDistro?: string } = {} ): Promise { try { await gitExecFileAsync(['status', '--short'], { cwd: runtimeWorktreePath, ...localWorktreeGitOptions }) return true } catch (error) { return !gitStatusErrorMeansNotRepository(error) } } function gitStatusErrorMeansNotRepository(error: unknown): boolean { const message = error instanceof Error ? error.message : error && typeof error === 'object' && 'message' in error ? String((error as { message: unknown }).message) : typeof error === 'string' ? error : '' const stderr = error && typeof error === 'object' && 'stderr' in error ? String((error as { stderr: unknown }).stderr) : '' return /not a git repository/i.test(`${message}\n${stderr}`) } type RuntimeWorktreeRemovalTarget = { id: string repoId: string path: string pushTarget?: GitPushTarget } type RuntimeWorktreeRemovalInFlight = { optionsKey: string promise: Promise } type PreservedBranchCleanupTarget = { branchName: string head: string pushTarget?: GitPushTarget } function getRuntimeWorktreeRemovalOptionsKey(force: boolean, runHooks: boolean): string { return `${force ? 'force' : 'normal'}:${runHooks ? 'run-hooks' : 'skip-hooks'}` } function getRuntimeFolderWorkspaceRootId(repo: Repo): string { return `${repo.id}::${repo.path}` } function getRuntimeFolderWorkspaceInstanceId(repo: Repo, instanceId: string): string { return `${getRuntimeFolderWorkspaceRootId(repo)}${FOLDER_WORKSPACE_INSTANCE_SEPARATOR}${instanceId}` } function getRuntimeFolderWorkspaceInstanceIdentity(repo: Repo, worktreeId: string): string { const prefix = `${getRuntimeFolderWorkspaceRootId(repo)}${FOLDER_WORKSPACE_INSTANCE_SEPARATOR}` return worktreeId.startsWith(prefix) ? worktreeId.slice(prefix.length) : randomUUID() } function isRuntimeFolderWorkspaceIdForRepo(repo: Repo, worktreeId: string): boolean { const rootId = getRuntimeFolderWorkspaceRootId(repo) return ( worktreeId === rootId || worktreeId.startsWith(`${rootId}${FOLDER_WORKSPACE_INSTANCE_SEPARATOR}`) ) } function mergeRuntimeFolderWorkspace(repo: Repo, worktreeId: string, meta: WorktreeMeta): Worktree { return { id: worktreeId, ...(meta.instanceId !== undefined ? { instanceId: meta.instanceId } : {}), repoId: repo.id, ...(meta.projectId !== undefined ? { projectId: meta.projectId } : {}), ...(meta.hostId !== undefined ? { hostId: meta.hostId } : {}), ...(meta.projectHostSetupId !== undefined ? { projectHostSetupId: meta.projectHostSetupId } : {}), path: repo.path, head: '', branch: '', isBare: false, isMainWorktree: worktreeId === getRuntimeFolderWorkspaceRootId(repo), displayName: meta.displayName || repo.displayName, comment: meta.comment || '', linkedIssue: meta.linkedIssue ?? null, linkedPR: meta.linkedPR ?? null, linkedLinearIssue: meta.linkedLinearIssue ?? null, linkedLinearIssueWorkspaceId: meta.linkedLinearIssueWorkspaceId ?? null, linkedLinearIssueOrganizationUrlKey: meta.linkedLinearIssueOrganizationUrlKey ?? null, linkedGitLabMR: meta.linkedGitLabMR ?? null, linkedGitLabIssue: meta.linkedGitLabIssue ?? null, linkedBitbucketPR: meta.linkedBitbucketPR ?? null, linkedAzureDevOpsPR: meta.linkedAzureDevOpsPR ?? null, linkedGiteaPR: meta.linkedGiteaPR ?? null, isArchived: meta.isArchived ?? false, isUnread: meta.isUnread ?? false, isPinned: meta.isPinned ?? false, sortOrder: meta.sortOrder ?? 0, ...(meta.manualOrder !== undefined ? { manualOrder: meta.manualOrder } : {}), lastActivityAt: meta.lastActivityAt ?? 0, ...(meta.createdAt !== undefined ? { createdAt: meta.createdAt } : {}), ...(meta.createdWithAgent !== undefined ? { createdWithAgent: meta.createdWithAgent } : {}), ...(meta.automationProvenance !== undefined ? { automationProvenance: meta.automationProvenance } : {}), ...(meta.priorWorktreeIds !== undefined ? { priorWorktreeIds: meta.priorWorktreeIds } : {}), workspaceStatus: meta.workspaceStatus ?? DEFAULT_WORKSPACE_STATUS_ID, diffComments: meta.diffComments, mobileDiffReview: meta.mobileDiffReview } } function listRuntimeFolderWorkspaces( store: Pick, repo: Repo ): Worktree[] { const rootId = getRuntimeFolderWorkspaceRootId(repo) const allMeta = store.getAllWorktreeMeta() const ids = Object.keys(allMeta).filter((worktreeId) => isRuntimeFolderWorkspaceIdForRepo(repo, worktreeId) ) if (!ids.includes(rootId)) { ids.unshift(rootId) } else { ids.sort((left, right) => { if (left === rootId) { return -1 } if (right === rootId) { return 1 } return 0 }) } return ids.map((worktreeId) => { const existing = allMeta[worktreeId] const meta = existing?.instanceId ? existing : store.setWorktreeMeta(worktreeId, { instanceId: getRuntimeFolderWorkspaceInstanceIdentity(repo, worktreeId), ...(existing ? {} : { displayName: repo.displayName, lastActivityAt: Date.now() }) }) return mergeRuntimeFolderWorkspace(repo, worktreeId, meta) }) } function parseExactWorktreeIdSelector(selector: string): RuntimeWorktreeRemovalTarget | null { const worktreeId = selector.startsWith('id:') ? selector.slice(3) : selector const parsed = splitWorktreeId(worktreeId) if (!parsed || !parsed.repoId || !parsed.worktreePath) { return null } return { id: worktreeId, repoId: parsed.repoId, path: parsed.worktreePath } } async function resolveCreateBranchName( repoPath: string, branchNameOverride: string | undefined, sanitizedName: string, settings: { branchPrefix: string; branchPrefixCustom?: string }, username: string | null, gitOptions: { wslDistro?: string } = {} ): Promise { if (!branchNameOverride) { return computeBranchName(sanitizedName, settings, username) } if (branchNameOverride.startsWith('-')) { throw new Error('Branch name must not start with "-"') } await gitExecFileAsync(['check-ref-format', '--branch', branchNameOverride], { cwd: repoPath, ...gitOptions }) return branchNameOverride } function normalizeLocalBranchName(branchName: string | undefined): string { return branchName?.replace(/^refs\/heads\//, '') ?? '' } // Clamp terminal dimensions to the PTY's supported range (cols 20–240, rows 8–120). function clampTerminalViewport(cols: number, rows: number): { cols: number; rows: number } { return { cols: Math.max(20, Math.min(240, Math.round(cols))), rows: Math.max(8, Math.min(120, Math.round(rows))) } } // Subscribe a listener to a per-key Set, pruning the key's entry once its last // listener unsubscribes. Returns the unsubscribe callback. function addListenerToMap(map: Map>, key: string, listener: T): () => void { let listeners = map.get(key) if (!listeners) { listeners = new Set() map.set(key, listeners) } const set = listeners set.add(listener) return () => { set.delete(listener) if (set.size === 0) { map.delete(key) } } } async function canCheckoutExistingLocalBranch( repoPath: string, branchName: string, baseBranch: string, gitOptions: { wslDistro?: string } = {} ): Promise { let localHead = '' try { const { stdout } = await gitExecFileAsync( ['rev-parse', '--verify', '--quiet', `refs/heads/${branchName}^{commit}`], { cwd: repoPath, ...gitOptions } ) localHead = stdout.trim() } catch { return false } if (normalizeLocalBranchName(baseBranch) !== branchName) { if (!localHead) { return false } try { const { stdout } = await gitExecFileAsync( ['rev-parse', '--verify', '--quiet', `${baseBranch}^{commit}`], { cwd: repoPath, ...gitOptions } ) if (stdout.trim() !== localHead) { return false } } catch { return false } } const worktrees = await listWorktrees(repoPath, gitOptions) return !worktrees.some((worktree) => normalizeLocalBranchName(worktree.branch) === branchName) } function hasLocalGitOptions(gitOptions: { wslDistro?: string }): boolean { return Object.keys(gitOptions).length > 0 } function getLocalGitHubPrForBranch( repoPath: string, branchName: string, gitOptions: { wslDistro?: string } ): ReturnType { return hasLocalGitOptions(gitOptions) ? getPRForBranch(repoPath, branchName, null, null, null, { localGitExecOptions: gitOptions }) : getPRForBranch(repoPath, branchName) } type SelectedReviewBranchInput = { branchNameOverride?: string linkedPR?: number | null linkedGitLabMR?: number | null linkedBitbucketPR?: number | null linkedAzureDevOpsPR?: number | null linkedGiteaPR?: number | null pushTarget?: GitPushTarget } type SelectedReviewBranch = { provider: ForgeProviderId number: number } function getSelectedReviewBranch(args: SelectedReviewBranchInput): SelectedReviewBranch | null { if (typeof args.linkedPR === 'number') { return { provider: 'github', number: args.linkedPR } } if (typeof args.linkedGitLabMR === 'number') { return { provider: 'gitlab', number: args.linkedGitLabMR } } if (typeof args.linkedBitbucketPR === 'number') { return { provider: 'bitbucket', number: args.linkedBitbucketPR } } if (typeof args.linkedAzureDevOpsPR === 'number') { return { provider: 'azure-devops', number: args.linkedAzureDevOpsPR } } if (typeof args.linkedGiteaPR === 'number') { return { provider: 'gitea', number: args.linkedGiteaPR } } return null } function isSelectedGitHubPrBranchOverride( args: SelectedReviewBranchInput, branchName: string ): boolean { return typeof args.linkedPR === 'number' && args.branchNameOverride === branchName } function isSelectedReviewBranchOverride( args: SelectedReviewBranchInput, branchName: string ): boolean { return getSelectedReviewBranch(args) !== null && args.branchNameOverride === branchName } function isMatchingSelectedGitHubPr( existingPR: Awaited>, args: SelectedReviewBranchInput, branchName: string ): boolean { return Boolean( existingPR && isSelectedGitHubPrBranchOverride(args, branchName) && existingPR.number === args.linkedPR ) } function isAllowedPushTargetRemoteConflict( conflictKind: 'local' | 'remote' | null, branchName: string, args: SelectedReviewBranchInput ): boolean { return ( conflictKind === 'remote' && isSelectedReviewBranchOverride(args, branchName) && args.pushTarget?.branchName === branchName ) } function getSelectedReviewLookupHints(args: SelectedReviewBranchInput): { linkedGitHubPR?: number | null linkedGitLabMR?: number | null linkedBitbucketPR?: number | null linkedAzureDevOpsPR?: number | null linkedGiteaPR?: number | null } { return { linkedGitHubPR: args.linkedPR ?? null, linkedGitLabMR: args.linkedGitLabMR ?? null, linkedBitbucketPR: args.linkedBitbucketPR ?? null, linkedAzureDevOpsPR: args.linkedAzureDevOpsPR ?? null, linkedGiteaPR: args.linkedGiteaPR ?? null } } async function getSelectedHostedReviewForBranch( repo: Pick, branchName: string, args: SelectedReviewBranchInput, executionOptions: { localGitExecOptions?: { wslDistro?: string } } = {} ): Promise<{ matchesSelected: boolean; number: number } | null> { const selectedReview = getSelectedReviewBranch(args) if (!selectedReview) { return null } const review = await getHostedReviewForBranchFromRepo({ repoPath: repo.path, connectionId: repo.connectionId ?? null, branch: branchName, ...executionOptions, ...getSelectedReviewLookupHints(args) }) if (!review) { return null } return { matchesSelected: review.provider === selectedReview.provider && review.number === selectedReview.number, number: review.number } } async function pathExists(pathValue: string): Promise { try { await stat(pathValue) return true } catch (error) { if (isENOENT(error)) { return false } throw error } } function resolveServerBrowsePath(pathValue: string): string { const trimmed = pathValue.trim() || '~' if (trimmed.includes('\0')) { throw new Error('Path cannot contain null bytes') } if (trimmed === '~') { return homedir() } if (/^~[\\/]/.test(trimmed)) { return resolve(homedir(), trimmed.slice(2)) } if (isAbsolute(trimmed)) { return resolve(trimmed) } // Why: remote clients do not share the server process cwd; relative browse // inputs are anchored to the server user's home to match the `~` picker root. return resolve(homedir(), trimmed) } type ResolvedWorktree = Worktree & { parentWorktreeId: string | null childWorktreeIds: string[] lineage: WorktreeLineage | null git: GitWorktreeInfo } type LinearAgentWriteTarget = { issue: LinearIssueSummary workspaceId: string } type LinearCreateFieldIntent = { stateId?: string assigneeId?: string | null priority?: number estimate?: number | null dueDate?: string | null labelIds?: string[] projectId?: string } const AGENT_HOOK_RUNTIME_ENV_KEYS = [ 'ORCA_AGENT_HOOK_PORT', 'ORCA_AGENT_HOOK_TOKEN', 'ORCA_AGENT_HOOK_ENV', 'ORCA_AGENT_HOOK_VERSION', 'ORCA_AGENT_HOOK_ENDPOINT' ] as const function sameStringSet(left: string[], right: string[]): boolean { if (left.length !== right.length) { return false } const rightSet = new Set(right) return left.every((value) => rightSet.has(value)) } function labelsForIds( ids: string[], labels: { id?: string | null; name?: string | null; color?: string | null }[] ): { id: string; name: string; color?: string | null }[] { return ids.map((id) => { const label = labels.find((candidate) => candidate.id === id) return { id, name: label?.name ?? id, ...(label?.color ? { color: label.color } : {}) } }) } type TerminalWorkspaceLaunchScope = { id: string path: string connectionId: string | null repo: Repo | null folderWorkspace: FolderWorkspace | null } type WorktreeLineageInput = { parentWorkspace?: string envParentWorkspace?: string parentWorktree?: string cwdParentWorktree?: string noParent?: boolean callerTerminalHandle?: string comment?: string orchestrationContext?: { parentWorktreeId?: string orchestrationRunId?: string taskId?: string coordinatorHandle?: string } } type ResolvedWorkspaceParent = | { type: 'worktree' workspaceKey: WorkspaceKey worktree: ResolvedWorktree instanceId: string | null } | { type: 'folder' workspaceKey: WorkspaceKey folderWorkspace: FolderWorkspace instanceId: string | null } type WorktreeLineageResolution = | { kind: 'lineage' parent: ResolvedWorkspaceParent origin: WorktreeLineage['origin'] capture: WorktreeLineage['capture'] orchestrationRunId?: string taskId?: string coordinatorHandle?: string createdByTerminalHandle?: string } | { kind: 'none' warnings: WorktreeLineageWarning[] } type RuntimeWorktreeScanResult = | { ok: true; worktrees: GitWorktreeInfo[] } | { ok: false; worktrees: GitWorktreeInfo[] } type WorktreeLineageCandidate = { source: 'env-workspace' | 'cwd-context' | 'terminal-context' | 'orchestration-context' parent: ResolvedWorkspaceParent orchestrationRunId?: string taskId?: string coordinatorHandle?: string } function extractOrchestrationTaskId(text?: string): string | undefined { return text?.match(/\btask_[A-Za-z0-9]+\b/)?.[0] } class RuntimeLineageError extends Error { code: string data?: unknown constructor(code: string, message: string, data?: unknown) { super(message) this.code = code this.data = data } } type ResolvedWorktreeCache = { expiresAt: number worktrees: ResolvedWorktree[] } type ResolvedWorktreeInFlight = { generation: number promise: Promise } export type MobileNotificationDispatchEvent = { type: 'notification' source: 'agent-task-complete' | 'terminal-bell' | 'test' title: string body: string worktreeId?: string notificationId?: string } export type MobileNotificationDismissEvent = { type: 'dismiss' notificationId: string } export type MobileNotificationEvent = | MobileNotificationDispatchEvent | MobileNotificationDismissEvent // Why: presence-based driver state for the mobile-presence lock. Exactly one // driver per PTY at any moment. See docs/mobile-presence-lock.md. // - `idle`: no mobile subscribers; desktop input flows freely // - `desktop`: at least one mobile client subscribed but desktop reclaimed // (or all mobile clients are passive `desktop`-mode watchers); desktop // input flows freely // - `mobile{clientId}`: a mobile client is the active driver; desktop // input/resize are dropped server-side and the lock banner is mounted. // `clientId` is the most recent mobile actor for this PTY. export type DriverState = RuntimeTerminalDriverState // Why: per-PTY layout target — what the PTY *should* be at right now. // `desktop` ⇒ runs at the desktop renderer's pane geometry; mobile passive // watchers (mode='desktop') still receive scrollback. `phone` ⇒ runs at // `ownerClientId`'s viewport; the desktop renderer's auto-fit is suppressed. // See docs/mobile-terminal-layout-state-machine.md. export type PtyLayoutTarget = | { kind: 'desktop'; cols: number; rows: number } | { kind: 'phone'; cols: number; rows: number; ownerClientId: string } // Why: authoritative layout state with monotonic seq. Bumped on every // applyLayout success; emitted on mobile subscribe-stream events so clients // drop stale events that arrive after a newer transition. export type PtyLayoutState = PtyLayoutTarget & { seq: number appliedAt: number } // Why: applyLayout result discriminator. Callers (especially RPC handlers) // need to distinguish "shipped a new state at seq N" from "no-op — caller // should not claim a seq it didn't produce." `pty-exited` is terminal; // `resize-failed` is transient and the caller may retry. export type ApplyLayoutResult = | { ok: true; state: PtyLayoutState } | { ok: false; reason: 'pty-exited' | 'resize-failed' } type LayoutQueueEntry = { running: Promise | null pending: { target: PtyLayoutTarget waiters: ((r: ApplyLayoutResult) => void)[] }[] } export class OrcaRuntimeService { private readonly runtimeId = randomUUID() private readonly startedAt = Date.now() private readonly store: RuntimeStore | null private rendererGraphEpoch = 0 private graphStatus: RuntimeGraphStatus = 'unavailable' private authoritativeWindowId: number | null = null private tabs = new Map() private mobileSessionTabsByWorktree = new Map() // Why: idempotency map for mobile terminal creation — a retried create with the // same clientMutationId returns the in-flight operation instead of duplicating. private mobileTerminalCreateByMutationId = new Map< string, Promise >() private mobileSessionTabListeners = new Set<(snapshot: RuntimeMobileSessionTabsResult) => void>() private leaves = new Map() // Why: PTY output is a per-keystroke hot path. Looking up affected leaves by // ptyId keeps active TUI redraws independent of the total open terminal count. private leavesByPtyId = new Map() private handles = new Map() private handleByLeafKey = new Map() private handleByPtyId = new Map() private detachedPreAllocatedLeaves = new Map() private graphSyncCallbacks: (() => void)[] = [] private waitersByHandle = new Map>() private ptyController: RuntimePtyController | null = null private notifier: RuntimeNotifier | null = null private clientEventListeners = new Set<(event: RuntimeClientEvent) => void>() private forkBackfillStarted = false private agentBrowserBridge: AgentBrowserBridge | null = null private offscreenBrowserBackend: BrowserBackend | null = null private emulatorBridge: EmulatorBridge | null = null private resolvedWorktreeCache: ResolvedWorktreeCache | null = null private resolvedWorktreeInFlight: ResolvedWorktreeInFlight | null = null private resolvedWorktreeGeneration = 0 private cloneInFlightByPath = new Map>() private agentDetector: AgentDetector | null = null private ptyForegroundAgentRefreshes = new Map>() private _orchestrationDb: OrchestrationDb | null = null private messageWaitersByHandle = new Map>() // Why: mobile clients subscribe to terminal output via terminal.subscribe. // These listeners fire on every onPtyData call, enabling real-time streaming // without polling. Keyed by ptyId for O(1) lookup per data event. private dataListeners = new Map< string, Set<(data: string, meta?: { seq?: number; rawLength?: number }) => void> >() // Why: startup draft paste can subscribe after the agent already emitted its // ready marker. Keep a bounded raw buffer so fast startup output is replayed. private recentPtyOutputById = new Map() // Why: mobile clients need to know when the desktop restores a terminal // from mobile-fit so they can update their UI. These listeners are // invoked from resizeForClient and onClientDisconnected/onPtyExit. private fitOverrideListeners = new Map< string, Set<(event: { mode: 'mobile-fit' | 'desktop-fit'; cols: number; rows: number }) => void> >() private driverListeners = new Map void>>() private subscriptionCleanups = new Map void>() // Why: index of subscriptionIds by per-WebSocket connectionId so the // server can sweep all subscriptions for a closing socket without // touching subscriptions on other live sockets that share the same // deviceToken (multi-screen mobile). private subscriptionsByConnection = new Map>() private subscriptionConnectionByEntry = new Map() private activeBrowserScreencastsByConnection = new Map< string, { cancel: (emitEnd?: boolean) => void; done: Promise; connectionKey: string } >() private activeBrowserScreencastsByPage = new Map< string, { cancel: (emitEnd?: boolean) => void; done: Promise; connectionKey: string } >() // Why: mobile clients subscribe to desktop notifications via // notifications.subscribe. This set enables fan-out — each connected // mobile client gets its own listener, and dispatchMobileNotification // iterates them all. Listeners are cleaned up via subscriptionCleanups. private notificationListeners = new Set<(event: MobileNotificationEvent) => void>() private ptysById = new Map() private titleObservationSequence = 0 private headlessTerminals = new Map() private ptyOutputSequenceById = new Map() // Why: OSC 9999 status can span PTY chunks. Keeping parser state in the // runtime lets hidden/model-owned terminals observe agent state without a // mounted xterm view. private agentStatusOscProcessorsByPtyId = new Map< string, ReturnType >() // Why: ordinary OSC 0/1/2 titles can split across PTY chunks, especially over // SSH/relay buffering. Keep a small raw scan tail so status titles are not lost. private oscTitleScanTailByPtyId = new Map() // Why: latest agent-status payload per pane, retained so worktree.ps can serve // mobile the same inline agent rows the desktop sidebar renders. Cleared on pty // teardown so dead agents don't linger. See RuntimeAgentRowSnapshot. private latestAgentStatusByPaneKey = new Map() // Why: per-PTY hydration state guards against double-hydration. Keys: // 'pending' → maybeHydrateHeadlessFromRenderer is in flight // 'done' → hydration completed (success or skip); never run again // Absent → hydration has not been considered yet for this PTY. // See docs/mobile-prefer-renderer-scrollback.md. private headlessHydrationState = new Map() // Why: mobile-fit overrides are keyed by ptyId (not terminal handle) because // handles can be reissued while the PTY identity is stable. In-memory only — // a stale phone override should not survive an app restart. private terminalFitOverrides = new Map< string, { mode: 'mobile-fit' cols: number rows: number previousCols: number | null previousRows: number | null updatedAt: number clientId: string } >() // Why: server-authoritative display mode per terminal. 'auto' (default) // means phone-fit when mobile subscribes, desktop otherwise. 'desktop' // locks to no-resize regardless of subscriber state. The third historical // value ('phone' = sticky phone-fit after unsubscribe) was removed since // the toggle UI never produced it and nothing in product depended on it. // In-memory only — modes reset on restart. private mobileDisplayModes = new Map() // Why: tracks active mobile subscribers per PTY so the runtime can restore // desktop dimensions on unsubscribe and prevent orphaned overrides during // rapid tab switches. Keyed by ptyId → inner map of clientId → subscriber. // The two-level map preserves multi-mobile soundness: phone B subscribing // does not silently overwrite phone A's record. See // docs/mobile-presence-lock.md "Multi-mobile subscriber model". // subscribedAt drives "earliest-by-subscribe-time" restore-target selection // (only among subscribers with non-null previousCols/Rows; desktop-mode // joins carry null and are skipped). lastActedAt drives "most-recent // actor's viewport wins" for active phone-fit dims. private mobileSubscribers = new Map< string, Map< string, { clientId: string viewport: { cols: number; rows: number } | null wasResizedToPhone: boolean previousCols: number | null previousRows: number | null subscribedAt: number lastActedAt: number } > >() // Why: per-PTY driver state. The "driver" is whoever currently owns the // input/resize floor. While `kind === 'mobile'` the desktop renderer drops // xterm.onData/onResize and shows the lock banner; `terminal.send` / // `pty:write` and `pty:resize` IPC handlers also drop desktop-side calls // server-side as defense-in-depth. The `clientId` carried on the mobile // variant is the most recent mobile actor — used by // `applyMobileDisplayMode` to pick the active phone-fit viewport. See // docs/mobile-presence-lock.md. private currentDriver = new Map() private currentBrowserDriver = new Map() // Why: resubscribe-grace window. When the last mobile subscriber for a // PTY unsubscribes, we hold the driver=mobile{clientId} state and the // inner-map record open for ~250ms. If the same (ptyId, clientId) // re-subscribes inside the window — typically because the mobile app // tore down the stream to reconfigure (rare with the new // updateMobileViewport path, but still possible on reconnects, network // hiccups, or older client builds) — we cancel the deferred idle and // restore-timer so the desktop banner doesn't flash and the new // subscriber doesn't capture an already-phone-fitted PTY size as its // restore baseline. Keyed by ptyId; carries the timer plus the snapshot // of the leaving subscriber so we can re-insert it on cancel. See // docs/mobile-presence-lock.md. private pendingSoftLeavers = new Map< string, { clientId: string timer: ReturnType record: { clientId: string viewport: { cols: number; rows: number } | null wasResizedToPhone: boolean previousCols: number | null previousRows: number | null subscribedAt: number lastActedAt: number } } >() // Why: tracks the last PTY size set by the desktop renderer (via pty:resize // IPC). Unlike ptySizes (which is overwritten by server-side phone-fit // resizes), this map preserves the actual pane geometry. Used as the // preferred source for previousCols so desktop restore uses the correct // split-pane width instead of a stale full-width value. private lastRendererSizes = new Map() // Why: when a desktop-fit override change fires, the desktop renderer's // re-render cascade (triggered by setOverrideTick) runs safeFit on ALL // panes — not just the affected one. Background tab panes get measured at // full-width (214) instead of their correct split width (105). The stale // pty:resize IPCs overwrite both the actual PTY size and lastRendererSizes. // This global window suppresses ALL pty:resize for 200ms after any // desktop-fit notification. The server has already set the correct PTY // size via ptyController.resize(), so desktop renderer resizes during // this window are redundant (for the restored pane) or wrong (collateral). private resizeSuppressedUntil = 0 // Why: delays PTY restore by 300ms after mobile unsubscribe so rapid tab // switches don't cause unnecessary resize thrashing. Keyed by clientId // Why: keyed by ptyId so each PTY gets its own independent restore timer. // The old clientId-keyed design lost timers when two PTYs were unsubscribed // back-to-back (only the last timer survived). private pendingRestoreTimers = new Map< string, { timer: ReturnType; clientId: string } >() // Why: inline resize events replace the unsubscribe→resubscribe pattern. // Listeners are notified when mode changes or desktop restores, allowing // the subscribe stream to emit a 'resized' event with fresh scrollback. // `seq` is the layout state-machine sequence number bumped on every // applyLayout success; mobile clients use it to drop stale events that // arrive after a newer transition. See docs/mobile-terminal-layout-state-machine.md. private resizeListeners = new Map< string, Set< (event: { cols: number rows: number displayMode: string reason: string seq?: number }) => void > >() // Why: per-PTY layout state machine. `applyLayout` is the sole writer of // `layouts`, `terminalFitOverrides`, and `ptyController.resize`; every // trigger method routes through `enqueueLayout`. The monotonic `seq` is // emitted on the mobile subscribe stream so clients can drop stale events. // See docs/mobile-terminal-layout-state-machine.md. private layouts = new Map() // Why: per-PTY async serialization queue for applyLayout. Without // serialization, two concurrent triggers can interleave around the // ptyController.resize await and bump seq in the wrong order, defeating // seq-as-truth. Coalesces same-kind same-owner viewport ticks so the // keyboard-show/hide animation doesn't queue 10+ resizes; mode flips, // take-floor, and different-owner targets always append (preserves // multi-mobile fairness). See docs/mobile-terminal-layout-state-machine.md // "enqueueLayout coalescing". private layoutQueues = new Map() // Why: gate so enqueueLayout's "no layouts entry" short-circuit doesn't // fire on the very first transition for a PTY (where the entry doesn't // exist yet *because* we're about to create it). `handleMobileSubscribe` // adds the ptyId before calling enqueueLayout and removes it after the // call resolves. private freshSubscribeGuard = new Set() private stats: StatsCollector | null = null // Why (§3.3 + §7.1): the renderer-create path and coordinator // `probeWorktreeDrift` share this cache so a create that already fetched // `origin` within the last 30s does not re-fetch during dispatch, and // vice-versa. Keyed by `::` so multi-remote repos (even // though v1 only uses `origin`) don't cross-contaminate. The in-flight Map // also provides serialization — two concurrent callers share a single // underlying `git fetch`. Full-remote fetch lifecycle rules: // - entry inserted BEFORE await, // - `.finally()` removes the entry on BOTH success and rejection, // - timestamp written ONLY on success (rejection must not make the // 30s freshness cache lie). // A literal "insert before await / read-back after await" without these // three rules wedges future fetches on the same repo after a single // DNS hiccup until process restart (see §3.3 Lifecycle). Exact base-ref // refreshes share the in-flight rule and maintain their own exact-base // freshness entries; a full-remote fetch may be narrowed by repo refspecs, // so it must not prove a specific branch for create. private fetchInflight = new Map>() // Why: `git fetch origin` and `git fetch origin ` contend for the // same repo remote/ref locks. This queue serializes all fetch shapes for one // canonical repo+remote while still letting same-shape callers share promises. private remoteFetchQueueTail = new Map>() private fetchLastCompletedAt = new Map() // Why: `getCanonicalFetchKey` is awaited from every freshness probe and // every getOrStartRemoteFetch call. Without memoization the warm-cache hot // path spawns a `git rev-parse --git-common-dir` subprocess per touch // (twice in createLocalWorktree). Cache by `::` so the // canonical key is resolved at most once per repo+remote in the process. private canonicalFetchKeyCache = new Map() private optimisticReconcileTokens = new Map() private removeManagedWorktreeInFlight = new Map() private preservedBranchCleanupByWorktreeId = new Map() private readonly getLocalProviderFn: (() => IPtyProvider) | null private readonly onPtyStopped: ((ptyId: string) => void) | null private readonly onTerminalAgentStatus: ((event: RuntimeTerminalAgentStatusEvent) => void) | null private readonly getAgentStatusSnapshotFn: (() => AgentStatusIpcPayload[]) | null private readonly buildAgentHookPtyEnv: (() => Record) | null private accountServices: RuntimeAccountServices | null = null private commitMessageAgentEnv: CommitMessageAgentEnvironmentResolvers | null = null private automationService: AutomationService | null = null private readonly claudeAgentTeams = new ClaudeAgentTeamsService() private mobileDictation: { id: string owner: string clientId?: string connectionId?: string state: 'starting' | 'active' | 'closing' partialText: string finalTexts: string[] errors: string[] } | null = null constructor( store: RuntimeStore | null = null, stats?: StatsCollector, deps?: { getLocalProvider?: () => IPtyProvider onPtyStopped?: (ptyId: string) => void onTerminalAgentStatus?: (event: RuntimeTerminalAgentStatusEvent) => void // Why: agent status mostly arrives via hooks (agent-hooks/server), not OSC // terminal output. worktree.ps reads this at query time so mobile shows the // same inline agent rows the desktop sidebar does — same source, 1:1. getAgentStatusSnapshot?: () => AgentStatusIpcPayload[] buildAgentHookPtyEnv?: () => Record } ) { this.store = store if (stats) { this.stats = stats this.agentDetector = new AgentDetector(stats) } this.getAgentStatusSnapshotFn = deps?.getAgentStatusSnapshot ?? null // Why: the daemon adapter is installed via `setLocalPtyProvider()` during // attachMainWindowServices, AFTER this service is constructed. Capturing // `getLocalPtyProvider()` at construction time would freeze a reference to // the pre-daemon `LocalPtyProvider` and miss the routed adapter. Resolve // lazily via thunk so teardown always sees the currently-installed // provider (design §4.3 wire-up). this.getLocalProviderFn = deps?.getLocalProvider ?? null this.onPtyStopped = deps?.onPtyStopped ?? null this.onTerminalAgentStatus = deps?.onTerminalAgentStatus ?? null this.buildAgentHookPtyEnv = deps?.buildAgentHookPtyEnv ?? null } getLocalProvider(): IPtyProvider | null { return this.getLocalProviderFn ? this.getLocalProviderFn() : null } getStatsSummary(): StatsSummary | null { return this.stats?.getSummary() ?? null } getMemorySnapshot(): Promise { if (!this.store) { throw new Error('runtime_unavailable') } return collectMemorySnapshot(this.store) } getUIState(): PersistedUIState { if (!this.store?.getUI) { throw new Error('runtime_unavailable') } return this.store.getUI() } updateUIState(updates: Partial): PersistedUIState { if (!this.store?.getUI || !this.store.updateUI) { throw new Error('runtime_unavailable') } this.store.updateUI(updates) return this.store.getUI() } recordFeatureInteraction(id: FeatureInteractionId): PersistedUIState { if (!this.store?.recordFeatureInteraction) { throw new Error('runtime_unavailable') } return this.store.recordFeatureInteraction(id) } getClientSettings(): Pick< GlobalSettings, | 'defaultTuiAgent' | 'disabledTuiAgents' | 'agentCmdOverrides' | 'agentDefaultArgs' | 'agentDefaultEnv' | 'agentStatusHooksEnabled' | 'defaultTaskSource' | 'defaultTaskViewPreset' | 'visibleTaskProviders' | 'defaultRepoSelection' | 'defaultLinearTeamSelection' | 'githubProjects' | 'experimentalNewWorktreeCardStyle' | 'compactWorktreeCards' > { if (!this.store?.getSettings) { throw new Error('runtime_unavailable') } const settings = this.store.getSettings() return { defaultTuiAgent: settings.defaultTuiAgent ?? null, disabledTuiAgents: settings.disabledTuiAgents ?? [], agentCmdOverrides: settings.agentCmdOverrides ?? {}, agentDefaultArgs: settings.agentDefaultArgs ?? {}, agentDefaultEnv: settings.agentDefaultEnv ?? {}, agentStatusHooksEnabled: settings.agentStatusHooksEnabled !== false, defaultTaskSource: settings.defaultTaskSource ?? 'github', defaultTaskViewPreset: settings.defaultTaskViewPreset ?? 'issues', visibleTaskProviders: settings.visibleTaskProviders ?? [...TASK_PROVIDERS], defaultRepoSelection: settings.defaultRepoSelection ?? null, defaultLinearTeamSelection: settings.defaultLinearTeamSelection ?? null, githubProjects: settings.githubProjects, experimentalNewWorktreeCardStyle: settings.experimentalNewWorktreeCardStyle === true, compactWorktreeCards: settings.compactWorktreeCards === true } } updateClientSettings( updates: Pick< Partial, | 'agentStatusHooksEnabled' | 'defaultTuiAgent' | 'disabledTuiAgents' | 'agentDefaultArgs' | 'agentDefaultEnv' | 'defaultTaskSource' | 'defaultTaskViewPreset' | 'visibleTaskProviders' | 'defaultRepoSelection' | 'defaultLinearTeamSelection' | 'githubProjects' | 'experimentalNewWorktreeCardStyle' | 'compactWorktreeCards' > ): Pick< GlobalSettings, | 'defaultTuiAgent' | 'disabledTuiAgents' | 'agentCmdOverrides' | 'agentDefaultArgs' | 'agentDefaultEnv' | 'agentStatusHooksEnabled' | 'defaultTaskSource' | 'defaultTaskViewPreset' | 'visibleTaskProviders' | 'defaultRepoSelection' | 'defaultLinearTeamSelection' | 'githubProjects' | 'experimentalNewWorktreeCardStyle' | 'compactWorktreeCards' > { if (!this.store?.getSettings || !this.store.updateSettings) { throw new Error('runtime_unavailable') } const before = this.store.getSettings().agentStatusHooksEnabled !== false this.store.updateSettings(updates, { notifyListeners: true }) if ( typeof updates.agentStatusHooksEnabled === 'boolean' && before !== updates.agentStatusHooksEnabled ) { applyAgentStatusHooksEnabled(updates.agentStatusHooksEnabled) } return this.getClientSettings() } listAutomations(): Automation[] { if (!this.store?.listAutomations) { throw new Error('runtime_unavailable') } return this.store.listAutomations() } listAutomationRuns(automationId?: string): AutomationRun[] { if (!this.store?.listAutomationRuns) { throw new Error('runtime_unavailable') } return this.store.listAutomationRuns(automationId) } showAutomation(id: string): Automation { const automation = this.listAutomations().find((entry) => entry.id === id) if (!automation) { throw new Error('Automation not found.') } return automation } async createAutomation(input: RuntimeAutomationCreateInput): Promise { if (!this.store?.createAutomation) { throw new Error('runtime_unavailable') } const target = await this.resolveAutomationTarget(input) if (input.reuseSession && target.workspaceMode !== 'existing') { throw new Error('Session reuse requires an existing workspace target.') } return this.store.createAutomation({ name: input.name, prompt: input.prompt, precheck: input.precheck, agentId: input.agentId, runContext: input.runContext, sourceContext: input.sourceContext, projectId: target.projectId, workspaceMode: target.workspaceMode, workspaceId: target.workspaceId, baseBranch: input.baseBranch, setupDecision: input.setupDecision, reuseSession: input.reuseSession, timezone: input.timezone ?? Intl.DateTimeFormat().resolvedOptions().timeZone, rrule: input.rrule, dtstart: input.dtstart, enabled: input.enabled, missedRunGraceMinutes: input.missedRunGraceMinutes }) } async updateAutomation(id: string, updates: RuntimeAutomationUpdateInput): Promise { if (!this.store?.updateAutomation) { throw new Error('runtime_unavailable') } const current = this.showAutomation(id) const patch: AutomationUpdateInput = {} if (hasRuntimeAutomationUpdateValue(updates, 'name')) { patch.name = updates.name } if (hasRuntimeAutomationUpdateValue(updates, 'prompt')) { patch.prompt = updates.prompt } if (hasRuntimeAutomationUpdateValue(updates, 'precheck')) { patch.precheck = updates.precheck } if (hasRuntimeAutomationUpdateValue(updates, 'agentId')) { patch.agentId = updates.agentId } if (hasRuntimeAutomationUpdateValue(updates, 'runContext')) { patch.runContext = updates.runContext } if (hasRuntimeAutomationUpdateValue(updates, 'sourceContext')) { patch.sourceContext = updates.sourceContext } if (hasRuntimeAutomationUpdateValue(updates, 'baseBranch')) { patch.baseBranch = updates.baseBranch } if (hasRuntimeAutomationUpdateValue(updates, 'setupDecision')) { patch.setupDecision = updates.setupDecision } if (hasRuntimeAutomationUpdateValue(updates, 'reuseSession')) { patch.reuseSession = updates.reuseSession } if (hasRuntimeAutomationUpdateValue(updates, 'timezone')) { patch.timezone = updates.timezone } if (hasRuntimeAutomationUpdateValue(updates, 'rrule')) { patch.rrule = updates.rrule } if (hasRuntimeAutomationUpdateValue(updates, 'dtstart')) { patch.dtstart = updates.dtstart } if (hasRuntimeAutomationUpdateValue(updates, 'enabled')) { patch.enabled = updates.enabled } if (hasRuntimeAutomationUpdateValue(updates, 'missedRunGraceMinutes')) { patch.missedRunGraceMinutes = updates.missedRunGraceMinutes } const targetChanged = hasRuntimeAutomationUpdateValue(updates, 'repo') || hasRuntimeAutomationUpdateValue(updates, 'workspace') || hasRuntimeAutomationUpdateValue(updates, 'workspaceMode') if (targetChanged) { const target = await this.resolveAutomationTarget(updates, current) if (patch.reuseSession === true && target.workspaceMode !== 'existing') { throw new Error('Session reuse requires an existing workspace target.') } patch.projectId = target.projectId patch.workspaceMode = target.workspaceMode patch.workspaceId = target.workspaceId if (target.workspaceMode !== 'existing') { patch.reuseSession = false } } if (!targetChanged && patch.reuseSession && current.workspaceMode !== 'existing') { throw new Error('Session reuse requires an existing workspace target.') } return this.store.updateAutomation(id, patch) } deleteAutomation(id: string): { removed: boolean; id: string } { if (!this.store?.deleteAutomation) { throw new Error('runtime_unavailable') } this.showAutomation(id) this.store.deleteAutomation(id) return { removed: true, id } } async runAutomationNow(id: string): Promise { if (!this.automationService) { throw new Error('runtime_unavailable') } return await this.automationService.runNow(id) } private async resolveAutomationTarget( input: { repo?: string workspace?: string workspaceMode?: AutomationWorkspaceMode baseBranch?: string | null }, current?: Automation ): Promise<{ projectId: string workspaceMode: AutomationWorkspaceMode workspaceId?: string | null }> { const hasRepo = input.repo !== undefined const hasWorkspace = input.workspace !== undefined if ( current?.workspaceMode === 'existing' && hasRepo && !hasWorkspace && input.workspaceMode !== 'new_per_run' ) { throw new Error( 'Repo updates for existing-workspace automation require workspaceMode new_per_run.' ) } const workspace = input.workspace ? await this.showManagedWorktree(input.workspace) : null const repo = input.repo ? await this.showRepo(input.repo) : null const workspaceMode = input.workspaceMode ?? (workspace ? 'existing' : input.repo && !current ? 'new_per_run' : (current?.workspaceMode ?? 'new_per_run')) if (workspaceMode === 'existing') { const workspaceId = workspace?.id ?? current?.workspaceId const projectId = workspace?.repoId ?? current?.projectId if (repo && repo.id !== projectId) { throw new Error('Selected workspace belongs to a different repo.') } if (!workspaceId || !projectId) { throw new Error('Existing-workspace automation requires --workspace.') } return { projectId, workspaceMode, workspaceId } } const projectId = repo?.id ?? workspace?.repoId ?? current?.projectId if (!projectId) { throw new Error('Automation requires --repo or --workspace.') } return { projectId, workspaceMode: 'new_per_run', workspaceId: null } } // Why: lazy initialization — the DB path depends on Electron's userData // which may not be finalized until after app.ready. Also allows unit tests // to inject an in-memory DB without touching the filesystem. getOrchestrationDb(): OrchestrationDb { if (!this._orchestrationDb) { const { app } = require('electron') const dbPath = join(app.getPath('userData'), 'orchestration.db') this._orchestrationDb = new OrchestrationDb(dbPath) } return this._orchestrationDb } setOrchestrationDb(db: OrchestrationDb): void { this._orchestrationDb = db } setAutomationService(service: AutomationService): void { this.automationService = service } getRuntimeId(): string { return this.runtimeId } getStartedAt(): number { return this.startedAt } getStatus(): RuntimeStatus { // Why: browser panes need a backend that can create and stream a page. A // desktop renderer provides one via ; a headless serve provides one // via the offscreen backend. Either way the same browser.screencast.v1 path // works, so advertise it when either is present. browser.headless.v1 // additionally tells clients this host owns browser pages with no renderer, // so they must not fall back to a local desktop browser tab. const hasRenderer = Boolean(this.getAvailableAuthoritativeWindow()) const hasOffscreen = !hasRenderer && Boolean(this.offscreenBrowserBackend) const canBrowse = hasRenderer || hasOffscreen const capabilities: RuntimeCapability[] = RUNTIME_CAPABILITIES.filter( (capability) => capability !== 'browser.screencast.v1' || canBrowse ) if (hasOffscreen) { capabilities.push(BROWSER_HEADLESS_RUNTIME_CAPABILITY) } return { runtimeId: this.runtimeId, rendererGraphEpoch: this.rendererGraphEpoch, graphStatus: this.graphStatus, authoritativeWindowId: this.authoritativeWindowId, liveTabCount: this.tabs.size, liveLeafCount: this.leaves.size, runtimeProtocolVersion: RUNTIME_PROTOCOL_VERSION, minCompatibleRuntimeClientVersion: MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION, // Why: headless orca serve cannot create/stream BrowserViews, so clients // must not treat browser panes as supported just because runtime RPC is up. capabilities, hostPlatform: process.platform, protocolVersion: RUNTIME_PROTOCOL_VERSION, minCompatibleMobileVersion: MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION } } setPtyController(controller: RuntimePtyController | null): void { // Why: CLI terminal writes must go through the main-owned PTY registry // instead of tunneling back through renderer IPC, or live handles could // drift from the process they are supposed to control during reloads. this.ptyController = controller } setNotifier(notifier: RuntimeNotifier | null): void { this.notifier = notifier // Why: run the one-shot fork-upstream backfill once a renderer is attached, // so existing forks self-correct on launch and the result can be broadcast. if (notifier && !this.forkBackfillStarted) { this.forkBackfillStarted = true void this.backfillForkUpstreams() } } onClientEvent(listener: (event: RuntimeClientEvent) => void): () => void { this.clientEventListeners.add(listener) return () => { this.clientEventListeners.delete(listener) } } private emitClientEvent(event: RuntimeClientEvent): void { for (const listener of this.clientEventListeners) { listener(event) } } private notifyWorktreesChanged(repoId: string): void { this.notifier?.worktreesChanged(repoId) this.emitClientEvent({ type: 'worktreesChanged', repoId }) } private notifyReposChanged(): void { this.notifier?.reposChanged() this.emitClientEvent({ type: 'reposChanged' }) } private notifyActivateWorktree( repoId: string, worktreeId: string, setup?: CreateWorktreeResult['setup'], startup?: WorktreeStartupLaunch, defaultTabs?: CreateWorktreeResult['defaultTabs'] ): void { this.notifier?.activateWorktree(repoId, worktreeId, setup, startup, defaultTabs) this.emitClientEvent( toRuntimeActivateWorktreeEvent(repoId, worktreeId, setup, startup, defaultTabs) ) } setAgentBrowserBridge(bridge: AgentBrowserBridge | null): void { this.agentBrowserBridge = bridge } getAgentBrowserBridge(): AgentBrowserBridge | null { return this.agentBrowserBridge } setOffscreenBrowserBackend(backend: BrowserBackend | null): void { this.offscreenBrowserBackend = backend } getOffscreenBrowserBackend(): BrowserBackend | null { return this.offscreenBrowserBackend } setEmulatorBridge(bridge: EmulatorBridge | null): void { this.emulatorBridge = bridge setEmulatorBridge(bridge) } getEmulatorBridge(): EmulatorBridge | null { return this.emulatorBridge } attachWindow(windowId: number): void { if (this.authoritativeWindowId === null) { this.authoritativeWindowId = windowId } } syncWindowGraph(windowId: number, graph: RuntimeSyncWindowGraph): RuntimeSyncWindowGraphResult { if (this.authoritativeWindowId === null) { this.authoritativeWindowId = windowId } if (windowId !== this.authoritativeWindowId) { throw new Error('Runtime graph publisher does not match the authoritative window') } this.tabs = new Map(graph.tabs.map((tab) => [tab.tabId, tab])) this.syncMobileSessionTabs(graph.mobileSessionTabs) const nextLeaves = new Map() const graphSyncedAt = this.nextTitleObservationSequence() // Why: renderer reloads can briefly republish the same leaf with no ptyId; // keep live CLI handles usable while the UI graph rebuilds. const preserveLivePtysDuringReload = this.graphStatus === 'reloading' for (const leaf of graph.leaves) { const leafKey = this.getLeafKey(leaf.tabId, leaf.leafId) const existing = this.leaves.get(leafKey) const ptyId = preserveLivePtysDuringReload && leaf.ptyId === null && existing?.ptyId ? existing.ptyId : leaf.ptyId const ptyGeneration = existing && existing.ptyId !== ptyId ? existing.ptyGeneration + 1 : (existing?.ptyGeneration ?? 0) const existingPty = ptyId ? this.ptysById.get(ptyId) : undefined const tailSource = existing?.ptyId === ptyId ? existing : existingPty nextLeaves.set(leafKey, { ...leaf, ptyId, ptyGeneration, connected: ptyId !== null, writable: this.graphStatus === 'ready' && ptyId !== null, lastOutputAt: tailSource?.lastOutputAt ?? null, lastExitCode: tailSource?.lastExitCode ?? null, tailBuffer: tailSource?.tailBuffer ?? [], tailPartialLine: tailSource?.tailPartialLine ?? '', tailPendingAnsi: tailSource?.tailPendingAnsi ?? '', tailRedrawCursor: tailSource?.tailRedrawCursor ?? null, tailTruncated: tailSource?.tailTruncated ?? false, tailLinesTotal: tailSource?.tailLinesTotal ?? 0, preview: tailSource?.preview ?? '', waitBlockedAt: tailSource?.waitBlockedAt ?? null, lastAgentStatus: tailSource?.lastAgentStatus ?? null, lastOscTitle: tailSource?.lastOscTitle ?? null, lastOscTitleAt: tailSource?.lastOscTitleAt ?? null, paneTitleUpdatedAt: existing?.ptyId === ptyId && existing.paneTitle === leaf.paneTitle ? existing.paneTitleUpdatedAt : graphSyncedAt }) if (leaf.ptyId) { this.recordPtyWorktree(leaf.ptyId, leaf.worktreeId, { connected: true, lastOutputAt: existing?.ptyId === leaf.ptyId ? existing.lastOutputAt : null, preview: existing?.ptyId === leaf.ptyId ? existing.preview : '', tabId: leaf.tabId, paneKey: this.makeRuntimePaneKey(leaf) }) } if (existing && (existing.ptyId !== ptyId || existing.ptyGeneration !== ptyGeneration)) { this.invalidateLeafHandle(leafKey) } } for (const oldLeafKey of this.leaves.keys()) { if (!nextLeaves.has(oldLeafKey)) { const oldLeaf = this.leaves.get(oldLeafKey) if ( preserveLivePtysDuringReload && oldLeaf?.ptyId && this.handleByPtyId.has(oldLeaf.ptyId) ) { // Why: a CLI-created agent keeps using its exported handle even if // the reloaded renderer has not rebound the pane yet. nextLeaves.set(oldLeafKey, oldLeaf) } else { this.invalidateLeafHandle(oldLeafKey) } } } const nextPtyIds = new Set( [...nextLeaves.values()].map((leaf) => leaf.ptyId).filter((ptyId): ptyId is string => !!ptyId) ) for (const [ptyId, leaf] of this.detachedPreAllocatedLeaves) { if (nextPtyIds.has(ptyId) || !this.handleByPtyId.has(ptyId)) { this.detachedPreAllocatedLeaves.delete(ptyId) continue } nextLeaves.set(this.getLeafKey(leaf.tabId, leaf.leafId), leaf) nextPtyIds.add(ptyId) } this.leaves = nextLeaves this.rebuildLeafPtyIndex() this.notifyMobileSessionTabSnapshots() this.graphStatus = 'ready' this.refreshWritableFlags() for (const leaf of this.leaves.values()) { this.adoptPreAllocatedHandle(leaf) } // Why: createTerminal waits for the renderer's graph sync to populate the // new leaf so it can return a handle. Drain callbacks after leaves update. for (const cb of [...this.graphSyncCallbacks]) { cb() } const agentOrchestrationByPaneKey = this.buildAgentOrchestrationByPaneKey() return { ...this.getStatus(), ...(agentOrchestrationByPaneKey ? { agentOrchestrationByPaneKey } : {}) } } async listMobileSessionTabs(worktreeSelector: string): Promise { const explicitWorktreeId = getExplicitWorktreeIdSelector(worktreeSelector) if (explicitWorktreeId) { this.hydrateHeadlessMobileSessionTabsFromWorkspaceSession(explicitWorktreeId) await this.refreshMobileSessionPtyRecords() return this.getMobileSessionTabsForWorktree(explicitWorktreeId) } const worktree = await this.resolveWorktreeSelector(worktreeSelector) this.hydrateHeadlessMobileSessionTabsFromWorkspaceSession(worktree.id) await this.refreshMobileSessionPtyRecords() return this.getMobileSessionTabsForWorktree(worktree.id) } async listAllMobileSessionTabs(): Promise { this.hydrateHeadlessMobileSessionTabsFromWorkspaceSession() await this.refreshMobileSessionPtyRecords() return [...this.mobileSessionTabsByWorktree.values()].map((snapshot) => this.toMobileSessionTabsResult(snapshot) ) } private hydrateHeadlessMobileSessionTabsFromWorkspaceSession( worktreeId?: string, options: { force?: boolean allowAttachedWindow?: boolean onlyServeOwnedTerminals?: boolean } = {} ): void { if (this.getAvailableAuthoritativeWindow() && options.allowAttachedWindow !== true) { return } const session = this.store?.getWorkspaceSession?.() if (!session) { return } const entries = worktreeId !== undefined ? ([[worktreeId, session.tabsByWorktree[worktreeId] ?? []]] as const) : Object.entries(session.tabsByWorktree ?? {}) for (const [entryWorktreeId, persistedTabs] of entries) { const existing = this.mobileSessionTabsByWorktree.get(entryWorktreeId) if ( existing && existing.tabs.length > 0 && options.force !== true && options.onlyServeOwnedTerminals !== true ) { // Why: terminals are stable/persisted so we normally skip a rebuild, but // offscreen browser tabs are live and may have been created/closed since. // Reconcile just the browser tabs against the live bridge instead of // leaving a stale snapshot that omits a freshly-opened browser tab. this.reconcileHeadlessMobileSessionBrowserTabs(entryWorktreeId, existing) continue } const terminalTabs = this.buildHeadlessMobileSessionTerminalTabs( entryWorktreeId, persistedTabs ).filter( (tab) => options.onlyServeOwnedTerminals !== true || this.hasServeOwnedPtyBinding(tab) ) // Why: offscreen browser panes are live-only (no persisted session entry), // so include them on every hydrate regardless of the onlyServeOwnedTerminals // filter, which is about terminal PTY ownership and never applies to browsers. const browserTabs = this.buildHeadlessMobileSessionBrowserTabs(entryWorktreeId) const tabs: RuntimeMobileSessionSnapshotTab[] = [...terminalTabs, ...browserTabs] if (tabs.length === 0) { continue } const activeTab = this.pickHeadlessActiveTerminalTab(terminalTabs) const tabOrder = [ ...this.collectHeadlessParentTabOrder(terminalTabs), ...browserTabs.map((tab) => tab.id) ] const groupId = this.getHeadlessMobileSessionGroupId(entryWorktreeId) const mergedTabs = options.onlyServeOwnedTerminals === true && existing ? this.mergeMobileSessionSnapshotTabs(existing.tabs, tabs) : tabs const mergedActiveTab = existing?.tabs.find((tab) => tab.id === existing.activeTabId) ?? activeTab ?? mergedTabs[0] ?? null const mergedTerminalTabs = mergedTabs.filter( (tab): tab is RuntimeMobileSessionTerminalTab => tab.type === 'terminal' ) const mergedBrowserOrder = mergedTabs .filter((tab): tab is RuntimeMobileSessionBrowserTab => tab.type === 'browser') .map((tab) => tab.id) // Why: a persisted multi-group split must be restored on cold rebuild, or // the headless serve coalesces the user's group layout back into one group // (the persisted tabGroups/tabGroupLayouts would otherwise be write-only). const persistedGroups = session.tabGroups?.[entryWorktreeId] const persistedLayout = session.tabGroupLayouts?.[entryWorktreeId] const hasPersistedSplit = options.onlyServeOwnedTerminals !== true && persistedGroups !== undefined && persistedGroups.length > 1 const activeTopLevelId = mergedActiveTab ? mergedActiveTab.type === 'terminal' ? mergedActiveTab.parentTabId : mergedActiveTab.id : null this.mobileSessionTabsByWorktree.set(entryWorktreeId, { worktree: existing?.worktree ?? entryWorktreeId, publicationEpoch: `headless-hydrated:${Date.now().toString(36)}`, snapshotVersion: (existing?.snapshotVersion ?? 0) + 1, activeGroupId: existing?.activeGroupId ?? groupId, activeTabId: mergedActiveTab?.id ?? null, activeTabType: mergedActiveTab?.type ?? null, tabGroups: hasPersistedSplit ? this.appendBrowserTabOrder( this.distributeHeadlessTabsAcrossGroups( persistedGroups.map((group) => ({ id: group.id, activeTabId: group.activeTabId, tabOrder: [...group.tabOrder], ...(group.recentTabIds ? { recentTabIds: [...group.recentTabIds] } : {}) })), this.collectHeadlessParentTabOrder(mergedTerminalTabs), activeTopLevelId ), mergedBrowserOrder, undefined, // Why: distribute drops browser ids (terminal-only), so carry each // browser's persisted group forward instead of coalescing left. this.collectBrowserGroupAssignment(persistedGroups, mergedBrowserOrder) ) : options.onlyServeOwnedTerminals === true && existing?.tabGroups ? this.appendBrowserTabOrder( this.mergeMobileSessionTabGroups( entryWorktreeId, existing.tabGroups, mergedTerminalTabs, mergedActiveTab?.type === 'terminal' ? mergedActiveTab : null ), mergedBrowserOrder ) : [ { id: groupId, activeTabId: mergedActiveTab?.id ? (activeTab?.parentTabId ?? mergedActiveTab.id) : (tabOrder[0] ?? null), tabOrder } ], ...(hasPersistedSplit && persistedLayout ? { tabGroupLayout: persistedLayout } : {}), tabs: mergedTabs }) } } // Why: keep an existing snapshot's browser tabs in sync with the live bridge // without rebuilding stable terminal state. Replaces browser entries with the // current live set and rewrites the browser portion of the primary group order. private reconcileHeadlessMobileSessionBrowserTabs( worktreeId: string, existing: RuntimeMobileSessionTabsSnapshot ): void { if (!this.offscreenBrowserBackend) { return } const liveBrowserTabs = this.buildHeadlessMobileSessionBrowserTabs(worktreeId) const liveIds = liveBrowserTabs.map((tab) => tab.id) const existingBrowserIds = existing.tabs .filter((tab): tab is RuntimeMobileSessionBrowserTab => tab.type === 'browser') .map((tab) => tab.id) const unchanged = liveIds.length === existingBrowserIds.length && liveIds.every((id, index) => existingBrowserIds[index] === id) if (unchanged) { return } const nonBrowserTabs = existing.tabs.filter((tab) => tab.type !== 'browser') const nextTabs: RuntimeMobileSessionSnapshotTab[] = [...nonBrowserTabs, ...liveBrowserTabs] const liveIdSet = new Set(liveIds) const tabGroups = this.appendBrowserTabOrder( (existing.tabGroups ?? []).map((group) => ({ ...group, // Drop closed browser ids; appendBrowserTabOrder re-adds the live ones. tabOrder: group.tabOrder.filter( (id) => liveIdSet.has(id) || !existingBrowserIds.includes(id) ) })), liveIds ) const activeStillPresent = nextTabs.some((tab) => tab.id === existing.activeTabId) const active = activeStillPresent ? null : (nextTabs.find((tab) => tab.isActive) ?? nextTabs[0] ?? null) this.mobileSessionTabsByWorktree.set(worktreeId, { ...existing, publicationEpoch: `headless-hydrated:${Date.now().toString(36)}`, snapshotVersion: existing.snapshotVersion + 1, ...(activeStillPresent ? {} : { activeTabId: active?.id ?? null, activeTabType: active?.type ?? null }), tabGroups, tabs: nextTabs }) } // Why: browser session tabs have no parentTabId so the terminal-only group // builder drops them from tabOrder; this re-adds their ids to a group. // Browser tabs are live-only (no persisted session entry), but their GROUP // membership must still survive snapshot rebuilds like terminals'. The // passed-in groups already encode each browser's group (carried from the prior // snapshot / persisted tabGroups), so keep each existing browser id where it // is; only a genuinely-new browser id goes to its create-target group (when // that group exists) and otherwise to the first group. Previously every // browser was force-pushed into group[0], so opening a browser in the right // split group always snapped it back to the left on the next rebuild. private appendBrowserTabOrder( groups: readonly RuntimeMobileSessionTabGroup[], browserTabIds: readonly string[], newTabAssignment?: { tabId: string; groupId: string }, // browserPageId -> groupId from the prior/persisted groups. The terminal // distributor rebuilds tabOrder from terminal ids only and drops browser // ids, so this carries each browser's group across rebuilds. priorGroupByBrowserId?: ReadonlyMap ): RuntimeMobileSessionTabGroup[] { if (browserTabIds.length === 0) { return [...groups] } const next = groups.map((group) => ({ ...group, tabOrder: [...group.tabOrder] })) if (next.length === 0) { return next } const groupById = new Map(next.map((group) => [group.id, group])) const ownerGroupByTabId = new Map() for (const group of next) { for (const id of group.tabOrder) { ownerGroupByTabId.set(id, group) } } for (const id of browserTabIds) { if (ownerGroupByTabId.has(id)) { continue } const priorGroupId = priorGroupByBrowserId?.get(id) const targetGroup = (newTabAssignment?.tabId === id ? groupById.get(newTabAssignment.groupId) : undefined) ?? (priorGroupId ? groupById.get(priorGroupId) : undefined) ?? next[0]! targetGroup.tabOrder.push(id) } return next } // browserPageId -> groupId from a set of groups (the persisted/prior layout), // so a browser stays in its group across rebuilds that drop browser ids. private collectBrowserGroupAssignment( groups: readonly RuntimeMobileSessionTabGroup[] | undefined, browserTabIds: readonly string[] ): Map { const browserIdSet = new Set(browserTabIds) const assignment = new Map() for (const group of groups ?? []) { for (const id of group.tabOrder) { if (browserIdSet.has(id)) { assignment.set(id, group.id) } } } return assignment } private isServeOwnedPtyId(ptyId: string | null | undefined): boolean { return typeof ptyId === 'string' && ptyId.startsWith('serve-') } private hasServeOwnedPtyBinding(tab: RuntimeMobileSessionTerminalTab): boolean { if (this.isServeOwnedPtyId(tab.ptyId)) { return true } return Object.values(tab.parentLayout?.ptyIdsByLeafId ?? {}).some((ptyId) => this.isServeOwnedPtyId(ptyId) ) } // Why: serve-* (local serve) and ssh:@@ (SSH relay) ids are minted // ONLY for runtime-owned terminals and are preserved/re-hydrated, so tear them // down even if the renderer adopted a view (else they resurrect). The daemon // session form @@ is deliberately NOT here: the daemon // mints it for ordinary renderer-owned local terminals too, so id shape can't // classify ownership for that form — renderer-graph membership does (below). private isServeOrSshOwnedPtyId(ptyId: string | null | undefined): boolean { return ( this.isServeOwnedPtyId(ptyId) || (typeof ptyId === 'string' && parseAppSshPtyId(ptyId) !== null) ) } private hasServeOrSshOwnedBinding(tab: RuntimeMobileSessionTerminalTab): boolean { if (this.isServeOrSshOwnedPtyId(tab.ptyId)) { return true } return Object.values(tab.parentLayout?.ptyIdsByLeafId ?? {}).some((ptyId) => this.isServeOrSshOwnedPtyId(ptyId) ) } // Why: a tab needs authoritative runtime teardown (kill + de-persist + prune) // only when the renderer can't durably tear it down: either it's serve/SSH // (preserved + re-hydrated, would resurrect) or the renderer graph never // published it (a leaked/unadopted shell — incl. daemon-session `@@` tabs the // host materialized but the renderer never showed). A tab the renderer graph // DOES list — including an ordinary daemon-backed local terminal or a pending // tab whose PTY hasn't bound — is renderer-owned: delegate, do not de-persist. private isRuntimeOwnedHeadlessMobileTab( worktreeId: string, tab: RuntimeMobileSessionTerminalTab ): boolean { if (this.hasServeOrSshOwnedBinding(tab)) { return true } const pty = this.findPtyForMobileTerminalTab(worktreeId, tab) if (pty && this.isServeOrSshOwnedPtyId(pty.ptyId)) { return true } return !this.tabs.has(tab.parentTabId) } private mergeMobileSessionSnapshotTabs( baseTabs: readonly RuntimeMobileSessionSnapshotTab[], extraTabs: readonly RuntimeMobileSessionSnapshotTab[] ): RuntimeMobileSessionSnapshotTab[] { const seenIds = new Set() const merged: RuntimeMobileSessionSnapshotTab[] = [] const add = (tab: RuntimeMobileSessionSnapshotTab): void => { const ids = this.getMobileSessionSnapshotTabIdentityKeys(tab) if (ids.some((id) => seenIds.has(id))) { return } for (const id of ids) { seenIds.add(id) } merged.push(tab) } for (const tab of baseTabs) { add(tab) } for (const tab of extraTabs) { add(tab) } return merged } private getMobileSessionSnapshotTabIdentityKeys(tab: RuntimeMobileSessionSnapshotTab): string[] { if (tab.type === 'terminal') { // Why: split terminal leaves share one parent tab; merge dedup must stay // leaf-scoped or preserved siblings collapse into a single surface. const keys = [tab.id, `${tab.parentTabId}::${tab.leafId}`] if (typeof tab.ptyId === 'string' && tab.ptyId.length > 0) { // Why: renderer and headless sources can derive different leafIds for the same // terminal; real PTYs collapse those duplicates without merging pending splits. keys.push(`${tab.parentTabId}::pty:${tab.ptyId}`) } return keys } if (tab.type === 'browser') { return [tab.id, tab.browserWorkspaceId] } return [tab.id] } private mergeMobileSessionTabGroups( worktreeId: string, groups: readonly RuntimeMobileSessionTabGroup[], terminalTabs: readonly RuntimeMobileSessionTerminalTab[], activeTab: RuntimeMobileSessionTerminalTab | null ): RuntimeMobileSessionTabGroup[] { const parentTabOrder = this.collectHeadlessParentTabOrder(terminalTabs) if (parentTabOrder.length === 0) { return [...groups] } const targetGroupId = groups[0]?.id ?? this.getHeadlessMobileSessionGroupId(worktreeId) const nextGroups = groups.length > 0 ? groups.map((group) => ({ ...group, tabOrder: [...group.tabOrder] })) : [ { id: targetGroupId, activeTabId: null, tabOrder: [] } ] // Why: keep each tab in the group that already owns it (a multi-group split // must survive the merge), drop tabs no longer present, and route only // genuinely-new tabs into the active group — never funnel everything into // group[0], which duplicated/coalesced tabs that lived in other groups. const ownerGroupId = new Map() for (const group of nextGroups) { for (const tabId of group.tabOrder) { ownerGroupId.set(tabId, group.id) } } const liveTabIds = new Set(parentTabOrder) const activeParentId = activeTab?.parentTabId ?? null const activeGroupId = (activeParentId ? ownerGroupId.get(activeParentId) : undefined) ?? nextGroups[0]!.id const retainedOrder = new Map(nextGroups.map((group) => [group.id, []])) for (const tabId of parentTabOrder) { const groupId = ownerGroupId.get(tabId) ?? activeGroupId retainedOrder.get(groupId)?.push(tabId) } return nextGroups .map((group) => { const tabOrder = retainedOrder.get(group.id) ?? [] const keptActive = group.activeTabId && tabOrder.includes(group.activeTabId) && liveTabIds.has(group.activeTabId) ? group.activeTabId : null return { ...group, tabOrder, activeTabId: activeParentId && tabOrder.includes(activeParentId) ? activeParentId : (keptActive ?? tabOrder[0] ?? null) } }) .filter((group) => group.tabOrder.length > 0) } /** * Publishes a PTY-backed terminal tab snapshot to the synced mobile session, * normalizing Pi-compatible titles based on launch ownership. */ private publishPtyBackedMobileSessionTerminal( worktreeId: string, pty: RuntimePtyWorktreeRecord, args: { tabId: string leafId: string title: string | null activate: boolean selectIfNoActiveTab?: boolean split?: { splitFromLeafId: string; direction: 'horizontal' | 'vertical' } } ): void { const existing = this.mobileSessionTabsByWorktree.get(worktreeId) const title = normalizeCompatibleAgentTitleForOwner( args.title ?? getLatestPtyTitle(pty) ?? 'Terminal', pty.launchAgent ) const existingTab = existing?.tabs.find( (candidate): candidate is RuntimeMobileSessionTerminalTab => candidate.type === 'terminal' && candidate.parentTabId === args.tabId && candidate.leafId === args.leafId ) // Why: a split inserts into the parent tab's layout, which lives on the // sibling surface, not this new leaf's (empty) existing surface. const baseLayout = args.split ? (existing?.tabs.find( (candidate): candidate is RuntimeMobileSessionTerminalTab => candidate.type === 'terminal' && candidate.parentTabId === args.tabId && candidate.leafId === args.split!.splitFromLeafId )?.parentLayout ?? existingTab?.parentLayout) : existingTab?.parentLayout const parentLayout = this.buildMaterializedHeadlessParentLayout( args.leafId, pty.ptyId, baseLayout, args.split ) const tab: RuntimeMobileSessionTerminalTab = { type: 'terminal', id: `${args.tabId}::${args.leafId}`, parentTabId: args.tabId, leafId: args.leafId, ptyId: pty.ptyId, title, ...(pty.launchAgent ? { launchAgent: pty.launchAgent } : {}), parentLayout, isActive: args.activate || (args.selectIfNoActiveTab !== false && existing?.activeTabId == null) } const existingTabs = (existing?.tabs ?? []).filter( (candidate) => !( candidate.type === 'terminal' && candidate.parentTabId === args.tabId && candidate.leafId === args.leafId ) ) const tabs = this.mergeMobileSessionSnapshotTabs( existingTabs.map((candidate) => ({ ...candidate, // Why: the client picks one sibling's parentLayout to render the whole // tab; a split must update every sibling surface to the new tree, or a // stale single-leaf sibling makes the client fall back to a default // direction ("Split Right" renders as down). ...(args.split && candidate.type === 'terminal' && candidate.parentTabId === args.tabId ? { parentLayout } : {}), isActive: tab.isActive ? false : candidate.isActive })), [tab] ) const activeTab = (tab.isActive ? tab : tabs.find((candidate) => candidate.id === existing?.activeTabId)) ?? tabs.find((candidate) => candidate.isActive) ?? (args.selectIfNoActiveTab !== false ? tabs[0] : null) ?? null const terminalTabs = tabs.filter( (candidate): candidate is RuntimeMobileSessionTerminalTab => candidate.type === 'terminal' ) const next: RuntimeMobileSessionTabsSnapshot = { worktree: worktreeId, publicationEpoch: existing?.publicationEpoch ?? `headless:pty-backed:${Date.now().toString(36)}`, snapshotVersion: (existing?.snapshotVersion ?? 0) + 1, activeGroupId: existing?.activeGroupId ?? this.getHeadlessMobileSessionGroupId(worktreeId), activeTabId: activeTab?.id ?? null, activeTabType: activeTab?.type ?? null, tabGroups: this.mergeMobileSessionTabGroups( worktreeId, existing?.tabGroups ?? [], terminalTabs, activeTab?.type === 'terminal' ? activeTab : null ), ...(existing?.tabGroupLayout ? { tabGroupLayout: existing.tabGroupLayout } : {}), tabs } this.mobileSessionTabsByWorktree.set(worktreeId, next) this.notifyMobileSessionTabsChanged(worktreeId) } private touchMobileSessionSnapshotsForPty(ptyId: string): void { for (const [worktreeId, snapshot] of this.mobileSessionTabsByWorktree) { const hasPtyBackedTab = snapshot.tabs.some( (tab) => tab.type === 'terminal' && (tab.ptyId === ptyId || tab.parentLayout?.ptyIdsByLeafId?.[tab.leafId] === ptyId) ) if (!hasPtyBackedTab) { continue } this.mobileSessionTabsByWorktree.set(worktreeId, { ...snapshot, snapshotVersion: snapshot.snapshotVersion + 1 }) this.notifyMobileSessionTabsChanged(worktreeId) } } private buildHeadlessMobileSessionTerminalTabs( worktreeId: string, persistedTabs: readonly TerminalTab[] ): RuntimeMobileSessionTerminalTab[] { const session = this.store?.getWorkspaceSession?.() if (!session) { return [] } return [...persistedTabs] .sort((a, b) => a.sortOrder - b.sortOrder || a.createdAt - b.createdAt) .flatMap((tab, index) => { const layout = session.terminalLayoutsByTabId?.[tab.id] const leafIds = this.collectPersistedTerminalLeafIds(layout) if (leafIds.length === 0) { leafIds.push(this.deriveHeadlessLegacyTerminalLeafId(tab.id)) } return leafIds.map((leafId) => { const ptyId = layout?.ptyIdsByLeafId?.[leafId] ?? (leafIds.length === 1 ? tab.ptyId : null) const title = tab.customTitle?.trim() || tab.generatedTitle?.trim() || tab.title?.trim() || tab.defaultTitle?.trim() || `Terminal ${index + 1}` return { type: 'terminal' as const, id: `${tab.id}::${leafId}`, parentTabId: tab.id, leafId, title, ...(ptyId ? { ptyId } : {}), ...(tab.launchAgent ? { launchAgent: tab.launchAgent } : {}), ...(layout ? { parentLayout: this.cloneTerminalLayoutSnapshot(layout) } : {}), ...(tab.color != null ? { color: tab.color } : {}), ...(tab.isPinned ? { isPinned: true } : {}), ...(tab.viewMode ? { viewMode: tab.viewMode } : {}), isActive: this.isPersistedTerminalLeafActive(worktreeId, tab.id, leafId, layout) } }) }) } // Why: headless serve backs browser panes with offscreen WebContents that live // only in the BrowserManager, never in a renderer graph. Without surfacing them // as session tabs, a session.tabs snapshot (e.g. on terminal open) prunes the // paired browser tab and closing it fails with tab_not_found. Synthesize browser // session tabs from the live bridge so they are first-class alongside terminals. private buildHeadlessMobileSessionBrowserTabs( worktreeId: string ): RuntimeMobileSessionBrowserTab[] { if (!this.offscreenBrowserBackend || !this.agentBrowserBridge?.tabList) { return [] } return this.agentBrowserBridge.tabList(worktreeId).tabs.map((tab) => { const persistedProps = this.getPersistedUnifiedSessionTabProps(worktreeId, tab.browserPageId) return { type: 'browser' as const, // Why: an offscreen page has no separate workspace identity, so the page id // is its own workspace id (matches the server's browserWorkspaceId fallback). id: tab.browserPageId, title: tab.title || tab.url || 'Browser', browserWorkspaceId: tab.browserPageId, browserPageId: tab.browserPageId, url: tab.url || 'about:blank', loading: false, canGoBack: false, canGoForward: false, ...(persistedProps ? { color: persistedProps.color } : {}), ...(persistedProps ? { isPinned: persistedProps.isPinned === true } : {}), isActive: tab.active === true } }) } private getPersistedUnifiedSessionTabProps( worktreeId: string, tabId: string ): Pick | null { const tab = this.store ?.getWorkspaceSession?.() ?.unifiedTabs?.[worktreeId]?.find( (candidate) => candidate.id === tabId || candidate.entityId === tabId ) ?? null return tab ? { color: tab.color, isPinned: tab.isPinned } : null } private collectPersistedTerminalLeafIds(layout: TerminalLayoutSnapshot | undefined): string[] { if (!layout) { return [] } const leafIds = new Set() const visit = (node: TerminalLayoutSnapshot['root']): void => { if (!node) { return } if (node.type === 'leaf') { if (isTerminalLeafId(node.leafId)) { leafIds.add(node.leafId) } return } visit(node.first) visit(node.second) } visit(layout.root) if (layout.activeLeafId && isTerminalLeafId(layout.activeLeafId)) { leafIds.add(layout.activeLeafId) } for (const leafId of Object.keys(layout.ptyIdsByLeafId ?? {})) { if (isTerminalLeafId(leafId)) { leafIds.add(leafId) } } return [...leafIds] } private deriveHeadlessLegacyTerminalLeafId(tabId: string): string { const hash = createHash('sha256').update(`headless-terminal-leaf:${tabId}`).digest('hex') const variant = ((Number.parseInt(hash.slice(16, 17), 16) & 0x3) | 0x8).toString(16) const leafId = [ hash.slice(0, 8), hash.slice(8, 12), `4${hash.slice(13, 16)}`, `${variant}${hash.slice(17, 20)}`, hash.slice(20, 32) ].join('-') if (!isTerminalLeafId(leafId)) { return randomUUID() } return leafId } private cloneTerminalLayoutSnapshot(layout: TerminalLayoutSnapshot): TerminalLayoutSnapshot { const cloned: TerminalLayoutSnapshot = { root: layout.root, activeLeafId: layout.activeLeafId, expandedLeafId: layout.expandedLeafId } if (layout.ptyIdsByLeafId) { cloned.ptyIdsByLeafId = { ...layout.ptyIdsByLeafId } } if (layout.buffersByLeafId) { cloned.buffersByLeafId = { ...layout.buffersByLeafId } } if (layout.scrollbackRefsByLeafId) { cloned.scrollbackRefsByLeafId = { ...layout.scrollbackRefsByLeafId } } if (layout.titlesByLeafId) { cloned.titlesByLeafId = { ...layout.titlesByLeafId } } return cloned } private isPersistedTerminalLeafActive( worktreeId: string, tabId: string, leafId: string, layout: TerminalLayoutSnapshot | undefined ): boolean { const session = this.store?.getWorkspaceSession?.() const activeTabId = session?.activeTabIdByWorktree?.[worktreeId] ?? session?.activeTabId return activeTabId === tabId && (!layout?.activeLeafId || layout.activeLeafId === leafId) } private pickHeadlessActiveTerminalTab( tabs: readonly RuntimeMobileSessionTerminalTab[] ): RuntimeMobileSessionTerminalTab | null { return tabs.find((tab) => tab.isActive) ?? tabs.find((tab) => tab.parentTabId) ?? null } private collectHeadlessParentTabOrder( tabs: readonly RuntimeMobileSessionTerminalTab[] ): string[] { const order: string[] = [] const seen = new Set() for (const tab of tabs) { if (!seen.has(tab.parentTabId)) { seen.add(tab.parentTabId) order.push(tab.parentTabId) } } return order } // Why: the group tab order must follow actual creation/insertion order across // both terminals and browsers, not list terminals first. A terminal's top-level // id is its parentTabId (split leaves share one); a browser's is its own id. private collectHeadlessTopLevelTabOrder( tabs: readonly RuntimeMobileSessionSnapshotTab[] ): string[] { const order: string[] = [] const seen = new Set() for (const tab of tabs) { const topLevelId = tab.type === 'terminal' ? tab.parentTabId : tab.id if (!seen.has(topLevelId)) { seen.add(topLevelId) order.push(topLevelId) } } return order } private getHeadlessMobileSessionGroupId(worktreeId: string): string { return `headless-terminals:${worktreeId}` } private buildHeadlessMobileSessionTabGroups( worktreeId: string, tabs: readonly RuntimeMobileSessionSnapshotTab[], activeTab: RuntimeMobileSessionSnapshotTab | null, existingGroups?: readonly RuntimeMobileSessionTabGroup[], // Why: a new tab created via a specific group's "+" must land in THAT group, // not the active one — otherwise every "+" in a split funnels to one group. newTabAssignment?: { tabId: string; groupId: string } ): RuntimeMobileSessionTabGroup[] { // Why: order across terminals and browsers in their actual array order so a // tab opened after a browser tab lands to its right, not regrouped before it. const tabOrder = this.collectHeadlessTopLevelTabOrder(tabs) const topLevelOf = (tab: RuntimeMobileSessionSnapshotTab): string => tab.type === 'terminal' ? tab.parentTabId : tab.id const activeTopLevelId = (activeTab ? topLevelOf(activeTab) : null) ?? existingGroups?.[0]?.activeTabId ?? (() => { const active = tabs.find((tab) => tab.isActive) return active ? topLevelOf(active) : null })() ?? tabOrder[0] ?? null // Why: when the user has split tabs into multiple groups, preserve that // assignment across rebuilds instead of coalescing back to one group. if (existingGroups && existingGroups.length > 1) { return this.distributeHeadlessTabsAcrossGroups( existingGroups, tabOrder, activeTopLevelId, newTabAssignment ) } const groupId = existingGroups?.[0]?.id ?? this.getHeadlessMobileSessionGroupId(worktreeId) return [ { id: groupId, activeTabId: activeTopLevelId && tabOrder.includes(activeTopLevelId) ? activeTopLevelId : (tabOrder[0] ?? null), tabOrder } ] } // Distribute live top-level tabs into the existing multi-group structure, // keeping each tab in its group; tabs new since the last snapshot join the // active group. Emptied groups are dropped so a closed split collapses. private distributeHeadlessTabsAcrossGroups( existingGroups: readonly RuntimeMobileSessionTabGroup[], tabOrder: readonly string[], activeTopLevelId: string | null, newTabAssignment?: { tabId: string; groupId: string } ): RuntimeMobileSessionTabGroup[] { const groupIdByTabId = new Map() for (const group of existingGroups) { for (const tabId of group.tabOrder) { groupIdByTabId.set(tabId, group.id) } } // Why: route a freshly-created tab to the group its "+" was clicked in, // when that group still exists; otherwise fall through to the active group. const hasTargetGroup = newTabAssignment !== undefined && existingGroups.some((group) => group.id === newTabAssignment.groupId) if (hasTargetGroup) { groupIdByTabId.set(newTabAssignment!.tabId, newTabAssignment!.groupId) } const activeGroupId = (activeTopLevelId ? groupIdByTabId.get(activeTopLevelId) : undefined) ?? existingGroups[0]!.id const orderByGroup = new Map(existingGroups.map((group) => [group.id, []])) for (const tabId of tabOrder) { const groupId = groupIdByTabId.get(tabId) ?? activeGroupId orderByGroup.get(groupId)?.push(tabId) } return existingGroups .map((group) => { const nextOrder = orderByGroup.get(group.id) ?? [] return { ...group, tabOrder: nextOrder, activeTabId: activeTopLevelId && nextOrder.includes(activeTopLevelId) ? activeTopLevelId : group.activeTabId && nextOrder.includes(group.activeTabId) ? group.activeTabId : (nextOrder[0] ?? null) } }) .filter((group) => group.tabOrder.length > 0) } private buildMaterializedHeadlessParentLayout( leafId: string, ptyId: string, existingLayout: TerminalLayoutSnapshot | undefined, split?: { splitFromLeafId: string; direction: 'horizontal' | 'vertical' } ): TerminalLayoutSnapshot { if (!existingLayout) { return { root: { type: 'leaf', leafId }, activeLeafId: leafId, expandedLeafId: null, ptyIdsByLeafId: { [leafId]: ptyId } } } // Why: a split must insert the new leaf into the live layout tree with the // requested direction, or the published snapshot keeps the old single-leaf // root and the split renders with a fallback direction ("Split Right" lands // as a top/bottom split). Reuse the persisted-split builder for parity. if (split) { return buildHeadlessTerminalSplitLayout(this.cloneTerminalLayoutSnapshot(existingLayout), { leafId, ptyId, splitFromLeafId: split.splitFromLeafId, direction: split.direction }) } return { ...this.cloneTerminalLayoutSnapshot(existingLayout), ptyIdsByLeafId: { ...existingLayout.ptyIdsByLeafId, [leafId]: ptyId } } } private removePersistedHeadlessTerminalTab(worktreeId: string, parentTabId: string): void { const session = this.store?.getWorkspaceSession?.() if (!session || !this.store?.setWorkspaceSession) { return } const tabs = session.tabsByWorktree[worktreeId] ?? [] const nextTabs = tabs.filter((tab) => tab.id !== parentTabId) const nextTabsByWorktree = { ...session.tabsByWorktree, [worktreeId]: nextTabs } const nextLayouts = { ...session.terminalLayoutsByTabId } delete nextLayouts[parentTabId] const nextActiveTabId = session.activeTabIdByWorktree?.[worktreeId] === parentTabId ? (nextTabs[0]?.id ?? null) : (session.activeTabIdByWorktree?.[worktreeId] ?? null) this.store.setWorkspaceSession({ ...session, activeTabId: session.activeTabId === parentTabId ? nextActiveTabId : session.activeTabId, tabsByWorktree: nextTabsByWorktree, terminalLayoutsByTabId: nextLayouts, activeTabIdByWorktree: { ...session.activeTabIdByWorktree, [worktreeId]: nextActiveTabId } }) } private persistHeadlessTerminalTabOrder(worktreeId: string, tabOrder: readonly string[]): void { const session = this.store?.getWorkspaceSession?.() if (!session || !this.store?.setWorkspaceSession) { return } const orderIndexByTabId = new Map(tabOrder.map((tabId, index) => [tabId, index])) const tabs = session.tabsByWorktree[worktreeId] ?? [] const reordered = [...tabs] .sort((a, b) => { const aIndex = orderIndexByTabId.get(a.id) ?? Number.MAX_SAFE_INTEGER const bIndex = orderIndexByTabId.get(b.id) ?? Number.MAX_SAFE_INTEGER return aIndex - bIndex || a.sortOrder - b.sortOrder || a.createdAt - b.createdAt }) .map((tab, index) => ({ ...tab, sortOrder: index })) this.store.setWorkspaceSession({ ...session, tabsByWorktree: { ...session.tabsByWorktree, [worktreeId]: reordered } }) } private emitMobileSessionTabsSnapshot(snapshot: RuntimeMobileSessionTabsSnapshot): void { if (this.mobileSessionTabListeners.size === 0) { return } const result = this.toMobileSessionTabsResult(snapshot) for (const listener of this.mobileSessionTabListeners) { listener(result) } } private async refreshMobileSessionPtyRecords(): Promise { if (!this.ptyController?.listProcesses) { return } const resolvedWorktrees = await this.listResolvedWorktrees() await this.refreshPtyWorktreeRecordsFromController(resolvedWorktrees) } async activateMobileSessionTab( worktreeSelector: string, tabId: string, leafId?: string, opts: { notifyClients?: boolean } = {} ): Promise { const explicitWorktreeId = getExplicitWorktreeIdSelector(worktreeSelector) const worktreeId = explicitWorktreeId ?? (await this.resolveWorktreeSelector(worktreeSelector)).id this.hydrateHeadlessMobileSessionTabsFromWorkspaceSession(worktreeId) await this.refreshMobileSessionPtyRecords() const snapshot = this.mobileSessionTabsByWorktree.get(worktreeId) const directTab = snapshot?.tabs.find((candidate) => candidate.id === tabId) const tab = leafId ? ((directTab?.type === 'terminal' && directTab.leafId === leafId ? directTab : undefined) ?? snapshot?.tabs.find( (candidate) => candidate.type === 'terminal' && candidate.parentTabId === tabId && candidate.leafId === leafId )) : (directTab ?? snapshot?.tabs.find( (candidate) => candidate.type === 'terminal' && candidate.parentTabId === tabId ) ?? snapshot?.tabs.find( (candidate) => candidate.type === 'browser' && candidate.browserWorkspaceId === tabId )) if (!tab) { throw new Error('tab_not_found') } if (tab.type === 'terminal') { const publicTab = this.toMobileSessionTabsResult(snapshot!).tabs.find( (candidate) => candidate.type === 'terminal' && candidate.id === tab.id ) // Why: serve-created tabs can be visible before any renderer has adopted // their tab id, so focusing the renderer would silently no-op. // Phone-local activation also needs this path for inactive restored tabs: // desktop focus is intentionally suppressed, but the PTY still must exist. const shouldMaterializePendingTerminal = publicTab?.type === 'terminal' && publicTab.status !== 'ready' && (opts.notifyClients === false || !this.notifier?.focusTerminal || this.shouldMaterializeHeadlessMobileSessionTab(snapshot!, tab)) if (shouldMaterializePendingTerminal) { const sessionId = tab.ptyId ?? tab.parentLayout?.ptyIdsByLeafId?.[tab.leafId] ?? undefined const targetGroupId = snapshot?.tabGroups?.find((group) => group.tabOrder.includes(tab.parentTabId) )?.id try { await this.createHeadlessMobileSessionTerminal( worktreeId, true, undefined, undefined, undefined, undefined, { tabId: tab.parentTabId, leafId: tab.leafId, sessionId }, tab.launchAgent, targetGroupId ) } catch (err) { if (sessionId && parseAppSshPtyId(sessionId)) { // Why: an expired SSH reattach clears durable bindings in the store, // but this in-memory headless snapshot can still carry the old id. this.hydrateHeadlessMobileSessionTabsFromWorkspaceSession(worktreeId, { force: true }) } throw err } return this.getMobileSessionTabsForWorktree(worktreeId) } const activeSibling = tab.id === tabId || leafId ? null : snapshot?.tabs.find( (candidate): candidate is RuntimeMobileSessionTerminalTab => candidate.type === 'terminal' && candidate.parentTabId === tab.parentTabId && candidate.isActive ) const targetTab = activeSibling ?? tab if (opts.notifyClients === false) { this.activateMobileSessionTabForRemoteClient(worktreeId, snapshot!, targetTab) return this.getMobileSessionTabsForWorktree(worktreeId) } if (!this.notifier?.focusTerminal) { if ( !targetTab.isActive && this.shouldPersistHeadlessMobileSessionActivation(snapshot!, targetTab) ) { this.activateHeadlessMobileSessionTerminalTab(worktreeId, snapshot!, targetTab) } return this.getMobileSessionTabsForWorktree(worktreeId) } this.notifier?.focusTerminal(targetTab.parentTabId, worktreeId, targetTab.leafId) } else if (tab.type === 'browser') { if (opts.notifyClients === false) { this.activateMobileSessionTabForRemoteClient(worktreeId, snapshot!, tab) return this.getMobileSessionTabsForWorktree(worktreeId) } // Why: browser mobile tabs are renderer-owned unified tabs; focusing the // session tab keeps desktop tab order/group state authoritative. this.notifier?.focusEditorTab?.(tab.id, worktreeId) } else { if (opts.notifyClients === false) { this.activateMobileSessionTabForRemoteClient(worktreeId, snapshot!, tab) return this.getMobileSessionTabsForWorktree(worktreeId) } this.notifier?.focusEditorTab?.(tab.id, worktreeId) } return this.getMobileSessionTabsForWorktree(worktreeId) } private activateMobileSessionTabForRemoteClient( worktreeId: string, snapshot: RuntimeMobileSessionTabsSnapshot, activeTab: RuntimeMobileSessionSnapshotTab ): void { // Why: phone tab selection should update the mobile snapshot without // asking desktop renderers to focus the phone's background worktree. const activeTopLevelId = activeTab.type === 'terminal' ? activeTab.parentTabId : activeTab.id const tabs = snapshot.tabs.map((tab) => ({ ...tab, isActive: tab.id === activeTab.id })) const tabGroups = snapshot.tabGroups?.map((group) => group.tabOrder.includes(activeTopLevelId) ? { ...group, activeTabId: activeTopLevelId } : group ) const activeGroupId = tabGroups?.find((group) => group.tabOrder.includes(activeTopLevelId))?.id ?? snapshot.activeGroupId const nextSnapshot: RuntimeMobileSessionTabsSnapshot = { ...snapshot, publicationEpoch: `mobile-local:${Date.now().toString(36)}`, snapshotVersion: snapshot.snapshotVersion + 1, activeGroupId, activeTabId: activeTab.id, activeTabType: activeTab.type, ...(tabGroups ? { tabGroups } : {}), tabs } this.mobileSessionTabsByWorktree.set(worktreeId, nextSnapshot) this.emitMobileSessionTabsSnapshot(nextSnapshot) } private shouldMaterializeHeadlessMobileSessionTab( snapshot: RuntimeMobileSessionTabsSnapshot, tab: RuntimeMobileSessionTerminalTab ): boolean { return ( this.isHeadlessMobileSessionPublication(snapshot.publicationEpoch) || this.hasServeOwnedPtyBinding(tab) ) } private shouldPersistHeadlessMobileSessionActivation( snapshot: RuntimeMobileSessionTabsSnapshot, tab: RuntimeMobileSessionTerminalTab ): boolean { if (snapshot.publicationEpoch.includes(':headless-merge:')) { return false } if (this.authoritativeWindowId !== null && this.graphStatus === 'ready') { return false } return this.shouldMaterializeHeadlessMobileSessionTab(snapshot, tab) } private activateHeadlessMobileSessionTerminalTab( worktreeId: string, snapshot: RuntimeMobileSessionTabsSnapshot, activeTab: RuntimeMobileSessionTerminalTab ): void { const tabs = snapshot.tabs.map((candidate) => ({ ...candidate, isActive: candidate.id === activeTab.id })) const nextSnapshot: RuntimeMobileSessionTabsSnapshot = { ...snapshot, publicationEpoch: `headless:${Date.now().toString(36)}`, snapshotVersion: snapshot.snapshotVersion + 1, activeTabId: activeTab.id, activeTabType: 'terminal', tabGroups: this.buildHeadlessMobileSessionTabGroups( worktreeId, tabs, activeTab, snapshot.tabGroups ), tabs } this.persistHeadlessTerminalActiveLeaf(worktreeId, activeTab) this.mobileSessionTabsByWorktree.set(worktreeId, nextSnapshot) this.emitMobileSessionTabsSnapshot(nextSnapshot) } // Why: a headless split only updated the LIVE session snapshot, never the // persisted workspace session layout. So a later snapshot rebuild (e.g. on the // next terminal create) re-derived from the stale single-leaf persisted layout // and collapsed the split. Persist the new split leaf into the workspace // session's terminalLayoutsByTabId so the split survives rebuilds. private persistHeadlessTerminalSplit(args: { tabId: string leafId: string ptyId: string splitFromLeafId: string direction: 'horizontal' | 'vertical' }): void { const session = this.store?.getWorkspaceSession?.() if (!session || !this.store?.setWorkspaceSession) { return } const existing = session.terminalLayoutsByTabId?.[args.tabId] const nextLayout = buildHeadlessTerminalSplitLayout( existing ? this.cloneTerminalLayoutSnapshot(existing) : undefined, args ) this.store.setWorkspaceSession({ ...session, terminalLayoutsByTabId: { ...session.terminalLayoutsByTabId, [args.tabId]: nextLayout } }) } private persistHeadlessTerminalActiveLeaf( worktreeId: string, tab: RuntimeMobileSessionTerminalTab ): void { const session = this.store?.getWorkspaceSession?.() if (!session || !this.store?.setWorkspaceSession) { return } const existingLayout = session.terminalLayoutsByTabId?.[tab.parentTabId] const nextLayouts = existingLayout ? { ...session.terminalLayoutsByTabId, [tab.parentTabId]: { ...this.cloneTerminalLayoutSnapshot(existingLayout), activeLeafId: tab.leafId } } : session.terminalLayoutsByTabId this.store.setWorkspaceSession({ ...session, activeTabId: tab.parentTabId, activeTabIdByWorktree: { ...session.activeTabIdByWorktree, [worktreeId]: tab.parentTabId }, terminalLayoutsByTabId: nextLayouts }) } async closeMobileSessionTab(worktreeSelector: string, tabId: string): Promise<{ closed: true }> { const explicitWorktreeId = getExplicitWorktreeIdSelector(worktreeSelector) const worktreeId = explicitWorktreeId ?? (await this.resolveWorktreeSelector(worktreeSelector)).id this.hydrateHeadlessMobileSessionTabsFromWorkspaceSession(worktreeId) await this.refreshMobileSessionPtyRecords() const snapshot = this.mobileSessionTabsByWorktree.get(worktreeId) const tab = snapshot?.tabs.find((candidate) => candidate.id === tabId) ?? snapshot?.tabs.find( (candidate) => candidate.type === 'terminal' && candidate.parentTabId === tabId ) ?? snapshot?.tabs.find( (candidate) => candidate.type === 'browser' && candidate.browserWorkspaceId === tabId ) if (!tab) { throw new Error('tab_not_found') } if (tab.type === 'terminal') { if (!this.notifier?.closeTerminal) { this.closeHeadlessMobileTerminalTab(worktreeId, snapshot!, tab) return { closed: true } } // Why: a runtime-owned headless tab whose whole parent is being closed must // be torn down authoritatively even with a renderer attached — kill the // PTY, drop the persisted binding, and prune+emit — or syncMobileSessionTabs // keeps republishing the "closed" tab with a live PTY. Best-effort notify the // renderer too so any adopted pane closes (no dead pane). A single split leaf // (exact id, multi-leaf parent) keeps the per-leaf path so siblings survive. const parentLeafCount = snapshot!.tabs.filter( (candidate) => candidate.type === 'terminal' && candidate.parentTabId === tab.parentTabId ).length const closingWholeParent = tab.id !== tabId || parentLeafCount <= 1 if (closingWholeParent && this.isRuntimeOwnedHeadlessMobileTab(worktreeId, tab)) { this.closeHeadlessMobileTerminalTab(worktreeId, snapshot!, tab) this.notifier?.closeTerminal(tab.parentTabId) return { closed: true } } if (tab.id === tabId) { const pty = this.findPtyForMobileTerminalTab(worktreeId, tab) if (pty) { this.ptyController?.kill(pty.ptyId) } else { this.notifier?.closeTerminal(tab.parentTabId) } } else { // Why: paired web tab bars represent a split terminal with one local // parent tab id. Closing that parent should close the desktop tab, not // just whichever leaf happened to be first in the session snapshot. this.notifier?.closeTerminal(tab.parentTabId) } } else if (tab.type === 'browser' && this.offscreenBrowserBackend) { // Why: headless browser tabs are offscreen WebContents with no renderer to // route closeSessionTab to. Close the page directly and drop it from the // snapshot so paired clients stop showing it. await this.closeHeadlessMobileBrowserTab(worktreeId, snapshot!, tab) } else { this.notifier?.closeSessionTab?.(tab.id, worktreeId) } return { closed: true } } private async closeHeadlessMobileBrowserTab( worktreeId: string, snapshot: RuntimeMobileSessionTabsSnapshot, tab: RuntimeMobileSessionBrowserTab ): Promise { if (tab.browserPageId) { await this.offscreenBrowserBackend?.closeTab(tab.browserPageId).catch(() => {}) } const nextTabs = snapshot.tabs.filter((candidate) => candidate.id !== tab.id) const active = nextTabs.find((candidate) => candidate.isActive) ?? nextTabs[0] ?? null const nextSnapshot: RuntimeMobileSessionTabsSnapshot = { ...snapshot, publicationEpoch: `headless:${Date.now().toString(36)}`, snapshotVersion: snapshot.snapshotVersion + 1, activeTabId: active?.id ?? null, activeTabType: active?.type ?? null, tabGroups: (snapshot.tabGroups ?? []).map((group) => ({ ...group, tabOrder: group.tabOrder.filter((id) => id !== tab.id), activeTabId: group.activeTabId === tab.id ? null : group.activeTabId })), tabs: nextTabs } this.mobileSessionTabsByWorktree.set(worktreeId, nextSnapshot) this.emitMobileSessionTabsSnapshot(nextSnapshot) } private markHeadlessBrowserSessionTabActive( worktreeId: string | undefined, browserPageId: string, targetGroupId?: string ): void { if (!this.offscreenBrowserBackend || !worktreeId) { return } // Hydrate first so the freshly created browser tab is present in the snapshot. this.hydrateHeadlessMobileSessionTabsFromWorkspaceSession(worktreeId) const snapshot = this.mobileSessionTabsByWorktree.get(worktreeId) const tab = snapshot?.tabs.find( (candidate): candidate is RuntimeMobileSessionBrowserTab => candidate.type === 'browser' && candidate.browserPageId === browserPageId ) if (!snapshot || !tab) { return } const groups = snapshot.tabGroups ?? [] const hasTargetGroup = targetGroupId !== undefined && groups.some((group) => group.id === targetGroupId) // Why: move the new browser into the group whose "+" was clicked, removing it // from wherever the rebuild placed it. Only the TARGET group's activeTabId // (and the global active) change — every other group's active tab is left // intact, so creating in the right group never resets the left group's tab. const nextGroups = hasTargetGroup ? groups.map((group) => { const withoutTab = group.tabOrder.filter((id) => id !== tab.id) if (group.id === targetGroupId) { return { ...group, tabOrder: [...withoutTab, tab.id], activeTabId: tab.id } } return withoutTab.length === group.tabOrder.length ? group : { ...group, tabOrder: withoutTab } }) : groups.map((group) => group.tabOrder.includes(tab.id) ? { ...group, activeTabId: tab.id } : group ) const nextSnapshot: RuntimeMobileSessionTabsSnapshot = { ...snapshot, publicationEpoch: `headless:${Date.now().toString(36)}`, snapshotVersion: snapshot.snapshotVersion + 1, ...(hasTargetGroup ? { activeGroupId: targetGroupId } : {}), activeTabId: tab.id, activeTabType: 'browser', tabs: snapshot.tabs.map((candidate) => ({ ...candidate, isActive: candidate.id === tab.id })), tabGroups: nextGroups } this.mobileSessionTabsByWorktree.set(worktreeId, nextSnapshot) // Why: browser group membership is otherwise live-only; persist it so a // later rebuild keeps the browser in its group instead of coalescing left. if (hasTargetGroup && nextSnapshot.tabGroupLayout) { this.persistHeadlessTabGroups(worktreeId, nextGroups, nextSnapshot.tabGroupLayout) } this.emitMobileSessionTabsSnapshot(nextSnapshot) } private closeHeadlessMobileTerminalTab( worktreeId: string, snapshot: RuntimeMobileSessionTabsSnapshot, tab: RuntimeMobileSessionTerminalTab ): void { const closedParentTabId = tab.parentTabId const nextTabs = snapshot.tabs.filter((candidate) => { if (candidate.type !== 'terminal' || candidate.parentTabId !== closedParentTabId) { return true } const pty = this.findPtyForMobileTerminalTab(worktreeId, candidate) if (pty?.connected) { this.ptyController?.kill(pty.ptyId) } else { const persistedSshPtyId = this.getPersistedSshPtyIdForMobileTerminalTab(candidate) if (persistedSshPtyId) { // Why: close is an explicit deletion. Hydrated SSH PTYs can be known // only by durable id before reconnect repopulates pane metadata. this.ptyController?.kill(persistedSshPtyId) } } return false }) this.removePersistedHeadlessTerminalTab(worktreeId, closedParentTabId) const active = nextTabs.find((candidate) => candidate.isActive) ?? nextTabs[0] ?? null const nextSnapshot: RuntimeMobileSessionTabsSnapshot = { ...snapshot, publicationEpoch: `headless:${Date.now().toString(36)}`, snapshotVersion: snapshot.snapshotVersion + 1, activeTabId: active?.id ?? null, activeTabType: active?.type ?? null, tabGroups: this.buildHeadlessMobileSessionTabGroups( worktreeId, nextTabs, active, snapshot.tabGroups ), tabs: nextTabs } this.mobileSessionTabsByWorktree.set(worktreeId, nextSnapshot) this.emitMobileSessionTabsSnapshot(nextSnapshot) } async moveMobileSessionTab( worktreeSelector: string, move: RuntimeMobileSessionTabMove ): Promise { const explicitWorktreeId = getExplicitWorktreeIdSelector(worktreeSelector) const worktreeId = explicitWorktreeId ?? (await this.resolveWorktreeSelector(worktreeSelector)).id this.hydrateHeadlessMobileSessionTabsFromWorkspaceSession(worktreeId) const snapshot = this.mobileSessionTabsByWorktree.get(worktreeId) if (!snapshot) { throw new Error('tab_not_found') } if (!this.notifier?.moveSessionTab) { return this.moveHeadlessMobileSessionTab(worktreeId, snapshot, move) } const hostTabId = this.resolveMobileSessionHostTabId(snapshot, move.tabId) if (!hostTabId) { throw new Error('tab_not_found') } const publicSnapshot = this.toMobileSessionTabsResult(snapshot) const targetGroup = publicSnapshot.tabGroups?.find((group) => group.id === move.targetGroupId) if (!targetGroup) { throw new Error('target_group_not_found') } // Why: web clients address terminal surfaces as tab::leaf, while desktop // tab grouping is owned by the outer terminal tab id. if (move.kind === 'reorder') { const tabOrder = this.normalizeMobileSessionTabOrder(snapshot, targetGroup, move.tabOrder) if (!tabOrder.includes(hostTabId)) { throw new Error('invalid_tab_order') } this.notifier.moveSessionTab(worktreeId, { ...move, tabId: hostTabId, tabOrder }) return { moved: true } } this.notifier.moveSessionTab(worktreeId, { ...move, tabId: hostTabId }) return { moved: true } } // Why: pane geometry inside a tab (split ratios, expanded pane, pane titles) // is host-authoritative for remote-server tabs but had no push path, so a // client divider-drag / expand / pane-rename reverted on the next snapshot. // Persist the structural fields onto the tab's layout, keeping host-owned // pty bindings and active leaf. async updateMobileSessionPaneLayout( worktreeSelector: string, args: { tabId: string root: TerminalPaneLayoutNode | null expandedLeafId: string | null titlesByLeafId?: Record } ): Promise<{ updated: true }> { const explicitWorktreeId = getExplicitWorktreeIdSelector(worktreeSelector) const worktreeId = explicitWorktreeId ?? (await this.resolveWorktreeSelector(worktreeSelector)).id // Why: when a renderer is authoritative (desktop host reached via shared // control), it owns pane geometry and republishes it — a headless write here // would be overwritten and could fight the renderer. Persist only headlessly. if (this.getAvailableAuthoritativeWindow()) { return { updated: true } } // Why: resolve to the host tab id (older/raw-id clients) so the persisted // layout entry matches, matching setMobileSessionTabProps. const snapshot = this.mobileSessionTabsByWorktree.get(worktreeId) const hostTabId = snapshot ? (this.resolveMobileSessionHostTabId(snapshot, args.tabId) ?? args.tabId) : args.tabId const resolvedArgs = { ...args, tabId: hostTabId } this.persistHeadlessTerminalPaneLayout(resolvedArgs) this.applyHeadlessTerminalPaneLayoutToSnapshot(worktreeId, resolvedArgs) return { updated: true } } // Why: tab color/pin are host-authoritative for remote-server tabs but had no // push path, so pinning or coloring a tab reverted on the next snapshot and // was never persisted. Persist to the workspace session + live snapshot. async setMobileSessionTabProps( worktreeSelector: string, args: { tabId: string color?: string | null isPinned?: boolean viewMode?: 'terminal' | 'chat' } ): Promise<{ updated: true }> { const explicitWorktreeId = getExplicitWorktreeIdSelector(worktreeSelector) const worktreeId = explicitWorktreeId ?? (await this.resolveWorktreeSelector(worktreeSelector)).id // Why: a renderer-authoritative host owns + republishes tab props, so a // headless write would be overwritten. Persist only when headless. if (this.getAvailableAuthoritativeWindow()) { return { updated: true } } const snapshot = this.mobileSessionTabsByWorktree.get(worktreeId) const hostTabId = snapshot ? (this.resolveMobileSessionHostTabId(snapshot, args.tabId) ?? args.tabId) : args.tabId this.persistHeadlessSessionTabProps(worktreeId, hostTabId, args) this.applyHeadlessSessionTabPropsToSnapshot(worktreeId, hostTabId, args) return { updated: true } } private persistHeadlessSessionTabProps( worktreeId: string, tabId: string, props: { color?: string | null; isPinned?: boolean; viewMode?: 'terminal' | 'chat' } ): void { const session = this.store?.getWorkspaceSession?.() if (!session || !this.store?.setWorkspaceSession) { return } const tabs = session.tabsByWorktree[worktreeId] const nextSession: WorkspaceSessionState = { ...session } let changed = false if (tabs?.some((tab) => tab.id === tabId)) { changed = true nextSession.tabsByWorktree = { ...session.tabsByWorktree, [worktreeId]: tabs.map((tab) => tab.id === tabId ? { ...tab, ...(props.color !== undefined ? { color: props.color } : {}), ...(props.isPinned !== undefined ? { isPinned: props.isPinned } : {}), ...(props.viewMode !== undefined ? { viewMode: props.viewMode } : {}) } : tab ) } } const unifiedTabs = session.unifiedTabs?.[worktreeId] if (unifiedTabs?.some((tab) => tab.id === tabId || tab.entityId === tabId)) { changed = true nextSession.unifiedTabs = { ...session.unifiedTabs, [worktreeId]: unifiedTabs.map((tab) => tab.id === tabId || tab.entityId === tabId ? { ...tab, ...(props.color !== undefined ? { color: props.color } : {}), ...(props.isPinned !== undefined ? { isPinned: props.isPinned } : {}) } : tab ) } } if (!changed) { return } this.store.setWorkspaceSession(nextSession) } private applyHeadlessSessionTabPropsToSnapshot( worktreeId: string, tabId: string, props: { color?: string | null; isPinned?: boolean; viewMode?: 'terminal' | 'chat' } ): void { const snapshot = this.mobileSessionTabsByWorktree.get(worktreeId) if (!snapshot) { return } let changed = false const tabs = snapshot.tabs.map((tab) => { if (this.getMobileSessionTopLevelTabId(tab) !== tabId) { return tab } changed = true return { ...tab, ...(props.color !== undefined ? { color: props.color } : {}), ...(props.isPinned !== undefined ? { isPinned: props.isPinned } : {}), ...(props.viewMode !== undefined ? { viewMode: props.viewMode } : {}) } }) if (!changed) { return } const nextSnapshot: RuntimeMobileSessionTabsSnapshot = { ...snapshot, publicationEpoch: `headless:${Date.now().toString(36)}`, snapshotVersion: snapshot.snapshotVersion + 1, tabs } this.mobileSessionTabsByWorktree.set(worktreeId, nextSnapshot) this.emitMobileSessionTabsSnapshot(nextSnapshot) } private getMobileSessionTopLevelTabId(tab: RuntimeMobileSessionSnapshotTab): string { return tab.type === 'terminal' ? tab.parentTabId : tab.id } // Merge the client's pane structure into the persisted tab layout. PTY // bindings and active leaf stay host-owned; only ratios/expand/titles change. // terminalLayoutsByTabId is keyed by tab id (worktree-independent). private persistHeadlessTerminalPaneLayout(args: { tabId: string root: TerminalPaneLayoutNode | null expandedLeafId: string | null titlesByLeafId?: Record }): void { const session = this.store?.getWorkspaceSession?.() if (!session || !this.store?.setWorkspaceSession) { return } const existing = session.terminalLayoutsByTabId?.[args.tabId] if (!existing) { return } this.store.setWorkspaceSession({ ...session, terminalLayoutsByTabId: { ...session.terminalLayoutsByTabId, [args.tabId]: { ...this.cloneTerminalLayoutSnapshot(existing), root: args.root ?? existing.root, expandedLeafId: args.expandedLeafId, ...(args.titlesByLeafId ? { titlesByLeafId: args.titlesByLeafId } : {}) } } }) } private applyHeadlessTerminalPaneLayoutToSnapshot( worktreeId: string, args: { tabId: string root: TerminalPaneLayoutNode | null expandedLeafId: string | null titlesByLeafId?: Record } ): void { const snapshot = this.mobileSessionTabsByWorktree.get(worktreeId) if (!snapshot) { return } let changed = false const tabs = snapshot.tabs.map((tab) => { if (tab.type !== 'terminal' || tab.parentTabId !== args.tabId || !tab.parentLayout) { return tab } changed = true return { ...tab, parentLayout: { ...tab.parentLayout, root: args.root ?? tab.parentLayout.root, expandedLeafId: args.expandedLeafId, ...(args.titlesByLeafId ? { titlesByLeafId: args.titlesByLeafId } : {}) } } }) if (!changed) { return } const nextSnapshot: RuntimeMobileSessionTabsSnapshot = { ...snapshot, publicationEpoch: `headless:${Date.now().toString(36)}`, snapshotVersion: snapshot.snapshotVersion + 1, tabs } this.mobileSessionTabsByWorktree.set(worktreeId, nextSnapshot) this.emitMobileSessionTabsSnapshot(nextSnapshot) } private moveHeadlessMobileSessionTab( worktreeId: string, snapshot: RuntimeMobileSessionTabsSnapshot, move: RuntimeMobileSessionTabMove ): RuntimeMobileSessionTabMoveResult { if (move.kind === 'split') { return this.splitHeadlessMobileSessionTabGroup(worktreeId, snapshot, move) } if (move.kind === 'move-to-group') { return this.moveHeadlessMobileSessionTabToGroup(worktreeId, snapshot, move) } if (move.kind !== 'reorder') { throw new Error('renderer_unavailable') } const hostTabId = this.resolveMobileSessionHostTabId(snapshot, move.tabId) if (!hostTabId) { throw new Error('tab_not_found') } const publicSnapshot = this.toMobileSessionTabsResult(snapshot) const targetGroup = publicSnapshot.tabGroups?.find((group) => group.id === move.targetGroupId) if (!targetGroup) { throw new Error('target_group_not_found') } const tabOrder = this.normalizeMobileSessionTabOrder(snapshot, targetGroup, move.tabOrder) const orderIndexByParentTabId = new Map(tabOrder.map((tabId, index) => [tabId, index])) const nextTabs = [...snapshot.tabs].sort((a, b) => { const aParent = a.type === 'terminal' ? a.parentTabId : a.id const bParent = b.type === 'terminal' ? b.parentTabId : b.id const aIndex = orderIndexByParentTabId.get(aParent) ?? Number.MAX_SAFE_INTEGER const bIndex = orderIndexByParentTabId.get(bParent) ?? Number.MAX_SAFE_INTEGER return aIndex - bIndex }) const active = nextTabs.find((candidate) => candidate.isActive) ?? nextTabs[0] ?? null const reorderedTargetActiveTabId = active?.type === 'terminal' ? active.parentTabId : active ? active.id : (tabOrder[0] ?? null) // Why: reorder only changes ONE group's order. Preserve every other group so // a multi-group split isn't deleted by re-sorting tabs in one of its groups. const existingGroups = snapshot.tabGroups ?? [] const nextGroups = existingGroups.some((group) => group.id === targetGroup.id) ? existingGroups.map((group) => group.id === targetGroup.id ? { ...group, tabOrder, activeTabId: reorderedTargetActiveTabId } : group ) : [{ ...targetGroup, tabOrder, activeTabId: reorderedTargetActiveTabId }] const nextSnapshot: RuntimeMobileSessionTabsSnapshot = { ...snapshot, publicationEpoch: `headless:${Date.now().toString(36)}`, snapshotVersion: snapshot.snapshotVersion + 1, activeTabId: active?.id ?? null, activeTabType: active?.type ?? null, tabGroups: nextGroups, tabs: nextTabs } this.persistHeadlessTerminalTabOrder(worktreeId, tabOrder) if (nextGroups.length > 1 && snapshot.tabGroupLayout) { this.persistHeadlessTabGroups(worktreeId, nextGroups, snapshot.tabGroupLayout) } this.mobileSessionTabsByWorktree.set(worktreeId, nextSnapshot) this.emitMobileSessionTabsSnapshot(nextSnapshot) return { moved: true } } // Why: a drag-to-split-group used to be a client-only change the headless host // never modeled, so the next snapshot coalesced every tab back into one group. // Model + persist the multi-group layout so the split survives rebuilds. private splitHeadlessMobileSessionTabGroup( worktreeId: string, snapshot: RuntimeMobileSessionTabsSnapshot, move: Extract ): RuntimeMobileSessionTabMoveResult { const hostTabId = this.resolveMobileSessionHostTabId(snapshot, move.tabId) if (!hostTabId) { throw new Error('tab_not_found') } const split = buildHeadlessTabGroupSplit({ groups: snapshot.tabGroups ?? [], layout: snapshot.tabGroupLayout, tabId: hostTabId, targetGroupId: move.targetGroupId, splitDirection: move.splitDirection, newGroupId: randomUUID() }) if (!split) { // Renderer treats an unsplittable drop (e.g. last tab onto its own group) // as a no-op; mirror that instead of churning the snapshot. return { moved: true } } const nextSnapshot: RuntimeMobileSessionTabsSnapshot = { ...snapshot, publicationEpoch: `headless:${Date.now().toString(36)}`, snapshotVersion: snapshot.snapshotVersion + 1, activeGroupId: split.newGroupId, tabGroups: split.groups, tabGroupLayout: split.layout } this.persistHeadlessTabGroups(worktreeId, split.groups, split.layout) this.mobileSessionTabsByWorktree.set(worktreeId, nextSnapshot) this.emitMobileSessionTabsSnapshot(nextSnapshot) return { moved: true } } // Move a tab into an existing group on a headless serve (non-split drop). private moveHeadlessMobileSessionTabToGroup( worktreeId: string, snapshot: RuntimeMobileSessionTabsSnapshot, move: Extract ): RuntimeMobileSessionTabMoveResult { const hostTabId = this.resolveMobileSessionHostTabId(snapshot, move.tabId) if (!hostTabId) { throw new Error('tab_not_found') } const moved = buildHeadlessTabGroupMove({ groups: snapshot.tabGroups ?? [], layout: snapshot.tabGroupLayout, tabId: hostTabId, targetGroupId: move.targetGroupId, index: move.index }) if (!moved) { // Same-group / missing-target drop is a renderer no-op; mirror that. return { moved: true } } const layout = moved.layout ?? { type: 'leaf' as const, groupId: move.targetGroupId } const nextSnapshot: RuntimeMobileSessionTabsSnapshot = { ...snapshot, publicationEpoch: `headless:${Date.now().toString(36)}`, snapshotVersion: snapshot.snapshotVersion + 1, activeGroupId: move.targetGroupId, tabGroups: moved.groups, tabGroupLayout: layout } this.persistHeadlessTabGroups(worktreeId, moved.groups, layout) this.mobileSessionTabsByWorktree.set(worktreeId, nextSnapshot) this.emitMobileSessionTabsSnapshot(nextSnapshot) return { moved: true } } // Persist the headless tab-GROUP layout so snapshot rebuilds keep the split. private persistHeadlessTabGroups( worktreeId: string, groups: readonly RuntimeMobileSessionTabGroup[], layout: TabGroupLayoutNode ): void { const session = this.store?.getWorkspaceSession?.() if (!session || !this.store?.setWorkspaceSession) { return } this.store.setWorkspaceSession({ ...session, tabGroups: { ...session.tabGroups, [worktreeId]: groups.map((group) => ({ id: group.id, worktreeId, activeTabId: group.activeTabId, tabOrder: [...group.tabOrder], ...(group.recentTabIds ? { recentTabIds: [...group.recentTabIds] } : {}) })) }, tabGroupLayouts: { ...session.tabGroupLayouts, [worktreeId]: layout } }) } // Persist a manual terminal rename so a headless rebuild keeps the title // instead of reverting to the generated/default one. private persistHeadlessTerminalTitle( worktreeId: string, tabId: string, title: string | null ): void { const session = this.store?.getWorkspaceSession?.() if (!session || !this.store?.setWorkspaceSession) { return } const tabs = session.tabsByWorktree[worktreeId] if (!tabs?.some((tab) => tab.id === tabId)) { return } this.store.setWorkspaceSession({ ...session, tabsByWorktree: { ...session.tabsByWorktree, [worktreeId]: tabs.map((tab) => (tab.id === tabId ? { ...tab, customTitle: title } : tab)) } }) } private normalizeMobileSessionTabOrder( snapshot: RuntimeMobileSessionTabsSnapshot | undefined, targetGroup: RuntimeMobileSessionTabGroup, tabOrder: readonly string[] ): string[] { const normalized: string[] = [] const seen = new Set() for (const tabId of tabOrder) { const hostTabId = this.resolveMobileSessionHostTabId(snapshot, tabId) if (!hostTabId) { throw new Error('invalid_tab_order') } if (seen.has(hostTabId)) { throw new Error('duplicate_tab_order') } seen.add(hostTabId) normalized.push(hostTabId) } const returnedIds = this.collectPublicMobileSessionTabIds(snapshot) const expected = targetGroup.tabOrder .map((tabId) => this.resolveMobileSessionHostTabId(snapshot, tabId) ?? tabId) // Why: clients reorder the sanitized session.tabs.list model; raw groups // can still contain stale browser ids hidden from paired web clients. .filter((tabId) => returnedIds.has(tabId)) // Why: reorder is a pure permutation of one existing group. Missing or // extra ids would let a paired web client silently move/lose host tabs. if (normalized.length !== expected.length || expected.some((tabId) => !seen.has(tabId))) { throw new Error('invalid_tab_order') } return normalized } private collectPublicMobileSessionTabIds( snapshot: RuntimeMobileSessionTabsSnapshot | undefined ): Set { const ids = new Set() if (!snapshot) { return ids } const liveBrowserTabsByPageId = this.getLiveBrowserTabsByPageId(snapshot.worktree) for (const tab of snapshot.tabs) { if (tab.type === 'browser') { const liveTab = tab.browserPageId ? liveBrowserTabsByPageId.get(tab.browserPageId) : undefined if (!liveTab) { continue } ids.add(tab.id) ids.add(tab.browserWorkspaceId) continue } ids.add(tab.id) if (tab.type === 'terminal') { ids.add(tab.parentTabId) } } return ids } private resolveMobileSessionHostTabId( snapshot: RuntimeMobileSessionTabsSnapshot | undefined, tabId: string ): string | null { const tab = snapshot?.tabs.find((candidate) => candidate.id === tabId) ?? snapshot?.tabs.find( (candidate) => candidate.type === 'terminal' && candidate.parentTabId === tabId ) ?? snapshot?.tabs.find( (candidate) => candidate.type === 'browser' && candidate.browserWorkspaceId === tabId ) if (!tab) { return null } return tab.type === 'terminal' ? tab.parentTabId : tab.id } async readMobileMarkdownTab( worktreeSelector: string, tabId: string ): Promise { const worktreeId = await this.resolveMobileMarkdownWorktreeId(worktreeSelector, tabId) if (!this.notifier?.readMobileMarkdownTab) { throw new Error('renderer_unavailable') } return await this.notifier.readMobileMarkdownTab(worktreeId, tabId) } async saveMobileMarkdownTab( worktreeSelector: string, tabId: string, baseVersion: string, content: string ): Promise { const worktreeId = await this.resolveMobileMarkdownWorktreeId(worktreeSelector, tabId) if (!this.notifier?.saveMobileMarkdownTab) { throw new Error('renderer_unavailable') } return await this.notifier.saveMobileMarkdownTab(worktreeId, tabId, baseVersion, content) } private readonly fileCommands = new RuntimeFileCommands({ getRuntimeId: () => this.runtimeId, requireStore: () => this.requireStore(), resolveWorktreeSelector: (selector) => this.resolveWorktreeSelector(selector), resolveRuntimeFileTarget: (selector) => this.resolveRuntimeFileTarget(selector), resolveRuntimeGitTarget: (selector) => this.resolveRuntimeGitTarget(selector), openFile: (worktreeId, filePath, relativePath, runtimeEnvironmentId) => { if (!this.notifier?.openFile) { throw new Error('renderer_unavailable') } this.notifier.openFile(worktreeId, filePath, relativePath, runtimeEnvironmentId) }, openDiff: (worktreeId, filePath, relativePath, staged, runtimeEnvironmentId) => { if (!this.notifier?.openDiff) { throw new Error('renderer_unavailable') } this.notifier.openDiff(worktreeId, filePath, relativePath, staged, runtimeEnvironmentId) } }) listMobileFiles: RuntimeFileCommands['listMobileFiles'] = this.fileCommands.listMobileFiles.bind( this.fileCommands ) openMobileFile: RuntimeFileCommands['openMobileFile'] = this.fileCommands.openMobileFile.bind( this.fileCommands ) openMobileDiff: RuntimeFileCommands['openMobileDiff'] = this.fileCommands.openMobileDiff.bind( this.fileCommands ) readMobileFile: RuntimeFileCommands['readMobileFile'] = this.fileCommands.readMobileFile.bind( this.fileCommands ) resolveTerminalPath: RuntimeFileCommands['resolveTerminalPath'] = this.fileCommands.resolveTerminalPath.bind(this.fileCommands) readFileExplorerDir: RuntimeFileCommands['readFileExplorerDir'] = this.fileCommands.readFileExplorerDir.bind(this.fileCommands) watchFileExplorer: RuntimeFileCommands['watchFileExplorer'] = this.fileCommands.watchFileExplorer.bind(this.fileCommands) readFileExplorerPreview: RuntimeFileCommands['readFileExplorerPreview'] = this.fileCommands.readFileExplorerPreview.bind(this.fileCommands) readFileExplorerChunk: RuntimeFileCommands['readFileExplorerChunk'] = this.fileCommands.readFileExplorerChunk.bind(this.fileCommands) writeFileExplorerFile: RuntimeFileCommands['writeFileExplorerFile'] = this.fileCommands.writeFileExplorerFile.bind(this.fileCommands) writeFileExplorerFileBase64: RuntimeFileCommands['writeFileExplorerFileBase64'] = this.fileCommands.writeFileExplorerFileBase64.bind(this.fileCommands) writeFileExplorerFileBase64Chunk: RuntimeFileCommands['writeFileExplorerFileBase64Chunk'] = this.fileCommands.writeFileExplorerFileBase64Chunk.bind(this.fileCommands) createFileExplorerFile: RuntimeFileCommands['createFileExplorerFile'] = this.fileCommands.createFileExplorerFile.bind(this.fileCommands) createFileExplorerDir: RuntimeFileCommands['createFileExplorerDir'] = this.fileCommands.createFileExplorerDir.bind(this.fileCommands) createFileExplorerDirNoClobber: RuntimeFileCommands['createFileExplorerDirNoClobber'] = this.fileCommands.createFileExplorerDirNoClobber.bind(this.fileCommands) commitFileExplorerUpload: RuntimeFileCommands['commitFileExplorerUpload'] = this.fileCommands.commitFileExplorerUpload.bind(this.fileCommands) renameFileExplorerPath: RuntimeFileCommands['renameFileExplorerPath'] = this.fileCommands.renameFileExplorerPath.bind(this.fileCommands) copyFileExplorerPath: RuntimeFileCommands['copyFileExplorerPath'] = this.fileCommands.copyFileExplorerPath.bind(this.fileCommands) deleteFileExplorerPath: RuntimeFileCommands['deleteFileExplorerPath'] = this.fileCommands.deleteFileExplorerPath.bind(this.fileCommands) searchRuntimeFiles: RuntimeFileCommands['searchRuntimeFiles'] = this.fileCommands.searchRuntimeFiles.bind(this.fileCommands) listRuntimeFiles: RuntimeFileCommands['listRuntimeFiles'] = this.fileCommands.listRuntimeFiles.bind(this.fileCommands) listRuntimeMarkdownDocuments: RuntimeFileCommands['listRuntimeMarkdownDocuments'] = this.fileCommands.listRuntimeMarkdownDocuments.bind(this.fileCommands) statRuntimeFile: RuntimeFileCommands['statRuntimeFile'] = this.fileCommands.statRuntimeFile.bind( this.fileCommands ) private readonly gitCommands = new RuntimeGitCommands({ resolveRuntimeGitTarget: (selector) => this.resolveRuntimeGitTarget(selector), getRuntimeSettings: () => this.requireStore().getSettings() as GlobalSettings, getCommitMessageAgentEnvironment: () => this.commitMessageAgentEnv ?? undefined }) getRuntimeGitStatus: RuntimeGitCommands['getRuntimeGitStatus'] = this.gitCommands.getRuntimeGitStatus.bind(this.gitCommands) getRuntimeGitSubmoduleStatus: RuntimeGitCommands['getRuntimeGitSubmoduleStatus'] = this.gitCommands.getRuntimeGitSubmoduleStatus.bind(this.gitCommands) checkRuntimeGitIgnoredPaths: RuntimeGitCommands['checkRuntimeGitIgnoredPaths'] = this.gitCommands.checkRuntimeGitIgnoredPaths.bind(this.gitCommands) getRuntimeGitHistory: RuntimeGitCommands['getRuntimeGitHistory'] = this.gitCommands.getRuntimeGitHistory.bind(this.gitCommands) getRuntimeGitConflictOperation: RuntimeGitCommands['getRuntimeGitConflictOperation'] = this.gitCommands.getRuntimeGitConflictOperation.bind(this.gitCommands) abortRuntimeGitMerge: RuntimeGitCommands['abortRuntimeGitMerge'] = this.gitCommands.abortRuntimeGitMerge.bind(this.gitCommands) abortRuntimeGitRebase: RuntimeGitCommands['abortRuntimeGitRebase'] = this.gitCommands.abortRuntimeGitRebase.bind(this.gitCommands) checkoutRuntimeGitBranch: RuntimeGitCommands['checkoutRuntimeGitBranch'] = this.gitCommands.checkoutRuntimeGitBranch.bind(this.gitCommands) listRuntimeGitLocalBranches: RuntimeGitCommands['listRuntimeGitLocalBranches'] = this.gitCommands.listRuntimeGitLocalBranches.bind(this.gitCommands) getRuntimeGitDiff: RuntimeGitCommands['getRuntimeGitDiff'] = this.gitCommands.getRuntimeGitDiff.bind(this.gitCommands) getRuntimeGitBranchCompare: RuntimeGitCommands['getRuntimeGitBranchCompare'] = this.gitCommands.getRuntimeGitBranchCompare.bind(this.gitCommands) getRuntimeGitCommitCompare: RuntimeGitCommands['getRuntimeGitCommitCompare'] = this.gitCommands.getRuntimeGitCommitCompare.bind(this.gitCommands) getRuntimeGitUpstreamStatus: RuntimeGitCommands['getRuntimeGitUpstreamStatus'] = this.gitCommands.getRuntimeGitUpstreamStatus.bind(this.gitCommands) fetchRuntimeGit: RuntimeGitCommands['fetchRuntimeGit'] = this.gitCommands.fetchRuntimeGit.bind( this.gitCommands ) syncRuntimeGitForkDefaultBranch: RuntimeGitCommands['syncRuntimeGitForkDefaultBranch'] = this.gitCommands.syncRuntimeGitForkDefaultBranch.bind(this.gitCommands) pullRuntimeGit: RuntimeGitCommands['pullRuntimeGit'] = this.gitCommands.pullRuntimeGit.bind( this.gitCommands ) fastForwardRuntimeGit: RuntimeGitCommands['fastForwardRuntimeGit'] = this.gitCommands.fastForwardRuntimeGit.bind(this.gitCommands) rebaseRuntimeGitFromBase: RuntimeGitCommands['rebaseRuntimeGitFromBase'] = this.gitCommands.rebaseRuntimeGitFromBase.bind(this.gitCommands) pushRuntimeGit: RuntimeGitCommands['pushRuntimeGit'] = this.gitCommands.pushRuntimeGit.bind( this.gitCommands ) getRuntimeGitBranchDiff: RuntimeGitCommands['getRuntimeGitBranchDiff'] = this.gitCommands.getRuntimeGitBranchDiff.bind(this.gitCommands) getRuntimeGitCommitDiff: RuntimeGitCommands['getRuntimeGitCommitDiff'] = this.gitCommands.getRuntimeGitCommitDiff.bind(this.gitCommands) commitRuntimeGit: RuntimeGitCommands['commitRuntimeGit'] = this.gitCommands.commitRuntimeGit.bind( this.gitCommands ) generateRuntimeCommitMessage: RuntimeGitCommands['generateRuntimeCommitMessage'] = this.gitCommands.generateRuntimeCommitMessage.bind(this.gitCommands) discoverRuntimeCommitMessageModels: RuntimeGitCommands['discoverRuntimeCommitMessageModels'] = this.gitCommands.discoverRuntimeCommitMessageModels.bind(this.gitCommands) cancelRuntimeGenerateCommitMessage: RuntimeGitCommands['cancelRuntimeGenerateCommitMessage'] = this.gitCommands.cancelRuntimeGenerateCommitMessage.bind(this.gitCommands) generateRuntimePullRequestFields: RuntimeGitCommands['generateRuntimePullRequestFields'] = this.gitCommands.generateRuntimePullRequestFields.bind(this.gitCommands) cancelRuntimeGeneratePullRequestFields: RuntimeGitCommands['cancelRuntimeGeneratePullRequestFields'] = this.gitCommands.cancelRuntimeGeneratePullRequestFields.bind(this.gitCommands) stageRuntimeGitPath: RuntimeGitCommands['stageRuntimeGitPath'] = this.gitCommands.stageRuntimeGitPath.bind(this.gitCommands) unstageRuntimeGitPath: RuntimeGitCommands['unstageRuntimeGitPath'] = this.gitCommands.unstageRuntimeGitPath.bind(this.gitCommands) bulkStageRuntimeGitPaths: RuntimeGitCommands['bulkStageRuntimeGitPaths'] = this.gitCommands.bulkStageRuntimeGitPaths.bind(this.gitCommands) bulkUnstageRuntimeGitPaths: RuntimeGitCommands['bulkUnstageRuntimeGitPaths'] = this.gitCommands.bulkUnstageRuntimeGitPaths.bind(this.gitCommands) bulkDiscardRuntimeGitPaths: RuntimeGitCommands['bulkDiscardRuntimeGitPaths'] = this.gitCommands.bulkDiscardRuntimeGitPaths.bind(this.gitCommands) discardRuntimeGitPath: RuntimeGitCommands['discardRuntimeGitPath'] = this.gitCommands.discardRuntimeGitPath.bind(this.gitCommands) getRuntimeGitRemoteFileUrl: RuntimeGitCommands['getRuntimeGitRemoteFileUrl'] = this.gitCommands.getRuntimeGitRemoteFileUrl.bind(this.gitCommands) getRuntimeGitRemoteCommitUrl: RuntimeGitCommands['getRuntimeGitRemoteCommitUrl'] = this.gitCommands.getRuntimeGitRemoteCommitUrl.bind(this.gitCommands) private async resolveRuntimeGitTarget(worktreeSelector: string): Promise<{ worktree: ResolvedWorktree repo?: Repo connectionId?: string localGitOptions?: { wslDistro?: string } }> { const store = this.requireStore() const worktree = await this.resolveWorktreeSelector(worktreeSelector) const repo = store.getRepo(worktree.repoId) const connectionId = repo?.connectionId ?? undefined const localGitOptions = repo && !connectionId ? getLocalProjectWorktreeGitOptions(store, repo) : {} return { worktree, repo, connectionId, localGitOptions } } private async resolveRuntimeFileTarget(worktreeSelector: string): Promise<{ worktree: ResolvedWorktree connectionId?: string }> { const folderScope = await this.resolveFolderWorkspaceLaunchScope(worktreeSelector) if (folderScope?.folderWorkspace) { return { worktree: this.folderWorkspaceToResolvedWorktree(folderScope.folderWorkspace), connectionId: folderScope.connectionId ?? undefined } } const store = this.requireStore() const worktree = await this.resolveWorktreeSelector(worktreeSelector) const repo = store.getRepo(worktree.repoId) return { worktree, connectionId: repo?.connectionId ?? undefined } } onMobileSessionTabsChanged( listener: (snapshot: RuntimeMobileSessionTabsResult) => void ): () => void { this.mobileSessionTabListeners.add(listener) return () => { this.mobileSessionTabListeners.delete(listener) } } // Why: terminal handles are normally created lazily when first referenced via // RPC, but agents need their own handle at spawn time (via ORCA_TERMINAL_HANDLE // env var) so they can self-identify in orchestration messages without an // extra RPC round-trip. Pre-allocating by ptyId lets issueHandle reuse it. preAllocateHandleForPty(ptyId: string): string { const existing = this.handleByPtyId.get(ptyId) if (existing) { return existing } const handle = this.createPreAllocatedTerminalHandle() this.handleByPtyId.set(ptyId, handle) return handle } createPreAllocatedTerminalHandle(): string { return `term_${randomUUID()}` } registerPreAllocatedHandleForPty(ptyId: string, handle: string): void { this.handleByPtyId.set(ptyId, handle) for (const leaf of this.getLeavesForPty(ptyId)) { this.adoptPreAllocatedHandle(leaf) } } onPtySpawned(ptyId: string): void { const pty = this.getOrCreatePtyWorktreeRecord(ptyId) if (pty) { pty.connected = true pty.disconnectedAt = null } for (const leaf of this.getLeavesForPty(ptyId)) { leaf.connected = true leaf.writable = this.graphStatus === 'ready' this.adoptPreAllocatedHandle(leaf) } } registerPty(ptyId: string, worktreeId: string, connectionId: string | null = null): void { this.recordPtyWorktree(ptyId, worktreeId, { connected: true, connectionId }) } /** * Handles incoming data from a PTY process, running agent detection, * updating terminal tail buffers, and triggering foreground agent refreshes. */ onPtyData(ptyId: string, data: string, at: number): number { const outputSequence = (this.ptyOutputSequenceById.get(ptyId) ?? 0) + data.length this.ptyOutputSequenceById.set(ptyId, outputSequence) const agentStatusChunk = this.processAgentStatusOscForPty(ptyId, data) this.recentPtyOutputById.set( ptyId, appendRecentPtyOutput(this.recentPtyOutputById.get(ptyId), data) ) // Agent detection runs on raw data before leaf processing, since the // tail buffer logic normalizes away the OSC sequences we need. this.agentDetector?.onData(ptyId, data, at) // Why: watch terminal output for advertised dev-server URLs (e.g. Vite's // `Network: https://local.example.com:3001/`) so the workspace ports // panel can surface them in place of the kernel bind address. advertisedUrlWatcher.ingest(ptyId, data, at) serveSimStateWatcher.ingestPtyOutput(ptyId, data) // Ordering invariant (DO NOT REORDER): maybeHydrateHeadlessFromRenderer // MUST run before trackHeadlessTerminalData so the eager-state pattern // (set headlessTerminals + writeChain head = seedPromise) is in place // before the live byte's chain link is queued. Without this ordering, // trackHeadlessTerminalData would lazy-create a fresh state at PTY dims // that the later seed-resolve would overwrite, dropping the live byte. // See docs/mobile-prefer-renderer-scrollback.md. this.maybeHydrateHeadlessFromRenderer(ptyId) this.trackHeadlessTerminalData(ptyId, data, outputSequence) // Why: extract OSC title from raw PTY data before tail-buffer processing // strips the escape sequences. Agent CLIs (Claude Code, Gemini, etc.) // announce status via OSC 0/1/2 title sequences — this is the same // detection path the renderer uses for notifications and sidebar badges. const oscTitle = this.extractLastOscTitleForPty(ptyId, data) const agentStatus = oscTitle ? detectAgentStatusFromTitle(oscTitle) : null const pty = this.getOrCreatePtyWorktreeRecord(ptyId) let shouldTouchPtyBackedSessionTabs = false const ptyTailBefore = pty ? { lines: pty.tailBuffer, partialLine: pty.tailPartialLine, pendingAnsi: pty.tailPendingAnsi, redrawCursor: pty.tailRedrawCursor, truncated: pty.tailTruncated, linesTotal: pty.tailLinesTotal } : null let ptyTailAfter: ReturnType | null = null if (pty) { pty.connected = true pty.disconnectedAt = null pty.lastOutputAt = at const normalized = normalizeTerminalChunk(data, pty.tailPendingAnsi) pty.tailPendingAnsi = normalized.pendingAnsi const previousWaitText = buildTerminalWaitText( pty.tailBuffer, pty.tailPartialLine, pty.preview ) const nextTail = appendNormalizedToTailBuffer( pty.tailBuffer, pty.tailPartialLine, normalized.text, pty.tailRedrawCursor ) if ( nextTailHasNewerBlockedReason( previousWaitText, buildTerminalWaitText(nextTail.lines, nextTail.partialLine, pty.preview), normalized.text ) ) { pty.waitBlockedAt = at } ptyTailAfter = nextTail pty.tailBuffer = nextTail.lines pty.tailPartialLine = nextTail.partialLine pty.tailRedrawCursor = nextTail.redrawCursor pty.tailTruncated = pty.tailTruncated || nextTail.truncated pty.tailLinesTotal += nextTail.newCompleteLines pty.preview = buildPreview(pty.tailBuffer, pty.tailPartialLine) if (oscTitle !== null) { const prevStatus = pty.lastAgentStatus const prevTitle = pty.lastOscTitle const observedAt = this.nextTitleObservationSequence() pty.lastOscTitle = oscTitle pty.lastOscTitleAt = observedAt pty.lastAgentStatus = agentStatus this.setPtyManagementTitleFromObservedTitle(pty, oscTitle, observedAt) shouldTouchPtyBackedSessionTabs = prevTitle !== oscTitle || prevStatus !== pty.lastAgentStatus if (agentStatus === 'idle' && prevStatus !== 'idle') { this.resolvePtyTuiIdleWaiters(pty, ptyId) } // Why: gate on an actual status transition — braille spinner frames // mutate the title every tick, so probing per-title-change would stream // a foreground query per frame during active work. if (prevStatus !== pty.lastAgentStatus) { this.refreshPtyForegroundAgent(ptyId) } } } for (const leaf of this.getLeavesForPty(ptyId)) { this.recordPtyWorktree(ptyId, leaf.worktreeId, { connected: true, lastOutputAt: pty?.lastOutputAt ?? at, preview: pty?.preview ?? leaf.preview, tabId: leaf.tabId, paneKey: this.makeRuntimePaneKey(leaf) }) leaf.connected = true leaf.writable = this.graphStatus === 'ready' leaf.lastOutputAt = at if ( pty && ptyTailBefore && ptyTailAfter && tailStateMatches( leaf.tailBuffer, leaf.tailPartialLine, leaf.tailPendingAnsi, leaf.tailRedrawCursor, leaf.tailTruncated, leaf.tailLinesTotal, ptyTailBefore ) ) { // Why: the leaf and PTY record usually mirror the same terminal. Reuse // the PTY tail update instead of splitting large output twice. leaf.tailBuffer = pty.tailBuffer leaf.tailPartialLine = pty.tailPartialLine leaf.tailPendingAnsi = pty.tailPendingAnsi leaf.tailRedrawCursor = pty.tailRedrawCursor leaf.tailTruncated = pty.tailTruncated leaf.tailLinesTotal = pty.tailLinesTotal leaf.preview = pty.preview leaf.waitBlockedAt = pty.waitBlockedAt } else { const normalized = normalizeTerminalChunk(data, leaf.tailPendingAnsi) leaf.tailPendingAnsi = normalized.pendingAnsi const previousWaitText = buildTerminalWaitText( leaf.tailBuffer, leaf.tailPartialLine, leaf.preview ) const nextTail = appendNormalizedToTailBuffer( leaf.tailBuffer, leaf.tailPartialLine, normalized.text, leaf.tailRedrawCursor ) if ( nextTailHasNewerBlockedReason( previousWaitText, buildTerminalWaitText(nextTail.lines, nextTail.partialLine, leaf.preview), normalized.text ) ) { leaf.waitBlockedAt = at } leaf.tailBuffer = nextTail.lines leaf.tailPartialLine = nextTail.partialLine leaf.tailRedrawCursor = nextTail.redrawCursor leaf.tailTruncated = leaf.tailTruncated || nextTail.truncated leaf.tailLinesTotal += nextTail.newCompleteLines leaf.preview = buildPreview(leaf.tailBuffer, leaf.tailPartialLine) } if (oscTitle !== null) { // Why: keep the latest OSC title on the leaf so worktree.ps can // recompute status from the live title each call. Without this, // daemon-hosted terminals (no renderer pushing pane titles) had no // way to clear a stale 'working' status after the agent exited and // the shell took over the title — the stuck-spinner bug in #1437. leaf.lastOscTitle = oscTitle leaf.lastOscTitleAt = this.nextTitleObservationSequence() const prevStatus = leaf.lastAgentStatus // Why: when a new OSC title doesn't classify as an agent state (e.g. // bare shell title after the agent exits), clear lastAgentStatus so // it is no longer sticky. Tui-idle waiters that needed the previous // 'idle' transition were already resolved at the moment of the // transition below; only fresh waiters registered after the agent // exits would observe the cleared value, and they correctly fall // back to title-based detection / polling. leaf.lastAgentStatus = agentStatus // Why: resolve tui-idle on any transition TO idle (not just working→idle). // Claude Code may skip "working" entirely on fast tasks, going null→idle, // and the coordinator's tui-idle waiter would hang forever waiting for a // working→idle transition that never comes. Permission→idle is excluded: // it means the agent was blocked on user approval and the user said no, // which isn't a task-completion signal. if (agentStatus === 'idle' && prevStatus !== 'idle') { this.resolveTuiIdleWaiters(leaf) this.deliverPendingMessages(leaf) } } } this.emitTerminalAgentStatusEvents(ptyId, agentStatusChunk) if (shouldTouchPtyBackedSessionTabs) { this.touchMobileSessionSnapshotsForPty(ptyId) } const listeners = this.dataListeners.get(ptyId) if (listeners) { const meta = { seq: outputSequence, rawLength: data.length } for (const listener of listeners) { listener(data, meta) } } return outputSequence } private processAgentStatusOscForPty(ptyId: string, data: string): ProcessedAgentStatusChunk { let processor = this.agentStatusOscProcessorsByPtyId.get(ptyId) if (!processor) { processor = createAgentStatusOscProcessor() this.agentStatusOscProcessorsByPtyId.set(ptyId, processor) } return processor(data) } private extractLastOscTitleForPty(ptyId: string, data: string): string | null { const previousTail = this.oscTitleScanTailByPtyId.get(ptyId) if (!previousTail && !data.includes('\x1b')) { return null } const input = `${previousTail ?? ''}${data}` const scanTail = extractOscTitleScanTail(input) if (scanTail.length > 0) { this.oscTitleScanTailByPtyId.set(ptyId, scanTail) } else { this.oscTitleScanTailByPtyId.delete(ptyId) } return extractLastOscTitle(input) } private emitTerminalAgentStatusEvents(ptyId: string, chunk: ProcessedAgentStatusChunk): void { // Why: snapshot retention (for mobile worktree.ps) must run even when no // renderer listener is attached, so we don't early-return on a missing // onTerminalAgentStatus — only the per-target emit below is gated on it. if (chunk.payloads.length === 0) { return } const targets = new Map< string, { source: 'mounted-leaf' | 'pty-record' paneKey: string tabId?: string worktreeId?: string connectionId?: string | null } >() const pty = this.ptysById.get(ptyId) const connectionId = pty?.connectionId ?? null for (const leaf of this.getLeavesForPty(ptyId)) { const paneKey = this.makeRuntimePaneKey(leaf) targets.set(paneKey, { source: 'mounted-leaf', paneKey, tabId: leaf.tabId, worktreeId: leaf.worktreeId, connectionId }) } if (targets.size === 0 && pty?.paneKey) { targets.set(pty.paneKey, { source: 'pty-record', paneKey: pty.paneKey, tabId: pty.tabId ?? undefined, worktreeId: pty.worktreeId, connectionId }) } for (const payload of chunk.payloads) { for (const target of targets.values()) { this.retainAgentRowSnapshot(ptyId, target.paneKey, target.worktreeId, target.tabId, payload) if (!this.onTerminalAgentStatus) { continue } try { this.onTerminalAgentStatus({ ptyId, ...target, payload }) } catch (err) { console.error('[runtime] terminal agent status listener threw', { ptyId, paneKey: target.paneKey, state: payload.state, agentType: payload.agentType, err }) } } } } private retainAgentRowSnapshot( ptyId: string, paneKey: string, worktreeId: string | undefined, tabId: string | undefined, payload: ParsedAgentStatusPayload ): void { const now = Date.now() const previous = this.latestAgentStatusByPaneKey.get(paneKey) // Why: stateStartedAt must mark the transition into the current state, not // every within-state ping (tool/prompt updates keep the state but refresh // updatedAt) — mirrors AgentStatusEntry.stateStartedAt on the desktop side. const stateStartedAt = previous && previous.payload.state === payload.state ? previous.stateStartedAt : now this.latestAgentStatusByPaneKey.set(paneKey, { paneKey, ptyId, worktreeId, tabId, payload, stateStartedAt, updatedAt: now }) } private clearAgentRowSnapshotsForPty(ptyId: string): void { for (const [paneKey, snapshot] of this.latestAgentStatusByPaneKey) { if (snapshot.ptyId === ptyId) { this.latestAgentStatusByPaneKey.delete(paneKey) } } } getPtyOutputSequence(ptyId: string): number { return this.ptyOutputSequenceById.get(ptyId) ?? 0 } subscribeToTerminalData( ptyId: string, listener: (data: string, meta?: { seq?: number; rawLength?: number }) => void ): () => void { return addListenerToMap(this.dataListeners, ptyId, listener) } subscribeToFitOverrideChanges( ptyId: string, listener: (event: { mode: 'mobile-fit' | 'desktop-fit'; cols: number; rows: number }) => void ): () => void { return addListenerToMap(this.fitOverrideListeners, ptyId, listener) } subscribeToDriverChanges(ptyId: string, listener: (driver: DriverState) => void): () => void { return addListenerToMap(this.driverListeners, ptyId, listener) } private notifyFitOverrideListeners( ptyId: string, mode: 'mobile-fit' | 'desktop-fit', cols: number, rows: number ): void { const listeners = this.fitOverrideListeners.get(ptyId) if (!listeners) { return } for (const listener of listeners) { listener({ mode, cols, rows }) } } serializeTerminalBuffer( ptyId: string, opts: { scrollbackRows?: number } = {} ): Promise<{ data: string cols: number rows: number cwd?: string | null lastTitle?: string seq?: number source?: 'headless' | 'renderer' oscLinks?: TerminalOscLinkRange[] alternateScreen?: boolean } | null> { return this.serializeTerminalBufferFromAvailableState(ptyId, opts) } serializeMainTerminalBuffer( ptyId: string, opts: { scrollbackRows?: number } = {} ): Promise<{ data: string cols: number rows: number cwd?: string | null lastTitle?: string seq?: number source?: 'headless' | 'renderer' oscLinks?: TerminalOscLinkRange[] alternateScreen?: boolean } | null> { return this.serializeHeadlessTerminalBuffer(ptyId, { ...opts, includeEmpty: true }) } async serializeHiddenOutputRecoveryBuffer( ptyId: string, opts: { scrollbackRows?: number } = {} ): Promise<{ data: string cols: number rows: number cwd?: string | null lastTitle?: string seq?: number source?: 'headless' | 'renderer' oscLinks?: TerminalOscLinkRange[] alternateScreen?: boolean } | null> { const headlessSnapshot = await this.serializeHeadlessTerminalBuffer(ptyId, { ...opts, includeEmpty: true }) if (headlessSnapshot) { return headlessSnapshot } // Why: hidden-output recovery is initiated by the desktop renderer. If the // runtime has not built headless state yet, the mounted xterm is still the // best available state and avoids a false "snapshot unavailable" result. return this.serializeRendererTerminalBuffer(ptyId, opts) } async clearTerminalBuffer(handle: string): Promise<{ handle: string; cleared: boolean }> { const leaf = this.resolveLeafForHandle(handle) if (!leaf?.ptyId) { throw new Error('terminal_not_found') } // Why: clear is a terminal UI action (Cmd+K on desktop), not shell input. // Route through the controller so renderer-owned xterm buffers, daemon // sessions, and SSH relay sessions all drop scrollback before the next // mobile snapshot. await this.ptyController?.clearBuffer?.(leaf.ptyId) await this.clearHeadlessTerminalBuffer(leaf.ptyId) return { handle, cleared: true } } getTerminalSize(ptyId: string): { cols: number; rows: number } | null { return this.ptyController?.getSize?.(ptyId) ?? null } // Why: a width reflow on a normal-buffer PTY must re-stream the full // scrollback to mobile so it rewraps at the new cols, but alternate-screen // TUIs (vim, Claude Code) own their repaint and have no scrollback — for // those the mobile client just resizes xterm geometry and consumes the // TUI's own redraw, so the resize re-stream must be skipped. Returns false // when there is no headless emulator (resize falls back to geometry-only). isTerminalAlternateScreen(ptyId: string): boolean { return this.headlessTerminals.get(ptyId)?.emulator.isAlternateScreen ?? false } // Why: daemon-backed PTYs that the runtime adopted after an Orca relaunch // start with a fresh headless emulator that has zero scrollback, even though // the daemon's on-disk checkpoint and the desktop xterm both contain the // full prior history. Without this hydration, mobile subscribers see only // the bare current prompt because serializeHeadlessTerminalBuffer always // wins over the renderer-path fallback. Seeding the emulator with the // adapter's snapshot/cold-restore data makes mobile and desktop agree on // what scrollback is available. seedHeadlessTerminal( ptyId: string, data: string, size?: { cols: number; rows: number }, metadata: HeadlessSeedMetadata = {} ): void { if (!data) { return } const existing = this.headlessTerminals.get(ptyId) if (existing) { // Why: emulator already has live data — re-seeding would duplicate // every byte. The seed is only valid when the emulator is fresh. return } const dims = size ?? this.getTerminalSize(ptyId) ?? { cols: 80, rows: 24 } const state: RuntimeHeadlessTerminal = { emulator: new HeadlessEmulator({ cols: dims.cols, rows: dims.rows }), outputSequence: 0, writeChain: Promise.resolve() } this.headlessTerminals.set(ptyId, state) state.writeChain = state.writeChain .then(async () => { await state.emulator.write(data) if (metadata.cwd !== undefined) { state.emulator.setCwd(metadata.cwd) } if (metadata.oscLinks !== undefined) { state.emulator.setRestoredOscLinks(metadata.oscLinks) } }) .catch(() => { // Seeding is best-effort; live data will continue to populate the // emulator even if the snapshot replay fails. }) } // Why: hydrate the runtime headless emulator from the desktop renderer's // xterm buffer on the first onPtyData byte after a PTY is taken over by a // pane. Eager-state pattern matches seedHeadlessTerminal: headlessTerminals // is populated synchronously so concurrent live writes from // trackHeadlessTerminalData chain after the seed via the same writeChain. // See docs/mobile-prefer-renderer-scrollback.md. private maybeHydrateHeadlessFromRenderer(ptyId: string): void { if (this.headlessHydrationState.has(ptyId)) { return } if (this.headlessTerminals.has(ptyId)) { // Daemon-snapshot seed already populated the emulator — skip hydration. this.headlessHydrationState.set(ptyId, 'done') return } const controller = this.ptyController if (!controller?.serializeBuffer || !controller.hasRendererSerializer) { return } if (!controller.hasRendererSerializer(ptyId)) { // Renderer hasn't registered yet (or never will). Live writes lazy- // create the state via trackHeadlessTerminalData on this same tick. return } this.headlessHydrationState.set(ptyId, 'pending') const dims = this.getTerminalSize(ptyId) ?? { cols: 80, rows: 24 } const state: RuntimeHeadlessTerminal = { emulator: new HeadlessEmulator({ cols: dims.cols, rows: dims.rows }), outputSequence: 0, writeChain: Promise.resolve() } this.headlessTerminals.set(ptyId, state) // Why: append the seed work to writeChain so live writes queued by // trackHeadlessTerminalData (after this method returns synchronously) // execute AFTER the seed-write resolves. If we awaited inline before // setting headlessTerminals, the live byte would lazy-create a separate // state and the seed-resolve would overwrite it, dropping live bytes. state.writeChain = state.writeChain.then(async () => { try { const rendered = await controller.serializeBuffer!(ptyId, { scrollbackRows: MOBILE_SUBSCRIBE_SCROLLBACK_ROWS, altScreenForcesZeroRows: true }) if (!rendered || rendered.data.length === 0) { return } // Resize to renderer's dims so the seed reflows correctly into the // emulator's grid, then resize back to PTY dims (if known) so live // writes use the correct cell layout. if (rendered.cols !== dims.cols || rendered.rows !== dims.rows) { state.emulator.resize(rendered.cols, rendered.rows) } await state.emulator.write(rendered.data) const ptyDims = this.getTerminalSize(ptyId) if (ptyDims && (ptyDims.cols !== rendered.cols || ptyDims.rows !== rendered.rows)) { state.emulator.resize(ptyDims.cols, ptyDims.rows) } if (rendered.lastTitle) { state.emulator.setLastTitle(rendered.lastTitle) this.applySeededAgentStatus(ptyId, rendered.lastTitle) } } catch { // Hydration is best-effort. Live writes continue via the same // writeChain that this catch-arm leaves intact. } finally { this.headlessHydrationState.set(ptyId, 'done') } }) } // Why: seed-derived agent status reflects historical state. Orchestration // waiters (resolveTuiIdleWaiters, deliverPendingMessages) must only react // to LIVE transitions, so this helper writes leaf.lastAgentStatus only and // never resolves waiters. detectAgentStatusFromTitle wrap mirrors the live // path so seeded and live values are the same union member, keeping // downstream `=== 'idle'` checks correct. private applySeededAgentStatus(ptyId: string, title: string): void { if (!title) { return } const status = detectAgentStatusFromTitle(title) const pty = this.ptysById.get(ptyId) if (pty) { const observedAt = this.nextTitleObservationSequence() pty.lastOscTitle = title pty.lastOscTitleAt = observedAt this.setPtyManagementTitleFromObservedTitle(pty, title, observedAt) } for (const leaf of this.getLeavesForPty(ptyId)) { // Why: seed lastOscTitle even when the seeded title doesn't classify // as an agent state, so worktree.ps recomputes status from the live // title rather than treating the leaf as agentless. leaf.lastOscTitle = title leaf.lastOscTitleAt = this.nextTitleObservationSequence() if (status !== null) { leaf.lastAgentStatus = status } } } private trackHeadlessTerminalData(ptyId: string, data: string, outputSequence: number): void { const state = this.getOrCreateHeadlessTerminal(ptyId) state.writeChain = state.writeChain .then(async () => { await state.emulator.write(data) state.outputSequence = outputSequence }) .catch(() => { // Best-effort state tracking; live streaming must continue even if // xterm rejects a malformed or raced write during shutdown. }) } private getOrCreateHeadlessTerminal(ptyId: string): RuntimeHeadlessTerminal { const existing = this.headlessTerminals.get(ptyId) if (existing) { return existing } const size = this.getTerminalSize(ptyId) ?? { cols: 80, rows: 24 } const state: RuntimeHeadlessTerminal = { emulator: new HeadlessEmulator({ cols: size.cols, rows: size.rows }), outputSequence: 0, writeChain: Promise.resolve() } this.headlessTerminals.set(ptyId, state) return state } private resizeHeadlessTerminal(ptyId: string, cols: number, rows: number): void { this.headlessTerminals.get(ptyId)?.emulator.resize(cols, rows) } private async clearHeadlessTerminalBuffer(ptyId: string): Promise { const state = this.headlessTerminals.get(ptyId) if (!state) { return } // Why: headless writes are queued to preserve xterm parser order. Clear // must join that same chain or an earlier PTY chunk can finish after the // clear request and repopulate mobile scrollback. state.writeChain = state.writeChain.then(() => state.emulator.clearScrollback()) await state.writeChain } private async serializeTerminalBufferFromAvailableState( ptyId: string, opts: { scrollbackRows?: number } = {} ): Promise<{ data: string cols: number rows: number cwd?: string | null lastTitle?: string seq?: number source?: 'headless' | 'renderer' oscLinks?: TerminalOscLinkRange[] alternateScreen?: boolean } | null> { const headlessSnapshot = await this.serializeHeadlessTerminalBuffer(ptyId, opts) if (headlessSnapshot) { return headlessSnapshot } return this.serializeRendererTerminalBuffer(ptyId, opts) } private async serializeRendererTerminalBuffer( ptyId: string, opts: { scrollbackRows?: number } = {} ): Promise<{ data: string cols: number rows: number cwd?: string | null lastTitle?: string source?: 'renderer' oscLinks?: TerminalOscLinkRange[] } | null> { let rendererSnapshot: { data: string cols: number rows: number cwd?: string | null lastTitle?: string oscLinks?: TerminalOscLinkRange[] } | null = null try { // Why: recovery/read fallback wants visible alt-screen content (e.g. an // active TUI), so altScreenForcesZeroRows is FALSE here. Hydration is // the only path that suppresses alt-screen scrollback. rendererSnapshot = await (this.ptyController?.serializeBuffer?.(ptyId, { scrollbackRows: opts.scrollbackRows, altScreenForcesZeroRows: false }) ?? Promise.resolve(null)) } catch { // Why: terminal snapshots should not depend on a mounted renderer pane. // If renderer serialization races reload/unmount, callers can still use // their existing null fallback paths. } return rendererSnapshot ? { ...rendererSnapshot, source: 'renderer' } : null } private async withVisibleSnapshotFallback( ptyId: string, read: RuntimeTerminalRead, opts: { cursor?: number; limit?: number } = {} ): Promise { if (!shouldFallbackToVisibleTerminalSnapshot(read, opts)) { return read } const lines = await this.readRendererVisibleSnapshotLines(ptyId) if (lines.length === 0) { return read } return buildVisibleSnapshotReadFallback(read, lines, opts.limit) } private async readRendererVisibleSnapshotLines(ptyId: string): Promise { const controller = this.ptyController if (!controller?.serializeBuffer) { return [] } if (controller.hasRendererSerializer && !controller.hasRendererSerializer(ptyId)) { return [] } try { // Why: raw PTY tails can be whitespace-only while a full-screen TUI is // visibly nonblank in renderer xterm. Ask the renderer for the active // screen instead of reusing the headless transcript path. const snapshot = await controller.serializeBuffer(ptyId, { scrollbackRows: 0, altScreenForcesZeroRows: false }) if (!snapshot || snapshot.data.length === 0) { return [] } const emulator = new HeadlessEmulator({ cols: snapshot.cols, rows: snapshot.rows, scrollback: 0 }) try { await emulator.write(snapshot.data) return emulator .getVisibleLines() .map((line) => line.trimEnd()) .filter((line) => line.trim().length > 0) } finally { emulator.dispose() } } catch { return [] } } private async serializeHeadlessTerminalBuffer( ptyId: string, opts: { scrollbackRows?: number; includeEmpty?: boolean } = {} ): Promise<{ data: string cols: number rows: number cwd?: string | null lastTitle?: string seq?: number source?: 'headless' oscLinks?: TerminalOscLinkRange[] alternateScreen?: boolean } | null> { const state = this.headlessTerminals.get(ptyId) if (!state) { return null } await state.writeChain // Why: when an alternate-screen TUI (Claude Code, vim, etc.) is currently // active, the visible content is the alt-screen snapshot — replaying any // normal-buffer scrollback before it can duplicate shell prompts and // flatten SGR attributes when the mobile xterm replays the data. Force // scrollbackRows=0 in that case. When the buffer is in normal mode the // caller can request scrollback so the user can scroll up to see prior // agent output. const requested = opts.scrollbackRows ?? 0 const isAlternateScreen = state.emulator.isAlternateScreen const scrollbackRows = isAlternateScreen ? 0 : requested const snapshot = state.emulator.getSnapshot({ scrollbackRows }) const data = snapshot.rehydrateSequences + snapshot.snapshotAnsi return data.length > 0 || opts.includeEmpty === true ? { data, cols: snapshot.cols, rows: snapshot.rows, cwd: snapshot.cwd, lastTitle: snapshot.lastTitle, seq: state.outputSequence, source: 'headless', oscLinks: snapshot.oscLinks, // Why: lets the renderer skip the destructive scrollback clear when // restoring an alt-screen snapshot — clearing wipes xterm's own // history that the TUI relies on for scroll-up after a tab return. alternateScreen: isAlternateScreen } : null } private disposeHeadlessTerminal(ptyId: string): void { this.headlessHydrationState.delete(ptyId) const state = this.headlessTerminals.get(ptyId) if (!state) { return } this.headlessTerminals.delete(ptyId) state.writeChain.finally(() => state.emulator.dispose()).catch(() => state.emulator.dispose()) } resolveLeafForHandle(handle: string): { ptyId: string | null } | null { const record = this.handles.get(handle) if (!record) { return null } if (record.tabId.startsWith('pty:')) { return { ptyId: record.ptyId } } const leaf = this.leaves.get(this.getLeafKey(record.tabId, record.leafId)) if (!leaf) { return null } return { ptyId: leaf.ptyId } } registerSubscriptionCleanup( subscriptionId: string, cleanup: () => void, connectionId?: string ): void { // Why: mobile clients reconnect frequently (phone lock, network switch). // The RPC client re-sends terminal.subscribe on reconnect, creating a new // handler before the old one is cleaned up. Without this, the old data // listener leaks in dataListeners and duplicates every PTY data event. const existing = this.subscriptionCleanups.get(subscriptionId) if (existing) { this.cleanupSubscription(subscriptionId) } this.subscriptionCleanups.set(subscriptionId, cleanup) if (connectionId) { let set = this.subscriptionsByConnection.get(connectionId) if (!set) { set = new Set() this.subscriptionsByConnection.set(connectionId, set) } set.add(subscriptionId) this.subscriptionConnectionByEntry.set(subscriptionId, connectionId) } } cleanupSubscription(subscriptionId: string): void { const cleanup = this.subscriptionCleanups.get(subscriptionId) if (cleanup) { this.subscriptionCleanups.delete(subscriptionId) const connectionId = this.subscriptionConnectionByEntry.get(subscriptionId) if (connectionId) { this.subscriptionConnectionByEntry.delete(subscriptionId) const set = this.subscriptionsByConnection.get(connectionId) if (set) { set.delete(subscriptionId) if (set.size === 0) { this.subscriptionsByConnection.delete(connectionId) } } } cleanup() } } cleanupSubscriptionsByPrefix(prefix: string): void { const ids = Array.from(this.subscriptionCleanups.keys()).filter((id) => id.startsWith(prefix)) for (const id of ids) { this.cleanupSubscription(id) } } // Why: invoked from the WebSocket transport's on-close hook so streaming // listeners registered for this exact socket get torn down even when other // sockets sharing the same deviceToken are still alive (multi-screen // mobile). Without this sweep, listeners leak across every reconnect. cleanupSubscriptionsForConnection(connectionId: string): void { const set = this.subscriptionsByConnection.get(connectionId) if (!set) { return } // Why: snapshot the ids before iterating because cleanupSubscription // mutates both the set and the index map. const ids = Array.from(set) for (const id of ids) { this.cleanupSubscription(id) } } // Why: mobile clients subscribe via notifications.subscribe streaming RPC. // Each subscriber gets its own listener. Returns an unsubscribe function // that the subscription cleanup mechanism calls on disconnect. onNotificationDispatched(listener: (event: MobileNotificationEvent) => void): () => void { this.notificationListeners.add(listener) return () => { this.notificationListeners.delete(listener) } } getMobileNotificationListenerCount(): number { return this.notificationListeners.size } dispatchMobileNotification(event: MobileNotificationEvent): void { for (const listener of this.notificationListeners) { listener(event) } } dismissMobileNotification(notificationId: string): void { this.dispatchMobileNotification({ type: 'dismiss', notificationId }) } // ─── Account Services (mobile RPC bridge) ───────────────────── setAccountServices(services: RuntimeAccountServices): void { this.accountServices = services } setCommitMessageAgentEnvironmentResolvers( resolvers: CommitMessageAgentEnvironmentResolvers ): void { this.commitMessageAgentEnv = resolvers } getCommitMessageAgentEnvironmentResolvers(): CommitMessageAgentEnvironmentResolvers | undefined { return this.commitMessageAgentEnv ?? undefined } // Lists the speech-model catalog joined with live download/ready state, plus // the current enabled flag + selected model, so mobile can present a dictation // setup sheet and drive remote enable/download. Always targets this (paired) // desktop — speech never routes to a worktree's SSH host. async listMobileSpeechModels(): Promise { if (!this.store) { throw new Error('voice_dictation_unavailable') } const voice = this.store.getSettings().voice ?? getDefaultVoiceSettings() const states = await getSpeechModelManager(this.store).getModelStates() const stateById = new Map(states.map((state) => [state.id, state])) const models: RuntimeSpeechModelSummary[] = SPEECH_MODEL_CATALOG.map((manifest) => { const state = stateById.get(manifest.id) return { id: manifest.id, label: manifest.label, provider: manifest.provider === 'openai' ? 'openai' : 'local', sizeBytes: manifest.sizeBytes ?? null, recommended: manifest.recommended === true, status: state?.status ?? 'not-downloaded', progress: state?.progress ?? null } }) return { enabled: voice.enabled === true, selectedModelId: voice.sttModel ?? '', dictationMode: voice.dictationMode === 'hold' ? 'hold' : 'toggle', models } } // Fire-and-forget model download; the ModelManager writes progress into its // per-model state, which mobile reads back via listMobileSpeechModels polling. async downloadMobileSpeechModel(modelId: string): Promise<{ started: true }> { if (!this.store) { throw new Error('voice_dictation_unavailable') } const manifest = getCatalogModel(modelId) if (!manifest || !isLocalSpeechModel(manifest)) { throw new Error('voice_model_not_downloadable') } // Why: do not await — downloads run for tens of seconds; the call returns // immediately and mobile polls for progress/ready. void getSpeechModelManager(this.store) .downloadModel(modelId) .catch((err) => { console.error('[runtime] mobile speech model download failed', { modelId, err }) }) return { started: true } } async deleteMobileSpeechModel(modelId: string): Promise { if (!this.store?.getSettings || !this.store.updateSettings) { throw new Error('voice_dictation_unavailable') } const store = this.store try { // The runtime store is adapted to the minimal speech settings contract used by deletion. await deleteLocalSpeechModel({ store: { getSettings: () => store.getSettings(), updateSettings: (updates, options) => store.updateSettings?.(updates, options) }, modelManager: getSpeechModelManager(store), sttService: getSpeechSttService(store), modelId }) } catch (error) { throw new Error(getSpeechModelDeletionErrorCode(error) ?? 'voice_model_delete_failed') } return this.listMobileSpeechModels() } // Enables/disables dictation and/or selects the model, merging into the // existing voice settings so other voice fields are preserved. async configureMobileDictation(params: { enabled?: boolean modelId?: string dictationMode?: 'toggle' | 'hold' }): Promise { if (!this.store?.getSettings || !this.store.updateSettings) { throw new Error('voice_dictation_unavailable') } const current = this.store.getSettings().voice ?? getDefaultVoiceSettings() // An explicit '' clears the selected model (the OptionalString RPC schema // maps '' → undefined, so this only matters for direct callers); any other // non-empty modelId must be a known catalog entry. if (params.modelId !== undefined && params.modelId !== '' && !getCatalogModel(params.modelId)) { throw new Error('voice_model_unknown') } const nextVoice: VoiceSettings = { ...current, ...(params.enabled !== undefined ? { enabled: params.enabled } : {}), ...(params.modelId !== undefined ? { sttModel: params.modelId } : {}), ...(params.dictationMode !== undefined ? { dictationMode: params.dictationMode } : {}) } this.store.updateSettings({ voice: nextVoice }, { notifyListeners: true }) return this.listMobileSpeechModels() } async startMobileDictation(params: { dictationId: string modelId?: string clientId?: string connectionId?: string }): Promise<{ dictationId: string modelId: string }> { if (!this.store) { throw new Error('voice_dictation_unavailable') } const voice = this.store.getSettings().voice ?? getDefaultVoiceSettings() if (!voice.enabled) { throw new Error('voice_dictation_disabled') } const modelId = params.modelId || voice.sttModel if (!modelId) { throw new Error('voice_model_not_selected') } const modelState = await getSpeechModelManager(this.store).getModelState(modelId) if (modelState.status !== 'ready') { throw new Error(`voice_model_not_ready:${modelState.status}`) } if (!params.clientId) { throw new Error('dictation_requires_mobile_client') } if (this.mobileDictation) { throw new Error('dictation_already_active') } const owner = `mobile:${params.dictationId}` this.mobileDictation = { id: params.dictationId, owner, clientId: params.clientId, connectionId: params.connectionId, state: 'starting', partialText: '', finalTexts: [], errors: [] } try { await getSpeechSttService(this.store).startDictation( modelId, (event) => { const session = this.mobileDictation if (!session || session.id !== params.dictationId) { return } if (event.type === 'partial') { session.partialText = event.text ?? '' } else if (event.type === 'final') { const text = event.text?.trim() if (text) { session.finalTexts.push(text) session.partialText = '' } } else if (event.type === 'error') { session.errors.push(event.error ?? 'Speech worker error') } }, undefined, owner ) if (this.mobileDictation?.id !== params.dictationId) { throw new Error('dictation_canceled') } this.mobileDictation.state = 'active' } catch (error) { if (this.mobileDictation?.id === params.dictationId) { this.mobileDictation = null } throw error } return { dictationId: params.dictationId, modelId } } feedMobileDictation(params: { dictationId: string audioBase64: string sampleRate: number clientId?: string connectionId?: string }): { dictationId: string } { const session = this.mobileDictation if (!session || session.id !== params.dictationId) { throw new Error('dictation_stream_not_started') } if (!params.clientId || session.clientId !== params.clientId) { throw new Error('dictation_owner_mismatch') } if (session.connectionId && session.connectionId !== params.connectionId) { throw new Error('dictation_owner_mismatch') } if (session.state !== 'active') { throw new Error('dictation_stream_closing') } if (session.errors.length > 0) { throw new Error(session.errors[0]) } const pcm = Buffer.from(params.audioBase64, 'base64') const samples = new Float32Array(Math.floor(pcm.length / 2)) for (let i = 0; i < samples.length; i += 1) { samples[i] = pcm.readInt16LE(i * 2) / 32768 } getSpeechSttService(this.store!).feedAudio(samples, params.sampleRate, session.owner) return { dictationId: params.dictationId } } async finishMobileDictation(params: { dictationId: string clientId?: string connectionId?: string }): Promise<{ dictationId: string text: string }> { const session = this.mobileDictation if (!session || session.id !== params.dictationId) { throw new Error('dictation_stream_not_started') } if (!params.clientId || session.clientId !== params.clientId) { throw new Error('dictation_owner_mismatch') } if (session.connectionId && session.connectionId !== params.connectionId) { throw new Error('dictation_owner_mismatch') } session.state = 'closing' try { await getSpeechSttService(this.store!).stopDictation(session.owner) if (session.errors.length > 0) { throw new Error(session.errors[0]) } const text = [...session.finalTexts, session.partialText].join(' ').trim() return { dictationId: params.dictationId, text } } finally { if (this.mobileDictation?.id === session.id) { this.mobileDictation = null } } } async cancelMobileDictation(params: { dictationId: string clientId?: string connectionId?: string }): Promise<{ dictationId: string }> { const session = this.mobileDictation if ( session?.id === params.dictationId && params.clientId && session.clientId === params.clientId && (!session.connectionId || session.connectionId === params.connectionId) ) { session.state = 'closing' try { await getSpeechSttService(this.store!).stopDictation(session.owner) } finally { if (this.mobileDictation?.id === session.id) { this.mobileDictation = null } } } return { dictationId: params.dictationId } } private cancelMobileDictationSession(session: NonNullable): void { if (session.state === 'closing') { return } session.state = 'closing' void getSpeechSttService(this.store!) .stopDictation(session.owner) .finally(() => { if (this.mobileDictation?.id === session.id) { this.mobileDictation = null } }) } cancelMobileDictationForConnection(connectionId: string): void { const session = this.mobileDictation if (!session || session.connectionId !== connectionId) { return } this.cancelMobileDictationSession(session) } private cancelMobileDictationForClient(clientId: string): void { const session = this.mobileDictation if (!session || session.clientId !== clientId) { return } this.cancelMobileDictationSession(session) } private requireAccountServices(): RuntimeAccountServices { if (!this.accountServices) { throw new Error('Account services are not configured on this runtime') } return this.accountServices } getAccountsSnapshot(): AccountsSnapshot { const { claudeAccounts, codexAccounts, rateLimits } = this.requireAccountServices() return { claude: claudeAccounts.listAccounts(), codex: codexAccounts.listAccounts(), rateLimits: rateLimits.getState() } } // Why: RateLimitService polls only when the Electron window is visible AND // focused, and the inactive-account caches fill lazily when the user opens // the desktop AccountsPane. Mobile has neither trigger, so without this the // phone shows 0% / "—" against a backgrounded desktop. Errors swallowed // because partial usage is still useful for the rest of the snapshot. async refreshAccountsForMobile(): Promise { const { rateLimits } = this.requireAccountServices() await Promise.allSettled([ rateLimits.refresh(), rateLimits.fetchInactiveClaudeAccountsOnOpen(), rateLimits.fetchInactiveCodexAccountsOnOpen() ]) } selectClaudeAccount(accountId: string | null): Promise { return this.requireAccountServices().claudeAccounts.selectAccount(accountId) } selectCodexAccount(accountId: string | null): Promise { return this.requireAccountServices().codexAccounts.selectAccount(accountId) } removeClaudeAccount(accountId: string): Promise { return this.requireAccountServices().claudeAccounts.removeAccount(accountId) } removeCodexAccount(accountId: string): Promise { return this.requireAccountServices().codexAccounts.removeAccount(accountId) } // Why: rate-limit polling fires every 5 minutes and on account switch. // Mobile clients subscribe to receive a fresh AccountsSnapshot whenever // RateLimitService pushes new usage data, mirroring the existing // `rateLimits:update` IPC channel desktop already uses. onAccountsChanged(listener: (snapshot: AccountsSnapshot) => void): () => void { const services = this.requireAccountServices() return services.rateLimits.onStateChange(() => { listener({ claude: services.claudeAccounts.listAccounts(), codex: services.codexAccounts.listAccounts(), rateLimits: services.rateLimits.getState() }) }) } // ─── Mobile Fit Override Management ───────────────────────── // Why: legacy mobile RPC entrypoint. After the state-machine rewrite this // is a thin shim that computes a `PtyLayoutTarget` and routes through // `enqueueLayout`. Keeps the same observable return shape so older mobile // builds continue to work. See docs/mobile-terminal-layout-state-machine.md. async resizeForClient( ptyId: string, mode: 'mobile-fit' | 'restore', clientId: string, cols?: number, rows?: number ): Promise<{ cols: number rows: number previousCols: number | null previousRows: number | null mode: 'mobile-fit' | 'desktop-fit' }> { if (mode === 'mobile-fit') { if (cols == null || rows == null || !Number.isFinite(cols) || !Number.isFinite(rows)) { throw new Error('invalid_dimensions') } const { cols: clampedCols, rows: clampedRows } = clampTerminalViewport(cols, rows) const currentSize = this.getTerminalSize(ptyId) const existing = this.terminalFitOverrides.get(ptyId) // Capture baseline cols/rows for the return value (existing override's // baseline wins over current size to preserve original desktop dims // across multiple re-fits). const previousCols = existing?.previousCols ?? currentSize?.cols ?? null const previousRows = existing?.previousRows ?? currentSize?.rows ?? null // Why: legacy resizeForClient callers bypass handleMobileSubscribe, so // mobileSubscribers stays empty and resolveDesktopRestoreTarget's step-1 // (per-subscriber baseline) never matches. Stash the pre-fit PTY size // into lastRendererSizes so restore lands on step 2 (renderer geometry) // instead of step 3 (current phone-fit dims = no-op restore). if (currentSize && !existing) { this.lastRendererSizes.set(ptyId, { cols: currentSize.cols, rows: currentSize.rows }) } this.freshSubscribeGuard.add(ptyId) let result: ApplyLayoutResult try { result = await this.enqueueLayout(ptyId, { kind: 'phone', cols: clampedCols, rows: clampedRows, ownerClientId: clientId }) } finally { this.freshSubscribeGuard.delete(ptyId) } if (!result.ok) { throw new Error('resize_failed') } // Why: mobile-fit via resizeForClient is a deliberate mobile action; // the actor takes the floor (updates lastActedAt; mode-flip case is // already handled by enqueueLayout above). await this.mobileTookFloor(ptyId, clientId) return { cols: clampedCols, rows: clampedRows, previousCols, previousRows, mode: 'mobile-fit' } } // restore mode const override = this.terminalFitOverrides.get(ptyId) if (!override) { throw new Error('no_active_override') } // Only the owning client can restore — prevents one phone from undoing // another phone's active fit. if (override.clientId !== clientId) { throw new Error('not_override_owner') } const restore = this.resolveDesktopRestoreTarget(ptyId) const result = await this.enqueueLayout(ptyId, { kind: 'desktop', cols: restore.cols, rows: restore.rows }) if (!result.ok) { throw new Error('resize_failed') } // Why: legacy mobile clients on the resizeForClient path also need a // fit-override-listener notification (the renderer-side terminalFitOverrideChanged // is already emitted by applyLayout's mode-flip path). this.notifyFitOverrideListeners(ptyId, 'desktop-fit', restore.cols, restore.rows) return { cols: restore.cols, rows: restore.rows, previousCols: null, previousRows: null, mode: 'desktop-fit' } } getTerminalFitOverride(ptyId: string) { return this.terminalFitOverrides.get(ptyId) ?? null } getAllTerminalFitOverrides(): Map { const result = new Map() for (const [ptyId, override] of this.terminalFitOverrides) { result.set(ptyId, { mode: override.mode, cols: override.cols, rows: override.rows }) } return result } getAllTerminalDrivers(): Map { return new Map(this.currentDriver) } getAllBrowserDrivers(): Map { return new Map(this.currentBrowserDriver) } private getBrowserDriver(browserPageId: string): RuntimeBrowserDriverState { return this.currentBrowserDriver.get(browserPageId) ?? { kind: 'idle' } } private setBrowserDriver(browserPageId: string, next: RuntimeBrowserDriverState): void { const prev = this.getBrowserDriver(browserPageId) if (prev.kind === next.kind) { if (prev.kind === 'mobile' && next.kind === 'mobile' && prev.clientId === next.clientId) { return } if (prev.kind !== 'mobile' && next.kind !== 'mobile') { return } } if (next.kind === 'idle') { this.currentBrowserDriver.delete(browserPageId) } else { this.currentBrowserDriver.set(browserPageId, next) } this.notifier?.browserDriverChanged?.(browserPageId, next) } reclaimBrowserForDesktop(browserPageId: string): boolean { this.setBrowserDriver(browserPageId, { kind: 'desktop' }) this.activeBrowserScreencastsByPage.get(browserPageId)?.cancel(true) return true } onClientDisconnected(clientId: string): void { this.cancelMobileDictationForClient(clientId) // (1) Cancel pending restore-debounce timers owned by this client. for (const [ptyId, entry] of this.pendingRestoreTimers) { if (entry.clientId === clientId) { clearTimeout(entry.timer) this.pendingRestoreTimers.delete(ptyId) } } // (2) Promote any soft-leave grace owned by this client into immediate // finalization. Grace existed to absorb a quick re-subscribe; a real // disconnect kills any chance of re-subscribe. // // Note: this is mode-decoupled (matches docs/mobile-terminal-layout-state-machine.md // sub-case 2). Today's pre-rewrite code only restored when // `mode === 'auto' && wasResizedToPhone`; the new design restores // whenever the layout is currently `phone`. This is an intentional // behavior fix — `mode === 'phone'` with no subscribers is a degenerate // state nothing in product depends on. for (const [ptyId, soft] of this.pendingSoftLeavers) { if (soft.clientId !== clientId) { continue } clearTimeout(soft.timer) this.pendingSoftLeavers.delete(ptyId) // Cancel any in-flight 300ms restore timer too — we'll handle it inline. const pending = this.pendingRestoreTimers.get(ptyId) if (pending) { clearTimeout(pending.timer) this.pendingRestoreTimers.delete(ptyId) } const cur = this.layouts.get(ptyId) // Why: Indefinite hold (mobileAutoRestoreFitMs == null) keeps the PTY // at phone dims after the phone disconnects; the desktop banner's // Restore button is the explicit return path. See // docs/mobile-fit-hold.md. if (cur?.kind === 'phone' && this.getAutoRestoreFitMs() != null) { // Use the soft-leaver's snapshot baseline as a hint, falling // through to resolveDesktopRestoreTarget for missing values. const fallback = this.resolveDesktopRestoreTarget(ptyId) const cols = soft.record.previousCols ?? fallback.cols const rows = soft.record.previousRows ?? fallback.rows void this.enqueueLayout(ptyId, { kind: 'desktop', cols, rows }) } this.setDriver(ptyId, { kind: 'idle' }) } // (3) Immediate restore for PTYs where this client was the last // mobile subscriber. With multi-mobile, peer subscribers keep the // floor; only when the inner map empties do we transition to desktop. const ptysWithSurvivingPeers: string[] = [] const ptysToRestore: { ptyId: string; baseline: { cols: number; rows: number } | null }[] = [] for (const [ptyId, inner] of this.mobileSubscribers) { const subscriber = inner.get(clientId) if (!subscriber) { continue } // Snapshot baseline before deleting — needed once mobileSubscribers // entry is gone for the resolveDesktopRestoreTarget chain. const baseline = subscriber.previousCols != null && subscriber.previousRows != null ? { cols: subscriber.previousCols, rows: subscriber.previousRows } : null inner.delete(clientId) if (inner.size > 0) { ptysWithSurvivingPeers.push(ptyId) } else { this.mobileSubscribers.delete(ptyId) ptysToRestore.push({ ptyId, baseline }) } } for (const { ptyId, baseline } of ptysToRestore) { const cur = this.layouts.get(ptyId) // Why: Indefinite hold gate — see soft-leaver branch above. if (cur?.kind === 'phone' && this.getAutoRestoreFitMs() != null) { const fallback = this.resolveDesktopRestoreTarget(ptyId) const cols = baseline?.cols ?? fallback.cols const rows = baseline?.rows ?? fallback.rows void this.enqueueLayout(ptyId, { kind: 'desktop', cols, rows }) } this.setDriver(ptyId, { kind: 'idle' }) } // (4) Driver re-election where peers survived. If the disconnecting // client was the active driver, the most-recent surviving actor takes // the floor. for (const ptyId of ptysWithSurvivingPeers) { const driver = this.getDriver(ptyId) if (driver.kind !== 'mobile' || driver.clientId !== clientId) { continue } const inner = this.mobileSubscribers.get(ptyId) const next = inner ? this.pickMostRecentActor(inner) : null if (!next) { continue } this.setDriver(ptyId, { kind: 'mobile', clientId: next.clientId }) const mode = this.getMobileDisplayMode(ptyId) if (mode === 'desktop') { continue } const nextSub = inner!.get(next.clientId) const nextViewport = nextSub?.viewport if (!nextViewport) { continue } void this.enqueueLayout(ptyId, { kind: 'phone', cols: nextViewport.cols, rows: nextViewport.rows, ownerClientId: next.clientId }) } // (5) Legacy-callers fallback. Older mobile builds use resizeForClient // directly and never populate mobileSubscribers. For those PTYs the // override carries the owning clientId; restore the layout when the // owner disconnects. resolveDesktopRestoreTarget reads lastRendererSizes // (which the legacy mobile-fit branch stashes the pre-fit size into). for (const [ptyId, override] of this.terminalFitOverrides) { if (override.clientId !== clientId) { continue } if (this.mobileSubscribers.has(ptyId)) { continue } const cur = this.layouts.get(ptyId) if (cur?.kind !== 'phone') { continue } // Why: Indefinite hold gate — see soft-leaver branch above. Legacy // mobile clients (resizeForClient path) honor the same setting. if (this.getAutoRestoreFitMs() == null) { continue } const fallback = this.resolveDesktopRestoreTarget(ptyId) const cols = override.previousCols ?? fallback.cols const rows = override.previousRows ?? fallback.rows void this.enqueueLayout(ptyId, { kind: 'desktop', cols, rows }) } } onPtyExit(ptyId: string, exitCode: number): void { advertisedUrlWatcher.unbindPty(ptyId) serveSimStateWatcher.unbindPty(ptyId) // Clean up new mobile state for this PTY this.mobileSubscribers.delete(ptyId) this.mobileDisplayModes.delete(ptyId) this.resizeListeners.delete(ptyId) this.lastRendererSizes.delete(ptyId) this.recentPtyOutputById.delete(ptyId) this.ptyOutputSequenceById.delete(ptyId) this.agentStatusOscProcessorsByPtyId.delete(ptyId) this.oscTitleScanTailByPtyId.delete(ptyId) this.clearAgentRowSnapshotsForPty(ptyId) // Why: a Claude agent-team leader whose PTY exits naturally (agent finished, // process died, renderer reload) must release its team + nested panes map. // Previously only explicit closeTerminal evicted it, so natural exits leaked // one team per never-reused teamId for the runtime's lifetime. const exitedTeamLeaderHandle = this.handleByPtyId.get(ptyId) if (exitedTeamLeaderHandle) { this.claudeAgentTeams.removeTeamForLeaderHandle(exitedTeamLeaderHandle) } // Layout state machine: clear `layouts` and `layoutQueues`. Any // already-queued applyLayout work for this ptyId will run, but every // applyLayout re-checks `layouts.has(ptyId)` (or fresh-subscribe) and // short-circuits with `pty-exited`. this.layouts.delete(ptyId) this.layoutQueues.delete(ptyId) this.freshSubscribeGuard.delete(ptyId) const pendingRestore = this.pendingRestoreTimers.get(ptyId) if (pendingRestore) { clearTimeout(pendingRestore.timer) this.pendingRestoreTimers.delete(ptyId) } const pendingSoft = this.pendingSoftLeavers.get(ptyId) if (pendingSoft) { clearTimeout(pendingSoft.timer) this.pendingSoftLeavers.delete(ptyId) } if (this.terminalFitOverrides.has(ptyId)) { this.terminalFitOverrides.delete(ptyId) this.notifier?.terminalFitOverrideChanged(ptyId, 'desktop-fit', 0, 0) this.notifyFitOverrideListeners(ptyId, 'desktop-fit', 0, 0) } // Why: clear driver state and notify the renderer so any lock banner on // this dead pane unmounts. Without this, the pane shows a stuck banner // until tab teardown, and `getDriver(deadPtyId)` would keep returning a // stale `mobile{X}` to any caller that hasn't yet seen the exit IPC. if (this.currentDriver.has(ptyId)) { this.currentDriver.delete(ptyId) this.notifier?.terminalDriverChanged(ptyId, { kind: 'idle' }) } this.disposeHeadlessTerminal(ptyId) this.agentDetector?.onExit(ptyId) const pty = this.ptysById.get(ptyId) if (pty) { pty.connected = false pty.disconnectedAt = Date.now() pty.lastExitCode = exitCode this.resolvePtyExitWaiters(pty, ptyId) this.pruneDisconnectedPtyTranscript(pty) this.touchMobileSessionSnapshotsForPty(ptyId) } for (const leaf of this.getLeavesForPty(ptyId)) { this.detachedPreAllocatedLeaves.delete(ptyId) leaf.connected = false leaf.writable = false leaf.lastExitCode = exitCode this.resolveExitWaiters(leaf) this.failActiveDispatchOnExit(leaf, exitCode) } this.pruneDisconnectedPtyRecords() } // ─── Driver state (mobile-presence lock) ────────────────────────── // // See docs/mobile-presence-lock.md. getDriver(ptyId: string): DriverState { return this.currentDriver.get(ptyId) ?? { kind: 'idle' } } private setDriver(ptyId: string, next: DriverState): void { const prev = this.getDriver(ptyId) if (prev.kind === next.kind) { if (prev.kind === 'mobile' && next.kind === 'mobile' && prev.clientId === next.clientId) { return } if (prev.kind !== 'mobile' && next.kind !== 'mobile') { return } } if (next.kind === 'idle') { this.currentDriver.delete(ptyId) } else { this.currentDriver.set(ptyId, next) } this.notifier?.terminalDriverChanged(ptyId, next) const listeners = this.driverListeners.get(ptyId) if (listeners) { for (const listener of listeners) { listener(next) } } } markMobileActor(ptyId: string, clientId: string): void { const inner = this.mobileSubscribers.get(ptyId) const sub = inner?.get(clientId) if (sub) { sub.lastActedAt = Date.now() } this.setDriver(ptyId, { kind: 'mobile', clientId }) } // Why: invoked from mobile RPC method handlers (terminal.send / setDisplayMode / // resizeForClient / fresh subscribe with auto). Records the actor as the // most recent mobile driver and re-applies phone-fit if we were previously // in `desktop` mode (mobile reclaims a take-back). Mobile-to-mobile hand-offs // are no-ops for resize. async mobileTookFloor(ptyId: string, clientId: string): Promise { const inner = this.mobileSubscribers.get(ptyId) const sub = inner?.get(clientId) if (sub) { sub.lastActedAt = Date.now() } const prev = this.getDriver(ptyId) const currentMode = this.mobileDisplayModes.get(ptyId) // Why: a deliberate mobile action implies mobile is resuming control. // If the display mode is currently 'desktop' (set by an earlier // take-back), flip it back to 'auto' (= map absence) and re-apply so // phone-fit takes hold again. See docs/mobile-presence-lock.md. if (prev.kind === 'desktop' || currentMode === 'desktop') { if (currentMode === 'desktop') { this.mobileDisplayModes.delete(ptyId) } await this.applyMobileDisplayMode(ptyId) } this.setDriver(ptyId, { kind: 'mobile', clientId }) } // Why: in-place viewport update on the existing mobile subscription — // used when the mobile keyboard opens/closes and shrinks/grows the // visible terminal area. We refresh the subscriber's viewport, re-fit // the PTY to the new dims, and emit a 'resized' event so the mobile // xterm reinits inline at the new dims without re-subscribing. This // avoids the unsubscribe → resubscribe cycle which would (a) flash the // desktop lock banner during the brief idle gap and (b) cause the new // subscribe to capture the already-phone-fitted PTY size as its // restore baseline (stuck-dim bug on later disconnect). // No-op when the client isn't actually subscribed to this PTY. async updateMobileViewport( ptyId: string, clientId: string, viewport: { cols: number; rows: number } ): Promise<{ updated: boolean; applied: boolean }> { const inner = this.mobileSubscribers.get(ptyId) const sub = inner?.get(clientId) if (!sub) { return { updated: false, applied: false } } sub.viewport = viewport sub.lastActedAt = Date.now() const mode = this.getMobileDisplayMode(ptyId) if (mode === 'desktop') { // Watching at desktop dims — viewport is informational only. return { updated: true, applied: false } } // Drive PTY dims by the most-recent-actor (just updated to this client). const winner = this.pickMostRecentActor(inner!) if (!winner) { return { updated: false, applied: false } } const winnerSub = inner!.get(winner.clientId) const driveViewport = winnerSub?.viewport ?? viewport const { cols: clampedCols, rows: clampedRows } = clampTerminalViewport( driveViewport.cols, driveViewport.rows ) sub.wasResizedToPhone = true // The driver is already mobile{this client} when we got here; refresh // to update lastActedAt-based ordering on later actor selection. this.setDriver(ptyId, { kind: 'mobile', clientId }) const needsFreshSubscribeGuard = !this.layouts.has(ptyId) if (needsFreshSubscribeGuard) { this.freshSubscribeGuard.add(ptyId) } let result: ApplyLayoutResult try { result = await this.enqueueLayout(ptyId, { kind: 'phone', cols: clampedCols, rows: clampedRows, ownerClientId: winner.clientId }) } finally { if (needsFreshSubscribeGuard) { this.freshSubscribeGuard.delete(ptyId) } } return { updated: true, applied: result.ok } } // Why: remote desktop clients do not have the local `pty:resize` IPC path. // Their measured xterm size still has to resize the source PTY so TUIs // reflow to the visible client dimensions. async updateDesktopViewport( ptyId: string, viewport: { cols: number; rows: number } ): Promise { const { cols, rows } = clampTerminalViewport(viewport.cols, viewport.rows) if (this.terminalFitOverrides.has(ptyId)) { // Why: remote desktop panes do not have the local pty:reportGeometry // IPC. While phone-fit holds the PTY, treat their viewport RPC as a // measurement-only restore target, not a resize intent. this.recordRendererGeometry(ptyId, cols, rows) return true } if (this.isResizeSuppressed() || this.getDriver(ptyId).kind === 'mobile') { return false } let resized = false try { resized = this.ptyController?.resize?.(ptyId, cols, rows) ?? false } catch { return false } if (!resized) { return false } this.resizeHeadlessTerminal(ptyId, cols, rows) this.onExternalPtyResize(ptyId, cols, rows) return true } // Why: invoked from `runtime:restoreTerminalFit` IPC (the desktop "Take // back" / "Restore" button). Forces the PTY back to desktop dims and // flips the driver to `desktop`, suppressing further mobile-driven dim // changes until a mobile actor takes the floor again. Two cases: // 1. Active mobile subscriber: route through applyMobileDisplayMode so // the existing 'resized' event reaches the phone. // 2. Held with no mobile subscriber (post-indefinite-hold): no inner // subscriber to notify; resolve restore target and enqueueLayout // directly. applyLayout is the SOLE writer of terminalFitOverrides; // the held branch must not duplicate that mutation. See // docs/mobile-fit-hold.md. async reclaimTerminalForDesktop(ptyId: string): Promise { if (this.isMobileSubscriberActive(ptyId)) { this.setMobileDisplayMode(ptyId, 'desktop') await this.applyMobileDisplayMode(ptyId) this.setDriver(ptyId, { kind: 'desktop' }) // Why: a desktop-initiated reclaim is "I'm taking over right now", // not a sticky preference. The next mobile subscribe (e.g. user // switches back to the terminal tab on the phone) must default to // phone-fit again, not stay in passive desktop-watch mode. this.setMobileDisplayMode(ptyId, 'auto') return true } const heldOverride = this.terminalFitOverrides.get(ptyId) if (heldOverride) { const pending = this.pendingRestoreTimers.get(ptyId) if (pending) { clearTimeout(pending.timer) this.pendingRestoreTimers.delete(ptyId) } // Why: with no subscribers, resolveDesktopRestoreTarget can fall through // to current PTY size — which is at phone dims (wrong). Prefer a fresh // desktop renderer measurement when one exists; otherwise use the // override's pre-fit baseline before falling back to current size. const fallback = this.resolveDesktopRestoreTarget(ptyId) const renderer = this.lastRendererSizes.get(ptyId) const cols = renderer?.cols ?? heldOverride.previousCols ?? fallback.cols const rows = renderer?.rows ?? heldOverride.previousRows ?? fallback.rows await this.enqueueLayout(ptyId, { kind: 'desktop', cols, rows }) this.setDriver(ptyId, { kind: 'desktop' }) // Why: a desktop-initiated reclaim is "I'm taking over right now", // not a sticky preference. Reset to auto so the next mobile subscribe // re-enters phone-fit. (Held-PTY branch may not have an entry, but // calling setMobileDisplayMode('auto') is a no-op deletion in that // case — safe and idempotent.) this.setMobileDisplayMode(ptyId, 'auto') return true } return false } // Why: read-side clamp for mobileAutoRestoreFitMs. `null` means // indefinite hold (no auto-restore timer). A finite value is clamped // to [MIN, MAX] to defend against bad config — the smallest useful // value is a few seconds, the largest is one hour. See // docs/mobile-fit-hold.md. private getAutoRestoreFitMs(): number | null { const raw = this.store?.getSettings().mobileAutoRestoreFitMs ?? null if (raw == null) { return null } if (typeof raw !== 'number' || !Number.isFinite(raw)) { return null } return Math.min(Math.max(raw, MOBILE_AUTO_RESTORE_FIT_MIN_MS), MOBILE_AUTO_RESTORE_FIT_MAX_MS) } // Why: invoked when the user changes mobileAutoRestoreFitMs to `null` // (Indefinite). Clears every pending restore timer so the just-expressed // preference "do not auto-restore" is honored for ALL currently-pending // PTYs, not just one. See docs/mobile-fit-hold.md. cancelAllPendingFitRestoreTimers(): void { for (const [, entry] of this.pendingRestoreTimers) { clearTimeout(entry.timer) } this.pendingRestoreTimers.clear() } // Why: read the persisted user preference (clamped) for surfacing to UI // callers (mobile RPC, desktop preferences). Returns null when the // setting is unset or `null` ("Indefinite"). getMobileAutoRestoreFitMs(): number | null { return this.getAutoRestoreFitMs() } // Why: persisted-preference setter routed through the same `Store` the // desktop preferences UI writes to. Transitions to `null` (Indefinite) // clear every pending restore timer to honor the preference change for // already-held PTYs. Transitions to a finite value do NOT retroactively // schedule timers for PTYs that are currently held — those PTYs were // already-not-restored under the old preference, and silently scheduling // a restore on a settings change would be surprising. The new value // takes effect on the next unsubscribe. See docs/mobile-fit-hold.md. setMobileAutoRestoreFitMs(ms: number | null): number | null { if (!this.store?.updateSettings) { return this.getAutoRestoreFitMs() } let normalized: number | null if (ms == null) { normalized = null } else if (typeof ms !== 'number' || !Number.isFinite(ms)) { normalized = null } else { normalized = Math.min( Math.max(ms, MOBILE_AUTO_RESTORE_FIT_MIN_MS), MOBILE_AUTO_RESTORE_FIT_MAX_MS ) } this.store.updateSettings({ mobileAutoRestoreFitMs: normalized }, { notifyListeners: true }) if (normalized == null) { this.cancelAllPendingFitRestoreTimers() } return normalized } // Why: with multiple subscribers, the active phone-fit dims follow the // most recent mobile actor (argmax(lastActedAt)). See // docs/mobile-presence-lock.md "Active phone-fit dim selection". private pickMostRecentActor( inner: Map ): { clientId: string; lastActedAt: number } | null { let best: { clientId: string; lastActedAt: number } | null = null for (const sub of inner.values()) { if (best === null || sub.lastActedAt > best.lastActedAt) { best = sub } } return best } // Why: restore-target selection on last-subscriber-leaves picks the // earliest-by-subscribe-time subscriber AMONG those with non-null // previousCols/Rows. Desktop-mode joins carry null and are skipped — they // never captured pre-fit dims by design. private pickEarliestRestoreTarget( inner: Map< string, { subscribedAt: number; previousCols: number | null; previousRows: number | null } > ): { previousCols: number; previousRows: number } | null { let best: { subscribedAt: number; previousCols: number; previousRows: number } | null = null for (const sub of inner.values()) { if (sub.previousCols == null || sub.previousRows == null) { continue } if (best === null || sub.subscribedAt < best.subscribedAt) { best = { subscribedAt: sub.subscribedAt, previousCols: sub.previousCols, previousRows: sub.previousRows } } } return best ? { previousCols: best.previousCols, previousRows: best.previousRows } : null } // ─── Layout state machine ───────────────────────────────────────── // // See docs/mobile-terminal-layout-state-machine.md. // // applyLayout is the SOLE writer of: // - this.layouts // - this.terminalFitOverrides // - this.ptyController.resize (i.e. the actual PTY dims) // // Every trigger that wants to change PTY dims or flip mode goes through // enqueueLayout, which serializes calls behind a per-PTY async queue // (the await on ptyController.resize would otherwise let seq bumps reach // the wire out of order). getLayout(ptyId: string): PtyLayoutState | null { return this.layouts.get(ptyId) ?? null } // Why: `enqueueLayout`'s "no layouts entry" short-circuit must not fire // on the very first transition for a PTY (where the entry doesn't exist // yet *because* we're about to create it). handleMobileSubscribe adds // the ptyId to `freshSubscribeGuard` before calling enqueueLayout and // removes it in a finally block. private isFreshSubscribe(ptyId: string): boolean { return this.freshSubscribeGuard.has(ptyId) } // Why: four-step fallback chain for desktop-restore targets. Always // returns a value; the terminal {80,24} branch is reached only under // bug. Wrapping the chain as a single helper prevents callsite drift. private resolveDesktopRestoreTarget(ptyId: string): { cols: number; rows: number } { // 1. Earliest-by-subscribedAt subscriber with non-null baseline. const inner = this.mobileSubscribers.get(ptyId) if (inner) { const earliest = this.pickEarliestRestoreTarget(inner) if (earliest) { return { cols: earliest.previousCols, rows: earliest.previousRows } } } // 2. Most-recent desktop renderer geometry report. const renderer = this.lastRendererSizes.get(ptyId) if (renderer) { return { cols: renderer.cols, rows: renderer.rows } } // 3. Current PTY size. const size = this.getTerminalSize(ptyId) if (size) { return { cols: size.cols, rows: size.rows } } // 4. Hard default. return { cols: 80, rows: 24 } } // Why: a new viewport-only update from the same owner supersedes a // queued same-shape tail. Mode flips, owner changes, and take-back // append (losing a take-floor to a viewport tick would be a fairness // hole — see "enqueueLayout coalescing" in the design doc). private coalescesWith(prev: PtyLayoutTarget, next: PtyLayoutTarget): boolean { if (prev.kind !== next.kind) { return false } if (prev.kind === 'phone' && next.kind === 'phone') { return prev.ownerClientId === next.ownerClientId } return true } private enqueueLayout(ptyId: string, target: PtyLayoutTarget): Promise { // Why: PTY-exit short-circuit. Fresh-subscribe gate lets the very first // transition through even though `layouts` has no entry yet. if (!this.layouts.has(ptyId) && !this.isFreshSubscribe(ptyId)) { return Promise.resolve({ ok: false, reason: 'pty-exited' }) } let entry = this.layoutQueues.get(ptyId) if (!entry) { entry = { running: null, pending: [] } this.layoutQueues.set(ptyId, entry) } const queue = entry return new Promise((resolve) => { if (!queue.running) { queue.running = this.runLayoutSlot(ptyId, target, [resolve]) return } const tail = queue.pending.at(-1) if (tail && this.coalescesWith(tail.target, target)) { tail.target = target tail.waiters.push(resolve) return } queue.pending.push({ target, waiters: [resolve] }) }) } private async runLayoutSlot( ptyId: string, target: PtyLayoutTarget, waiters: ((r: ApplyLayoutResult) => void)[] ): Promise { let result: ApplyLayoutResult try { result = await this.applyLayout(ptyId, target) } catch (err) { // Why: defensive — applyLayout itself catches resize errors, but a // throw from one of the synchronous map writes (e.g. notifier hook) // must not jam the queue forever. console.error('[layout] applyLayout threw', { ptyId, err }) result = { ok: false, reason: 'resize-failed' } } for (const w of waiters) { w(result) } const queue = this.layoutQueues.get(ptyId) if (!queue) { return result } const next = queue.pending.shift() if (next) { queue.running = this.runLayoutSlot(ptyId, next.target, next.waiters) } else { queue.running = null // Why: drop the entry once empty so the map doesn't grow without bound // across short-lived PTYs. this.layoutQueues.delete(ptyId) } return result } private async applyLayout(ptyId: string, target: PtyLayoutTarget): Promise { // Why: re-check pty-exit at the head of the slot — the queue may have // accepted this target before onPtyExit ran. if (!this.layouts.has(ptyId) && !this.isFreshSubscribe(ptyId)) { return { ok: false, reason: 'pty-exited' } } const prev = this.layouts.get(ptyId) ?? null const seq = (prev?.seq ?? 0) + 1 const next: PtyLayoutState = { ...target, seq, appliedAt: Date.now() } const currentSize = this.getTerminalSize(ptyId) const dimsChanged = currentSize?.cols !== target.cols || currentSize?.rows !== target.rows const modeChanged = (prev?.kind ?? 'desktop') !== target.kind // Snapshot for rollback. const prevFitOverride = this.terminalFitOverrides.get(ptyId) ?? null // Tentative writes — the resize is the point of no return. this.layouts.set(ptyId, next) if (target.kind === 'phone') { // Why: pull baseline cols+rows atomically from the same subscriber so // they can't desync. const baseline = (() => { const inner = this.mobileSubscribers.get(ptyId) if (!inner) { return null } return this.pickEarliestRestoreTarget(inner) })() this.terminalFitOverrides.set(ptyId, { mode: 'mobile-fit', cols: target.cols, rows: target.rows, previousCols: baseline?.previousCols ?? null, previousRows: baseline?.previousRows ?? null, updatedAt: next.appliedAt, clientId: target.ownerClientId }) } else { this.terminalFitOverrides.delete(ptyId) } if (dimsChanged) { let ok = false try { const r = this.ptyController?.resize?.(ptyId, target.cols, target.rows) ok = r ?? true } catch (err) { console.error('[layout] ptyController.resize threw', { ptyId, err }) ok = false } if (!ok) { // Roll back to pre-call snapshot. seq is NOT bumped on the wire // because we never emit below. if (prev) { this.layouts.set(ptyId, prev) } else { this.layouts.delete(ptyId) } if (prevFitOverride) { this.terminalFitOverrides.set(ptyId, prevFitOverride) } else { this.terminalFitOverrides.delete(ptyId) } return { ok: false, reason: 'resize-failed' } } this.resizeHeadlessTerminal(ptyId, target.cols, target.rows) } // Why: emit fit-override-changed only when the *mode* flips. Layouts // can change dims without flipping mode (keyboard show/hide while // phone), and waking the renderer on every viewport tick is wasteful // churn. if (modeChanged) { // Why: phone→desktop arms the renderer-cascade suppress window // before the collateral safeFit IPCs arrive. See "Renderer cascade // suppression". if (target.kind === 'desktop') { this.lastRendererSizes.delete(ptyId) this.suppressResizesForMs(500) } this.notifier?.terminalFitOverrideChanged( ptyId, target.kind === 'phone' ? 'mobile-fit' : 'desktop-fit', target.cols, target.rows ) this.notifyFitOverrideListeners( ptyId, target.kind === 'phone' ? 'mobile-fit' : 'desktop-fit', target.cols, target.rows ) } // Mobile-facing event always fires (phone clients need to re-fit on // every dim change, not just mode flips). this.notifyTerminalResize(ptyId, { cols: target.cols, rows: target.rows, displayMode: target.kind === 'phone' ? 'phone' : 'desktop', reason: 'apply-layout', seq }) return { ok: true, state: next } } // ─── Server-Authoritative Mobile Display Mode ───────────────────── setMobileDisplayMode(ptyId: string, mode: 'auto' | 'desktop'): void { if (mode === 'auto') { this.mobileDisplayModes.delete(ptyId) } else { this.mobileDisplayModes.set(ptyId, mode) } } getMobileDisplayMode(ptyId: string): 'auto' | 'desktop' { return this.mobileDisplayModes.get(ptyId) ?? 'auto' } isMobileSubscriberActive(ptyId: string): boolean { const inner = this.mobileSubscribers.get(ptyId) return inner !== undefined && inner.size > 0 } // Why: late-bind viewport on an existing subscriber record. Subscribers // that registered before the mobile side measured (e.g. terminal first // mounted while the WebView was still loading) have null viewport, and // applyMobileDisplayMode's auto branch needs a viewport to phone-fit. // The setDisplayMode RPC carries the latest viewport so we can patch it // here just before applyMobileDisplayMode runs. updateMobileSubscriberViewport( ptyId: string, clientId: string, viewport: { cols: number; rows: number } ): void { const inner = this.mobileSubscribers.get(ptyId) const record = inner?.get(clientId) if (!record) { return } record.viewport = viewport } // Why: server-side auto-fit on mobile subscribe. The runtime is the single // source of truth — the mobile client just passes its viewport and the runtime // decides whether to resize. This eliminates the measure→RPC→resubscribe // pipeline that caused race conditions. // // Multi-mobile keying: each subscriber lives in `mobileSubscribers[ptyId]`'s // inner map under its own clientId. Phone B subscribing does not overwrite // phone A's record — both stay until each unsubscribes. // // Subscribe-in-desktop-mode rule: a subscribe with displayMode='desktop' is // a passive watch; it does NOT take the floor. The driver remains // `idle`/`desktop`. The lock banner is reserved for actual mobile // interaction (input/resize/setDisplayMode/auto-or-phone subscribe). async handleMobileSubscribe( ptyId: string, clientId: string, viewport?: { cols: number; rows: number } ): Promise { const mode = this.getMobileDisplayMode(ptyId) // Cancel pending restore timer for this ptyId — any new subscriber // supersedes any old client's pending restore. const pendingRestore = this.pendingRestoreTimers.get(ptyId) if (pendingRestore) { clearTimeout(pendingRestore.timer) this.pendingRestoreTimers.delete(ptyId) } // Resubscribe-grace honor: same client returning within soft-leave // window restores prior record (preserving baseline so we don't capture // phone-fitted dims as the new baseline). const softLeaver = this.pendingSoftLeavers.get(ptyId) if (softLeaver && softLeaver.clientId === clientId) { clearTimeout(softLeaver.timer) this.pendingSoftLeavers.delete(ptyId) let inner = this.mobileSubscribers.get(ptyId) if (!inner) { inner = new Map() this.mobileSubscribers.set(ptyId, inner) } inner.set(clientId, { ...softLeaver.record, viewport: viewport ?? null, lastActedAt: Date.now() }) if (!viewport) { return false } this.setDriver(ptyId, { kind: 'mobile', clientId }) if (mode !== 'desktop') { const { cols: clampedCols, rows: clampedRows } = clampTerminalViewport( viewport.cols, viewport.rows ) this.freshSubscribeGuard.add(ptyId) try { await this.enqueueLayout(ptyId, { kind: 'phone', cols: clampedCols, rows: clampedRows, ownerClientId: clientId }) } finally { this.freshSubscribeGuard.delete(ptyId) } } return true } let inner = this.mobileSubscribers.get(ptyId) if (!inner) { inner = new Map() this.mobileSubscribers.set(ptyId, inner) } // Capture restore baseline BEFORE applyLayout writes the override. // Multi-mobile: peer joiner against an already-fitted PTY captures null // — the existing baseline-holder's snapshot remains canonical. See // docs/mobile-presence-lock.md. // // Resubscribe-after-indefinite-hold: the held override carries the only // authoritative pre-fit dims across the no-subscriber gap. Inherit it // first; otherwise rendererSize/currentSize would be the held phone dims // and applyLayout would clobber the override's previousCols with phone // dims, making any subsequent Restore a no-op. const heldOverride = this.terminalFitOverrides.get(ptyId) const existing = inner.get(clientId) const someoneAlreadyFitted = [...inner.values()].some((s) => s.wasResizedToPhone) const currentSize = this.getTerminalSize(ptyId) const rendererSize = this.lastRendererSizes.get(ptyId) const previousCols = existing?.previousCols ?? heldOverride?.previousCols ?? (someoneAlreadyFitted ? null : (rendererSize?.cols ?? currentSize?.cols ?? null)) const previousRows = existing?.previousRows ?? heldOverride?.previousRows ?? (someoneAlreadyFitted ? null : (rendererSize?.rows ?? currentSize?.rows ?? null)) const now = Date.now() const subscribedAt = existing?.subscribedAt ?? now if (!viewport) { // Why: mobile can subscribe before its WebView has measured. Keep the // subscriber + desktop baseline so updateViewport/setDisplayMode can // late-bind the viewport without recapturing phone dims. inner.set(clientId, { clientId, viewport: null, wasResizedToPhone: false, previousCols, previousRows, subscribedAt, lastActedAt: now }) return false } const { cols: clampedCols, rows: clampedRows } = clampTerminalViewport( viewport.cols, viewport.rows ) if (mode === 'desktop') { // Passive watch — null baseline (we'll capture later if user toggles // to auto/phone, since safeFit will have converged by then). Do not // flip driver. inner.set(clientId, { clientId, viewport, wasResizedToPhone: false, previousCols: null, previousRows: null, subscribedAt, lastActedAt: now }) return false } inner.set(clientId, { clientId, viewport, wasResizedToPhone: true, previousCols, previousRows, subscribedAt, lastActedAt: now }) // Subscribe-fresh with auto/phone counts as "take the floor". this.setDriver(ptyId, { kind: 'mobile', clientId }) // Route the actual resize through the state machine. The fresh-subscribe // gate lets enqueueLayout's "no layouts entry" short-circuit pass on // the very first transition for this PTY. this.freshSubscribeGuard.add(ptyId) try { await this.enqueueLayout(ptyId, { kind: 'phone', cols: clampedCols, rows: clampedRows, ownerClientId: clientId }) } finally { this.freshSubscribeGuard.delete(ptyId) } return true } // Why: delayed restore prevents resize thrashing during rapid tab switches. // The 300ms debounce means only the final tab triggers a PTY restore; // intermediate terminals keep their current dims harmlessly. // // Multi-mobile: only the last subscriber leaving for this ptyId triggers // restore + driver=idle. Peer mobile clients still on the inner map keep // the lock banner mounted; if the disconnecting client was the active // driver, we re-elect the most-recent surviving subscriber. handleMobileUnsubscribe(ptyId: string, clientId: string): void { const inner = this.mobileSubscribers.get(ptyId) if (!inner) { return } const subscriber = inner.get(clientId) if (!subscriber) { return } const wasResizedToPhone = subscriber.wasResizedToPhone inner.delete(clientId) if (inner.size > 0) { // Why: if the leaving client was the only one with a non-null restore // baseline (typical when peer joiners subscribed against an // already-phone-fitted PTY and got null prevCols), donate the baseline // to the earliest surviving subscriber so a future last-leaver can // still restore correctly. See docs/mobile-presence-lock.md. if ( subscriber.previousCols != null && subscriber.previousRows != null && !this.pickEarliestRestoreTarget(inner) ) { let earliestSurvivor: { clientId: string; subscribedAt: number } | null = null for (const sub of inner.values()) { if (earliestSurvivor === null || sub.subscribedAt < earliestSurvivor.subscribedAt) { earliestSurvivor = { clientId: sub.clientId, subscribedAt: sub.subscribedAt } } } if (earliestSurvivor) { const heir = inner.get(earliestSurvivor.clientId) if (heir) { heir.previousCols = subscriber.previousCols heir.previousRows = subscriber.previousRows } } } // Peers still on the line. If the disconnecting client was the active // mobile driver, re-elect the most-recent surviving subscriber so the // banner remains correct and active phone-fit dims follow them. const driver = this.getDriver(ptyId) if (driver.kind === 'mobile' && driver.clientId === clientId) { const next = this.pickMostRecentActor(inner) if (next) { this.setDriver(ptyId, { kind: 'mobile', clientId: next.clientId }) // Fire-and-forget — handleMobileUnsubscribe stays sync; applyLayout // failures self-recover on the next gesture. void this.applyMobileDisplayMode(ptyId) } } return } // Last subscriber leaving — clean up. this.mobileSubscribers.delete(ptyId) const mode = this.getMobileDisplayMode(ptyId) // Resubscribe-grace: hold driver=mobile{clientId} for ~250ms so a quick // re-subscribe (older clients without updateViewport) doesn't flash the // desktop banner. See docs/mobile-presence-lock.md. const SOFT_LEAVE_GRACE_MS = 250 const existingSoft = this.pendingSoftLeavers.get(ptyId) if (existingSoft) { clearTimeout(existingSoft.timer) this.pendingSoftLeavers.delete(ptyId) } const softTimer = setTimeout(() => { this.pendingSoftLeavers.delete(ptyId) if (!this.mobileSubscribers.has(ptyId)) { this.setDriver(ptyId, { kind: 'idle' }) } }, SOFT_LEAVE_GRACE_MS) if (typeof softTimer.unref === 'function') { softTimer.unref() } this.pendingSoftLeavers.set(ptyId, { clientId, timer: softTimer, record: { clientId: subscriber.clientId, viewport: subscriber.viewport, wasResizedToPhone: subscriber.wasResizedToPhone, previousCols: subscriber.previousCols, previousRows: subscriber.previousRows, subscribedAt: subscriber.subscribedAt, lastActedAt: subscriber.lastActedAt } }) if (mode === 'auto' && wasResizedToPhone) { const existingTimer = this.pendingRestoreTimers.get(ptyId) if (existingTimer) { clearTimeout(existingTimer.timer) this.pendingRestoreTimers.delete(ptyId) } // Why: scheduling is conditional on the user's mobileAutoRestoreFitMs // preference. `null` (default, "Indefinite") leaves the PTY at phone // dims until the user clicks Restore on the desktop banner — the // central UX promise of docs/mobile-fit-hold.md. A finite value runs // the restore that long after the last unsubscribe. const autoRestoreMs = this.getAutoRestoreFitMs() if (autoRestoreMs == null) { // Indefinite hold: the fit override persists, the SOFT_LEAVE_GRACE // driver-state grace above still releases the input lock, and the // banner's Restore button is the explicit return path. } else { // Snapshot the disconnecting subscriber's baseline NOW, before the // timer fires. By the time the timer runs, the subscriber map has // been deleted; resolveDesktopRestoreTarget would fall through to // lastRendererSizes → current PTY size (which is at phone dims, // wrong). The disconnecting subscriber's baseline is the correct // restore target. const fallback = this.lastRendererSizes.get(ptyId) const restoreCols = subscriber.previousCols ?? fallback?.cols ?? this.getTerminalSize(ptyId)?.cols ?? 80 const restoreRows = subscriber.previousRows ?? fallback?.rows ?? this.getTerminalSize(ptyId)?.rows ?? 24 const timer = setTimeout(() => { this.pendingRestoreTimers.delete(ptyId) if (this.isMobileSubscriberActive(ptyId)) { return } void this.enqueueLayout(ptyId, { kind: 'desktop', cols: restoreCols, rows: restoreRows }) }, autoRestoreMs) // Why: a delayed mobile restore should not keep Electron main alive // after the last window/runtime transport has otherwise shut down. if (typeof timer.unref === 'function') { timer.unref() } this.pendingRestoreTimers.set(ptyId, { timer, clientId }) } } // 'desktop' mode: was never resized, nothing to restore. } // Why: called when mode changes via terminal.setDisplayMode. Applies the // mode change immediately if there's an active subscriber, and emits a // 'resized' event so the mobile client can reinitialize xterm inline. // // Multi-mobile: the most recent mobile actor's viewport drives the active // phone-fit dims. The earliest-by-subscribe-time subscriber's // previousCols/Rows drive the desktop-restore target. async applyMobileDisplayMode(ptyId: string): Promise { const mode = this.getMobileDisplayMode(ptyId) const inner = this.mobileSubscribers.get(ptyId) const subscriber = inner ? this.pickMostRecentActor(inner) : null const subscriberRecord = subscriber && inner ? inner.get(subscriber.clientId) : null if (mode === 'desktop') { // Reset wasResizedToPhone on every fitted subscriber so a future // toggle back to auto re-issues the resize. applyLayout owns the // actual PTY resize + override delete + renderer notify. let anyWasResized = false if (inner) { for (const sub of inner.values()) { if (sub.wasResizedToPhone) { anyWasResized = true sub.wasResizedToPhone = false } } } if (anyWasResized) { const restore = this.resolveDesktopRestoreTarget(ptyId) await this.enqueueLayout(ptyId, { kind: 'desktop', cols: restore.cols, rows: restore.rows }) } else { // No subscriber was fitted — emit a mode-change resize event so // the mobile client still learns the toggle landed. const size = this.getTerminalSize(ptyId) this.notifyTerminalResize(ptyId, { cols: size?.cols ?? 0, rows: size?.rows ?? 0, displayMode: 'desktop', reason: 'mode-change', seq: this.layouts.get(ptyId)?.seq }) } } else { // mode === 'auto' — the only non-desktop mode after the 'phone' // (sticky-fit) collapse. Phone-fit if the active subscriber has a // viewport and we haven't already applied it. if (subscriberRecord && !subscriberRecord.wasResizedToPhone) { const viewport = subscriberRecord.viewport if (viewport) { await this.handleMobileSubscribe(ptyId, subscriberRecord.clientId, viewport) return } } // Why: always emit the mode change even when no resize occurred — the // mobile client needs to learn the toggle landed even if dims didn't // actually change. Carry the current seq (or undefined if no layout // entry yet) so the mobile-side stale-event filter behaves correctly. const size = this.getTerminalSize(ptyId) this.notifyTerminalResize(ptyId, { cols: size?.cols ?? 0, rows: size?.rows ?? 0, displayMode: 'auto', reason: 'mode-change', seq: this.layouts.get(ptyId)?.seq }) } } // Why: called from the pty:resize IPC handler whenever the desktop renderer // resizes a PTY (e.g. via safeFit after window resize, split, or desktop-mode // restore). Stores the renderer-reported size so handleMobileSubscribe can use // the actual pane geometry instead of a stale PTY size for previousCols. // This is a passive geometry report — it does NOT call applyLayout; the // PTY is already at the reported size. onExternalPtyResize(ptyId: string, cols: number, rows: number): void { // The pty:resize IPC handler is supposed to gate via `isResizeSuppressed` // before calling here, but defend against callers that don't. if (this.isResizeSuppressed()) { return } // Why: while a mobile-fit override is in place, the desktop renderer's // safeFit echoes pty:resize(override.cols, override.rows). Treating that // echo as legitimate geometry would overwrite each subscriber's // previousCols/Rows baseline with phone dims, so the next take-back // enqueues a no-op {kind:'desktop', cols:49, rows:40} and leaves xterm // stuck. Only filter reports that EXACTLY match the override — a fresh // measurement from a now-visible pane (e.g. user activated a previously // hidden tab on desktop, container went 0×0 → 1782×1195) reports // different dims and is the right baseline to remember. const activeOverride = this.terminalFitOverrides.get(ptyId) if (activeOverride && activeOverride.cols === cols && activeOverride.rows === rows) { return } this.refreshRendererGeometry(ptyId, cols, rows) } // Why: pty:reportGeometry IPC sibling. The renderer calls this when a // desktop pane container goes from 0×0 to a real size while a mobile-fit // override is active (e.g. user activates a previously-hidden tab on // desktop after the phone has already taken the floor). We need the // restore-target baseline to track real desktop dims even during the // fit period — otherwise resolveDesktopRestoreTarget falls back to the // PTY's spawn default (typically 80×24) and Take Back leaves the // terminal partially restored. This is a measurement-only channel: it // refreshes lastRendererSizes and non-null subscriber baselines, never // resizes the PTY, and bypasses both isResizeSuppressed and the // override-echo gate by design — the renderer only fires it when it // has just measured fresh real geometry. See docs/mobile-fit-hold.md. recordRendererGeometry(ptyId: string, cols: number, rows: number): void { if (cols <= 0 || rows <= 0) { return } this.refreshRendererGeometry(ptyId, cols, rows) } // Why: test seam — exposes lastRendererSizes for assertions about // pty:reportGeometry / onExternalPtyResize side effects without making // the underlying Map writable from the outside. getLastRendererSize(ptyId: string): { cols: number; rows: number } | null { return this.lastRendererSizes.get(ptyId) ?? null } private refreshRendererGeometry(ptyId: string, cols: number, rows: number): void { this.lastRendererSizes.set(ptyId, { cols, rows }) const inner = this.mobileSubscribers.get(ptyId) if (!inner) { return } // Refresh the renderer-current size as the next-restore target on every // subscriber that already has a non-null baseline. Subscribers with null // baselines (joined while a peer had already phone-fitted) stay null. for (const sub of inner.values()) { if (sub.previousCols != null && sub.previousRows != null) { sub.previousCols = cols sub.previousRows = rows } } } // Why: the pty:resize IPC handler calls this to check if the global // suppress window is active. During this window, all desktop renderer // pty:resize events are ignored to prevent collateral safeFit corruption. isResizeSuppressed(): boolean { return Date.now() < this.resizeSuppressedUntil } private suppressResizesForMs(ms: number): void { this.resizeSuppressedUntil = Date.now() + ms } subscribeToTerminalResize( ptyId: string, listener: (event: { cols: number rows: number displayMode: string reason: string seq?: number }) => void ): () => void { return addListenerToMap(this.resizeListeners, ptyId, listener) } private notifyTerminalResize( ptyId: string, event: { cols: number; rows: number; displayMode: string; reason: string; seq?: number } ): void { const listeners = this.resizeListeners.get(ptyId) if (!listeners) { return } for (const listener of listeners) { listener(event) } } // Why: Section 7.2 — the runtime detects agent exit directly and updates // dispatch contexts immediately, rather than waiting for the coordinator's // next poll cycle. This catches agent crashes and unexpected exits within // milliseconds. The task is set back to 'pending' so it can be re-dispatched. private failActiveDispatchOnExit(leaf: RuntimeLeafRecord, exitCode: number): void { if (!this._orchestrationDb) { return } const handle = this.handleByLeafKey.get(this.getLeafKey(leaf.tabId, leaf.leafId)) if (!handle) { return } const dispatch = this._orchestrationDb.getActiveDispatchForTerminal(handle) if (!dispatch) { return } const errorContext = `Agent exited with code ${exitCode}` this._orchestrationDb.failDispatch(dispatch.id, errorContext) // Why: create an escalation message so the coordinator is notified about // the unexpected exit on its next check cycle, even if the circuit breaker // hasn't tripped yet. const run = this._orchestrationDb.getActiveCoordinatorRun() if (run) { this._orchestrationDb.insertMessage({ from: handle, to: run.coordinator_handle, subject: `Agent exited unexpectedly (code ${exitCode})`, type: 'escalation', priority: 'high', payload: JSON.stringify({ taskId: dispatch.task_id, exitCode, handle }) }) } } async listTerminals( worktreeSelector?: string, limit = DEFAULT_TERMINAL_LIST_LIMIT, opts: { requireFreshPtyLiveness?: boolean } = {} ): Promise { if (!Number.isInteger(limit) || limit <= 0) { throw new Error('invalid_limit') } const graphEpoch = this.graphStatus === 'ready' ? this.rendererGraphEpoch : null const explicitTargetWorktreeId = worktreeSelector ? getExplicitWorktreeIdSelector(worktreeSelector) : null const initialResolvedWorktreeCache = this.resolvedWorktreeCache const cachedResolvedWorktrees = initialResolvedWorktreeCache && initialResolvedWorktreeCache.expiresAt > Date.now() ? initialResolvedWorktreeCache.worktrees : null const cachedExplicitTargetWorktree = explicitTargetWorktreeId && cachedResolvedWorktrees ? (cachedResolvedWorktrees.find((worktree) => worktree.id === explicitTargetWorktreeId) ?? null) : null const parsedExplicitTargetWorktree = explicitTargetWorktreeId && !cachedExplicitTargetWorktree ? this.buildResolvedWorktreeFromId(explicitTargetWorktreeId) : null const targetWorktree = worktreeSelector && !explicitTargetWorktreeId ? await this.resolveWorktreeSelector(worktreeSelector) : (cachedExplicitTargetWorktree ?? parsedExplicitTargetWorktree) const targetWorktreeId = explicitTargetWorktreeId ?? targetWorktree?.id ?? null const classificationResolvedWorktreeCache = this.resolvedWorktreeCache const classificationResolvedWorktrees = targetWorktreeId && classificationResolvedWorktreeCache && classificationResolvedWorktreeCache.expiresAt > Date.now() ? includeTargetResolvedWorktree( classificationResolvedWorktreeCache.worktrees, targetWorktree ) : targetWorktreeId && explicitTargetWorktreeId ? this.listKnownResolvedWorktreesForExplicitTarget(targetWorktreeId, targetWorktree) : null const worktreesById = targetWorktreeId && targetWorktree ? new Map([[targetWorktree.id, targetWorktree]]) : targetWorktreeId ? new Map() : await this.getResolvedWorktreeMap() if (graphEpoch !== null) { this.assertStableReadyGraph(graphEpoch) } const resolvedWorktrees = targetWorktreeId && classificationResolvedWorktrees ? classificationResolvedWorktrees : targetWorktreeId && targetWorktree ? [targetWorktree] : targetWorktreeId ? [] : [...worktreesById.values()] const refreshedPtyLiveness = await this.refreshPtyWorktreeRecordsFromController( resolvedWorktrees, targetWorktreeId ) if (opts.requireFreshPtyLiveness && !refreshedPtyLiveness) { throw new Error('terminal_liveness_unavailable') } const livePtyWorktreeIds = new Set() for (const pty of this.ptysById.values()) { if (pty.connected) { livePtyWorktreeIds.add(pty.worktreeId) } } const terminals: RuntimeTerminalSummary[] = [] const ptyIdsFromLeaves = new Set() if (graphEpoch !== null) { for (const leaf of this.leaves.values()) { if (targetWorktreeId && leaf.worktreeId !== targetWorktreeId) { continue } if (opts.requireFreshPtyLiveness && leaf.ptyId && !refreshedPtyLiveness?.has(leaf.ptyId)) { continue } if (!leaf.ptyId && livePtyWorktreeIds.has(leaf.worktreeId)) { continue } if (leaf.ptyId) { ptyIdsFromLeaves.add(leaf.ptyId) } terminals.push(this.buildTerminalSummary(leaf, worktreesById)) } } // Why: worktree.ps can classify active worktrees from PTY records even when // the renderer graph is missing a leaf. terminal.list needs the same fallback // so mobile does not show a false "No terminals" create flow. for (const pty of this.ptysById.values()) { if (!pty.connected || ptyIdsFromLeaves.has(pty.ptyId)) { continue } if (opts.requireFreshPtyLiveness && !refreshedPtyLiveness?.has(pty.ptyId)) { continue } if (targetWorktreeId && pty.worktreeId !== targetWorktreeId) { continue } terminals.push(this.buildPtyTerminalSummary(pty, worktreesById)) } const listedTerminals = terminals.slice(0, limit) const visualLayouts = this.buildTerminalVisualLayouts( listedTerminals, worktreesById, targetWorktreeId ) return { terminals: listedTerminals, ...(visualLayouts.length > 0 ? { visualLayouts } : {}), totalCount: terminals.length, truncated: terminals.length > limit } } private buildTerminalVisualLayouts( terminals: RuntimeTerminalSummary[], worktreesById: Map, targetWorktreeId: string | null ): RuntimeTerminalVisualLayout[] { if (terminals.length === 0) { return [] } // Why: the mobile/session snapshot supplies topology, but terminal.list // must print the same handles in both the flat list and visual tree. const summariesByLeafKey = new Map( terminals.map((terminal) => [this.getLeafKey(terminal.tabId, terminal.leafId), terminal]) ) const summariesByWorktree = new Map() for (const terminal of terminals) { const existing = summariesByWorktree.get(terminal.worktreeId) if (existing) { existing.push(terminal) } else { summariesByWorktree.set(terminal.worktreeId, [terminal]) } } const snapshots = targetWorktreeId ? [this.mobileSessionTabsByWorktree.get(targetWorktreeId)].filter( (snapshot): snapshot is RuntimeMobileSessionTabsSnapshot => snapshot !== undefined ) : [...this.mobileSessionTabsByWorktree.values()] const layouts: RuntimeTerminalVisualLayout[] = [] for (const snapshot of snapshots) { const worktreeTerminals = summariesByWorktree.get(snapshot.worktree) if (!worktreeTerminals || worktreeTerminals.length === 0) { continue } const groups = this.buildTerminalVisualGroups(snapshot, summariesByLeafKey) if (groups.length === 0) { continue } const groupsById = new Map( groups .filter((group): group is RuntimeTerminalVisualGroupNode & { groupId: string } => Boolean(group.groupId) ) .map((group) => [group.groupId, group]) ) const root = this.buildTerminalVisualGroupLayout(snapshot.tabGroupLayout, groupsById) ?? groups[0] if (!root) { continue } const worktree = worktreesById.get(snapshot.worktree) layouts.push({ worktreeId: snapshot.worktree, worktreePath: worktree?.path ?? worktreeTerminals[0]?.worktreePath ?? '', root }) } return layouts } private buildTerminalVisualGroups( snapshot: RuntimeMobileSessionTabsSnapshot, summariesByLeafKey: ReadonlyMap ): RuntimeTerminalVisualGroupNode[] { const terminalTabs = snapshot.tabs.filter( (tab): tab is RuntimeMobileSessionTerminalTab => tab.type === 'terminal' ) if (terminalTabs.length === 0) { return [] } const tabsByParentId = new Map() const parentOrder: string[] = [] for (const tab of terminalTabs) { const existing = tabsByParentId.get(tab.parentTabId) if (existing) { existing.push(tab) } else { parentOrder.push(tab.parentTabId) tabsByParentId.set(tab.parentTabId, [tab]) } } const groupSources = snapshot.tabGroups && snapshot.tabGroups.length > 0 ? snapshot.tabGroups : [{ id: null, activeTabId: snapshot.activeTabId, tabOrder: parentOrder }] return groupSources .map((group): RuntimeTerminalVisualGroupNode | null => { const tabs = group.tabOrder .map((tabId) => { const surfaces = tabsByParentId.get(tabId) ?? terminalTabs.filter((tab) => tab.id === tabId) return this.buildTerminalVisualTab(tabId, surfaces, summariesByLeafKey) }) .filter((tab): tab is RuntimeTerminalVisualTab => tab !== null) if (tabs.length === 0) { return null } return { type: 'group', groupId: group.id, activeTabId: group.activeTabId, tabs } }) .filter((group): group is RuntimeTerminalVisualGroupNode => group !== null) } private buildTerminalVisualTab( tabId: string, surfaces: RuntimeMobileSessionTerminalTab[], summariesByLeafKey: ReadonlyMap ): RuntimeTerminalVisualTab | null { const firstSurface = surfaces[0] if (!firstSurface) { return null } const parentTabId = firstSurface.parentTabId const requestedActiveLeafId = firstSurface.parentLayout?.activeLeafId ?? surfaces.find((surface) => surface.isActive)?.leafId ?? firstSurface.leafId const root = firstSurface.parentLayout?.root ?? { type: 'leaf' as const, leafId: firstSurface.leafId } const visibleLeafIds = this.collectVisibleTerminalLeafIds(root, parentTabId, summariesByLeafKey) if (visibleLeafIds.length === 0) { return null } const activeLeafId = (requestedActiveLeafId && visibleLeafIds.includes(requestedActiveLeafId) ? requestedActiveLeafId : surfaces.find((surface) => surface.isActive && visibleLeafIds.includes(surface.leafId)) ?.leafId) ?? visibleLeafIds[0]! const panes = this.buildTerminalVisualPane(root, parentTabId, activeLeafId, summariesByLeafKey) if (!panes) { return null } return { tabId: parentTabId || tabId, title: this.tabs.get(parentTabId)?.title ?? firstSurface.title ?? null, activeLeafId, panes } } private collectVisibleTerminalLeafIds( node: TerminalPaneLayoutNode, tabId: string, summariesByLeafKey: ReadonlyMap ): string[] { if (node.type === 'leaf') { return summariesByLeafKey.has(this.getLeafKey(tabId, node.leafId)) ? [node.leafId] : [] } return [ ...this.collectVisibleTerminalLeafIds(node.first, tabId, summariesByLeafKey), ...this.collectVisibleTerminalLeafIds(node.second, tabId, summariesByLeafKey) ] } private buildTerminalVisualPane( node: TerminalPaneLayoutNode, tabId: string, activeLeafId: string | null, summariesByLeafKey: ReadonlyMap ): RuntimeTerminalVisualPaneNode | null { if (node.type === 'leaf') { const summary = summariesByLeafKey.get(this.getLeafKey(tabId, node.leafId)) if (!summary) { return null } return { type: 'terminal', handle: summary.handle, tabId: summary.tabId, leafId: summary.leafId, title: summary.title, connected: summary.connected, active: summary.leafId === activeLeafId } } const first = this.buildTerminalVisualPane(node.first, tabId, activeLeafId, summariesByLeafKey) const second = this.buildTerminalVisualPane( node.second, tabId, activeLeafId, summariesByLeafKey ) if (first && second) { return { type: 'pane-split', direction: node.direction, first, second } } return first ?? second } private buildTerminalVisualGroupLayout( node: TabGroupLayoutNode | null | undefined, groupsById: ReadonlyMap ): RuntimeTerminalVisualLayoutNode | null { if (!node) { return null } if (node.type === 'leaf') { return groupsById.get(node.groupId) ?? null } const first = this.buildTerminalVisualGroupLayout(node.first, groupsById) const second = this.buildTerminalVisualGroupLayout(node.second, groupsById) if (first && second) { return { type: 'split', direction: node.direction, first, second } } return first ?? second } // Why: when --terminal is omitted, the CLI auto-resolves to the active // terminal in the current worktree — matching browser's implicit active tab. async resolveActiveTerminal(worktreeSelector?: string): Promise { if (this.graphStatus !== 'ready') { const targetWorktreeId = worktreeSelector ? (await this.resolveWorktreeSelector(worktreeSelector)).id : null const snapshots = targetWorktreeId ? [this.getMobileSessionTabsForWorktree(targetWorktreeId)] : await this.listAllMobileSessionTabs() for (const snapshot of snapshots) { const activeTerminal = snapshot.tabs.find( (tab) => tab.type === 'terminal' && tab.isActive && tab.status === 'ready' && typeof tab.terminal === 'string' ) if (activeTerminal?.type === 'terminal' && activeTerminal.terminal) { return activeTerminal.terminal } } const listed = await this.listTerminals(worktreeSelector) const first = listed.terminals[0]?.handle if (first) { return first } throw new Error('no_active_terminal') } this.assertGraphReady() const targetWorktreeId = worktreeSelector ? (await this.resolveWorktreeSelector(worktreeSelector)).id : null // Prefer the tab's activeLeafId — this is the pane the user last focused for (const tab of this.tabs.values()) { if (targetWorktreeId && tab.worktreeId !== targetWorktreeId) { continue } if (!tab.activeLeafId) { continue } const leafKey = this.getLeafKey(tab.tabId, tab.activeLeafId) const leaf = this.leaves.get(leafKey) if (leaf) { return this.issueHandle(leaf) } } // Fallback: any leaf in the target worktree for (const leaf of this.leaves.values()) { if (targetWorktreeId && leaf.worktreeId !== targetWorktreeId) { continue } return this.issueHandle(leaf) } throw new Error('no_active_terminal') } resolveTerminalPane(paneKey: string): RuntimeTerminalResolvePane { // Why: the renderer context menu only knows the stable pane key; main owns // the runtime terminal handle that agents and CLI commands can address. const handle = this.getTerminalHandleForPaneKey(paneKey) if (!handle) { throw new Error('terminal_not_found') } const record = this.handles.get(handle) const parsed = parsePaneKey(paneKey) return { handle, tabId: record?.tabId ?? parsed?.tabId ?? '', leafId: record?.leafId ?? parsed?.leafId ?? '', ptyId: record?.ptyId ?? null } } async showTerminal(handle: string): Promise { const pty = this.getLivePtyForHandle(handle) if (pty) { const worktreesById = await this.getResolvedWorktreeMap() return { ...this.buildPtyTerminalSummary(pty.pty, worktreesById), tabId: pty.pty.tabId ?? pty.record.tabId, leafId: parsePaneKey(pty.pty.paneKey ?? '')?.leafId ?? pty.record.leafId, paneRuntimeId: -1, ptyId: pty.pty.ptyId, rendererGraphEpoch: this.rendererGraphEpoch } } const graphEpoch = this.captureReadyGraphEpoch() const worktreesById = await this.getResolvedWorktreeMap() this.assertStableReadyGraph(graphEpoch) const { leaf } = this.getLiveLeafForHandle(handle) const summary = this.buildTerminalSummary(leaf, worktreesById) return { ...summary, paneRuntimeId: leaf.paneRuntimeId, ptyId: leaf.ptyId, rendererGraphEpoch: this.rendererGraphEpoch } } async readTerminal( handle: string, opts: { cursor?: number; limit?: number } = {} ): Promise { const pty = this.getLivePtyForHandle(handle) if (pty) { const read = this.readPtyTerminal(handle, pty.pty, opts) return this.withVisibleSnapshotFallback(pty.pty.ptyId, read, opts) } const { leaf } = this.getLiveLeafForHandle(handle) const read = readTerminalTail({ handle, status: getTerminalState(leaf), completedLines: leaf.tailBuffer, partialLine: leaf.tailPartialLine, completedLineCount: leaf.tailLinesTotal, bufferTruncated: leaf.tailTruncated, cursor: opts.cursor, limit: opts.limit }) return leaf.ptyId ? this.withVisibleSnapshotFallback(leaf.ptyId, read, opts) : read } async sendTerminal( handle: string, action: { text?: string enter?: boolean interrupt?: boolean }, options: { beforeWrite?: (ptyId: string) => void | Promise suffixFailureError?: string } = {} ): Promise { const pty = this.getLivePtyForHandle(handle) if (pty) { if (!pty.pty.connected) { throw new Error('terminal_not_writable') } const payload = buildSendPayload(action) if (payload === null) { throw new Error('invalid_terminal_send') } await assertTerminalInputWithinLimitWithYield(action.text) await this.writeTerminalAction(pty.pty.ptyId, action, payload, options) return { handle, accepted: true, bytesWritten: Buffer.byteLength(payload, 'utf8') } } const { leaf } = this.getLiveLeafForHandle(handle) if (!leaf.writable || !leaf.ptyId) { throw new Error('terminal_not_writable') } const payload = buildSendPayload(action) if (payload === null) { throw new Error('invalid_terminal_send') } await assertTerminalInputWithinLimitWithYield(action.text) await this.writeTerminalAction(leaf.ptyId, action, payload, options) return { handle, accepted: true, bytesWritten: Buffer.byteLength(payload, 'utf8') } } async getTerminalAgentStatus(handle: string): Promise { const terminal = this.getTerminalAgentStatusSnapshot(handle) const explicitStatus = this.getFreshExplicitAgentStatusForHandle(handle) const blockedByWaitText = detectTerminalWaitBlockedReason(terminal.waitText) const liveTitleClearsBlockedText = terminal.titleStatusIsLive && terminal.titleStatus !== null && terminal.titleStatus !== 'permission' if (terminal.titleStatus === 'permission' && terminal.titleStatusIsLive) { return { handle, isRunningAgent: true, status: 'permission' } } if ( blockedByWaitText && !liveTitleClearsBlockedText && (!explicitStatus || explicitStatus.status === 'permission' || (terminal.waitBlockedAt !== null && terminal.waitBlockedAt >= explicitStatus.updatedAt)) ) { return { handle, isRunningAgent: true, status: 'permission' } } if (explicitStatus) { // Why: permission titles can linger after hooks report the agent resumed. // Fresh hook state is tighter, but current shell/management evidence wins. const isRunningAgent = !terminalTitleBlocksExplicitAgentStatus(terminal.title) && !(await this.terminalHasShellForegroundProcess(handle)) return { handle, isRunningAgent, status: isRunningAgent ? explicitStatus.status : null } } if (terminal.titleStatus) { return { handle, isRunningAgent: true, status: terminal.titleStatus } } return { handle, isRunningAgent: await this.isTerminalRunningAgent(handle), status: null } } private getTerminalAgentStatusSnapshot(handle: string): { waitText: string waitBlockedAt: number | null title: string | null titleStatus: AgentStatus | null titleStatusIsLive: boolean } { const pty = this.getLivePtyForHandle(handle) if (pty) { if (!pty.pty.connected) { throw new Error('terminal_gone') } const leaf = this.getPrimaryLeafForPty(pty.pty.ptyId) const leafTitle = leaf ? getLatestAgentCandidateTitleInfo( { title: leaf.paneTitle, updatedAt: leaf.paneTitleUpdatedAt }, { title: leaf.lastOscTitle, updatedAt: leaf.lastOscTitleAt } ) : null const ptyTitle = leafTitle ?? getLatestAgentCandidateTitleInfo( { title: pty.pty.title, updatedAt: pty.pty.titleUpdatedAt }, { title: pty.pty.lastOscTitle, updatedAt: pty.pty.lastOscTitleAt } ) const waitText = buildTerminalWaitText( pty.pty.tailBuffer, pty.pty.tailPartialLine, pty.pty.preview ) return { waitText, waitBlockedAt: pty.pty.waitBlockedAt, title: ptyTitle?.title ?? null, titleStatus: ptyTitle ? detectAgentStatusFromTitle(ptyTitle.title) : pty.pty.lastAgentStatus, titleStatusIsLive: ptyTitle !== null } } const { leaf } = this.getLiveLeafForHandle(handle) if (getTerminalState(leaf) !== 'running') { throw new Error('terminal_exited') } if (!leaf.ptyId) { throw new Error('terminal_gone') } const title = getLatestAgentCandidateTitleInfo( { title: leaf.paneTitle, updatedAt: leaf.paneTitleUpdatedAt }, { title: leaf.lastOscTitle, updatedAt: leaf.lastOscTitleAt }, { title: this.tabs.get(leaf.tabId)?.title, updatedAt: 0 } ) return { waitText: buildTerminalWaitText(leaf.tailBuffer, leaf.tailPartialLine, leaf.preview), waitBlockedAt: leaf.waitBlockedAt, title: title?.title ?? null, titleStatus: title ? detectAgentStatusFromTitle(title.title) : leaf.lastAgentStatus, titleStatusIsLive: (title?.updatedAt ?? 0) > 0 } } private async terminalHasShellForegroundProcess(handle: string): Promise { if (!this.ptyController) { return false } try { const pty = this.getLivePtyForHandle(handle) const ptyId = pty?.pty.ptyId ?? this.getLiveLeafForHandle(handle).leaf.ptyId if (!ptyId) { return false } const foregroundProcess = await this.ptyController.getForegroundProcess(ptyId) return foregroundProcess !== null && isShellProcess(foregroundProcess) } catch { return false } } /** * Schedules an asynchronous query to check which agent process is currently * running in the foreground of a PTY. */ private refreshPtyForegroundAgent(ptyId: string): void { void this.refreshPtyForegroundAgentFromController(ptyId) } /** * Deduplicates and manages in-flight foreground agent refresh queries * for a specific PTY. */ private refreshPtyForegroundAgentFromController(ptyId: string): Promise { const pendingRefresh = this.ptyForegroundAgentRefreshes.get(ptyId) if (pendingRefresh) { return pendingRefresh } const refresh = this.loadPtyForegroundAgentFromController(ptyId).finally(() => { this.ptyForegroundAgentRefreshes.delete(ptyId) }) this.ptyForegroundAgentRefreshes.set(ptyId, refresh) return refresh } /** * Queries the PTY controller for the active foreground process, identifies if it * is a recognized agent, and updates the PTY's foreground agent state if changed. */ private async loadPtyForegroundAgentFromController(ptyId: string): Promise { if (!this.ptyController) { return } const pty = this.ptysById.get(ptyId) if (!pty?.connected) { return } // Why: foregroundAgent is only consulted as the owner fallback when // launchAgent is unknown, so a known launchAgent makes the relay // getForegroundProcess round-trip pure waste (covers all launched agents). if (pty.launchAgent) { return } let foregroundProcess: string | null try { foregroundProcess = await this.ptyController.getForegroundProcess(ptyId) } catch { return } const foregroundAgent = foregroundProcess ? (recognizeAgentProcess(foregroundProcess)?.agent ?? null) : null if (pty.foregroundAgent === foregroundAgent) { return } pty.foregroundAgent = foregroundAgent this.touchMobileSessionSnapshotsForPty(ptyId) } private getFreshExplicitAgentStatusForHandle(handle: string): { status: NonNullable updatedAt: number } | null { const paneKey = this.getPaneKeyForTerminalHandle(handle) const now = Date.now() let bestStatus: NonNullable | null = null let bestUpdatedAt = -1 const consider = ( state: AgentStatusEntry['state'] | undefined, updatedAt: number | null | undefined ): void => { if (!state) { return } if (typeof updatedAt !== 'number' || now - updatedAt > AGENT_STATUS_STALE_AFTER_MS) { return } const status = mapExplicitAgentStateToRuntimeTerminalStatus(state) // Why: older retained permission rows can remain visible after the agent // resumes. Prefer the newest explicit state; only let permission win ties. if (updatedAt > bestUpdatedAt || (updatedAt === bestUpdatedAt && status === 'permission')) { bestStatus = status bestUpdatedAt = updatedAt } } if (paneKey) { const retained = this.latestAgentStatusByPaneKey.get(paneKey) consider(retained?.payload.state, retained?.updatedAt) } for (const entry of this.getAgentStatusSnapshotFn?.() ?? []) { if (entry.terminalHandle !== handle && (!paneKey || entry.paneKey !== paneKey)) { continue } consider(entry.state, entry.receivedAt) } return bestStatus ? { status: bestStatus, updatedAt: bestUpdatedAt } : null } private async writeTerminalAction( ptyId: string, action: { text?: string; enter?: boolean; interrupt?: boolean }, payload: string, options: { beforeWrite?: (ptyId: string) => void | Promise suffixFailureError?: string } = {} ): Promise { // Why: direct terminal.send can carry paste-sized text from RPC/mobile // clients; chunk text before PTY/ConPTY while preserving suffix separation. const hasText = typeof action.text === 'string' && action.text.length > 0 const hasSuffix = action.enter || action.interrupt if (hasText) { await this.writeTerminalInputChunks(ptyId, action.text!, options) } if (hasSuffix) { const suffix = (action.enter ? '\r' : '') + (action.interrupt ? '\x03' : '') if (hasText) { await new Promise((resolve) => setTimeout(resolve, 500)) } try { await options.beforeWrite?.(ptyId) } catch (error) { if (options.suffixFailureError) { throw new Error(options.suffixFailureError) } throw error } const suffixWrote = this.ptyController?.write(ptyId, suffix) ?? false if (!suffixWrote) { throw new Error(options.suffixFailureError ?? 'terminal_not_writable') } return } if (hasText) { return } await options.beforeWrite?.(ptyId) const wrote = this.ptyController?.write(ptyId, payload) ?? false if (!wrote) { throw new Error('terminal_not_writable') } } private async writeTerminalInputChunks( ptyId: string, text: string, options: { beforeWrite?: (ptyId: string) => void | Promise } = {} ): Promise { const chunks = iterateTerminalInputChunks(text) let chunk = chunks.next() while (!chunk.done) { await options.beforeWrite?.(ptyId) const wrote = this.ptyController?.write(ptyId, chunk.value) ?? false if (!wrote) { throw new Error('terminal_not_writable') } chunk = chunks.next() if (!chunk.done) { await new Promise((resolve) => setTimeout(resolve, 0)) } } } async waitForTerminal( handle: string, options?: { condition?: RuntimeTerminalWaitCondition timeoutMs?: number signal?: AbortSignal } ): Promise { const condition = options?.condition ?? 'exit' const pty = this.getLivePtyForHandle(handle) if (pty) { if (condition === 'exit' && !pty.pty.connected) { return buildPtyTerminalWaitResult(handle, condition, pty.pty) } const ptyWaitText = buildTerminalWaitText( pty.pty.tailBuffer, pty.pty.tailPartialLine, pty.pty.preview ) const ptyBlockedReason = detectTerminalWaitBlockedReason(ptyWaitText) if (condition === 'tui-idle' && ptyBlockedReason) { return buildPtyTerminalWaitBlockedResult(handle, condition, pty.pty, ptyBlockedReason) } if (condition === 'tui-idle' && pty.pty.lastAgentStatus === 'idle') { return buildPtyTerminalWaitResult(handle, condition, pty.pty) } if ( condition === 'tui-idle' && (this.getAdoptedPtyExplicitIdleStatus(pty.pty) === 'idle' || isKnownReadyPromptPreview(ptyWaitText)) ) { return buildPtyTerminalWaitResult(handle, condition, pty.pty) } return await new Promise((resolve, reject) => { const effectiveTimeoutMs = typeof options?.timeoutMs === 'number' && options.timeoutMs > 0 ? options.timeoutMs : condition === 'tui-idle' ? TUI_IDLE_DEFAULT_TIMEOUT_MS : 0 const waiter: TerminalWaiter = { handle, condition, resolve, reject, timeout: null, pollInterval: null, abortCleanup: null } if (!this.bindTerminalWaiterAbort(waiter, options?.signal)) { reject(new Error('request_aborted')) return } if (effectiveTimeoutMs > 0) { waiter.timeout = setTimeout(() => { this.removeWaiter(waiter) reject(new Error('timeout')) }, effectiveTimeoutMs) } let waiters = this.waitersByHandle.get(handle) if (!waiters) { waiters = new Set() this.waitersByHandle.set(handle, waiters) } waiters.add(waiter) const live = this.getLivePtyForHandle(handle) if (!live) { this.removeWaiter(waiter) reject(new Error('terminal_handle_stale')) } else if (condition === 'exit' && !live.pty.connected) { this.resolveWaiter(waiter, buildPtyTerminalWaitResult(handle, condition, live.pty)) } else if (condition === 'tui-idle') { const livePtyWaitText = buildTerminalWaitText( live.pty.tailBuffer, live.pty.tailPartialLine, live.pty.preview ) const blockedReason = detectTerminalWaitBlockedReason(livePtyWaitText) if (blockedReason) { this.resolveWaiter( waiter, buildPtyTerminalWaitBlockedResult(handle, condition, live.pty, blockedReason) ) } else if (live.pty.lastAgentStatus === 'idle') { this.resolveWaiter(waiter, buildPtyTerminalWaitResult(handle, condition, live.pty)) } else if ( this.getAdoptedPtyExplicitIdleStatus(live.pty) === 'idle' || isKnownReadyPromptPreview(livePtyWaitText) ) { this.resolveWaiter(waiter, buildPtyTerminalWaitResult(handle, condition, live.pty)) } else { this.startPtyTuiIdleFallbackPoll(waiter, live.pty) } } }) } const { leaf } = this.getLiveLeafForHandle(handle) if (condition === 'exit' && getTerminalState(leaf) === 'exited') { return buildTerminalWaitResult(handle, condition, leaf) } const leafWaitText = buildTerminalWaitText(leaf.tailBuffer, leaf.tailPartialLine, leaf.preview) const leafBlockedReason = detectTerminalWaitBlockedReason(leafWaitText) if (condition === 'tui-idle' && leafBlockedReason) { return buildTerminalWaitBlockedResult(handle, condition, leaf, leafBlockedReason) } // Why: if the agent already transitioned to idle (or permission) before the // waiter was registered, resolve immediately. This uses the same OSC title // detection that powers the renderer's "Task complete" notifications. // Why: only 'idle' satisfies tui-idle, not 'permission'. Permission means the // agent is blocked on user approval, not finished with its task. if (condition === 'tui-idle' && leaf.lastAgentStatus === 'idle') { return buildTerminalWaitResult(handle, condition, leaf) } if (condition === 'tui-idle') { const fastPathTitle = leaf.paneTitle ?? this.tabs.get(leaf.tabId)?.title if ( (fastPathTitle && detectExplicitIdleStatusFromTitle(fastPathTitle) === 'idle') || isKnownReadyPromptPreview(leafWaitText) ) { return buildTerminalWaitResult(handle, condition, leaf) } } return await new Promise((resolve, reject) => { // Why: tui-idle depends on OSC title transitions from a recognized agent. // If no agent is detected, the waiter would hang forever. Enforce a default // timeout so unsupported CLIs fail predictably instead of silently blocking. const effectiveTimeoutMs = typeof options?.timeoutMs === 'number' && options.timeoutMs > 0 ? options.timeoutMs : condition === 'tui-idle' ? TUI_IDLE_DEFAULT_TIMEOUT_MS : 0 const waiter: TerminalWaiter = { handle, condition, resolve, reject, timeout: null, pollInterval: null, abortCleanup: null } if (!this.bindTerminalWaiterAbort(waiter, options?.signal)) { reject(new Error('request_aborted')) return } if (effectiveTimeoutMs > 0) { waiter.timeout = setTimeout(() => { this.removeWaiter(waiter) reject(new Error('timeout')) }, effectiveTimeoutMs) } let waiters = this.waitersByHandle.get(handle) if (!waiters) { waiters = new Set() this.waitersByHandle.set(handle, waiters) } waiters.add(waiter) // Why: the handle may go stale or exit in the small gap between the first // validation and waiter registration. Re-checking here keeps wait --for // exit honest instead of hanging on a terminal that already changed. try { const live = this.getLiveLeafForHandle(handle) if (getTerminalState(live.leaf) === 'exited') { this.resolveWaiter(waiter, buildTerminalWaitResult(handle, condition, live.leaf)) } else if (condition === 'tui-idle') { const liveLeafWaitText = buildTerminalWaitText( live.leaf.tailBuffer, live.leaf.tailPartialLine, live.leaf.preview ) const blockedReason = detectTerminalWaitBlockedReason(liveLeafWaitText) if (blockedReason) { this.resolveWaiter( waiter, buildTerminalWaitBlockedResult(handle, condition, live.leaf, blockedReason) ) } else if (live.leaf.lastAgentStatus === 'idle') { // Why: don't clear lastAgentStatus here. It's a factual record of the // last detected OSC state, not a one-shot signal. Clearing it causes // subsequent tui-idle waiters to hang even though the agent is idle — // the first waiter consumes the status and all later ones see null. this.resolveWaiter(waiter, buildTerminalWaitResult(handle, condition, live.leaf)) } else { // Why: renderer-synced previews can show a known ready prompt even // while the last OSC title is still "working"; keep polling the // preview/title until the waiter resolves or hits its timeout. const fastPathTitle = live.leaf.paneTitle ?? this.tabs.get(live.leaf.tabId)?.title if ( (fastPathTitle && detectExplicitIdleStatusFromTitle(fastPathTitle) === 'idle') || isKnownReadyPromptPreview(liveLeafWaitText) ) { this.resolveWaiter(waiter, buildTerminalWaitResult(handle, condition, live.leaf)) } else { this.startTuiIdleFallbackPoll(waiter, live.leaf) } } } } catch (error) { this.removeWaiter(waiter) reject(error instanceof Error ? error : new Error(String(error))) } }) } async getWorktreePs(limit = DEFAULT_WORKTREE_PS_LIMIT): Promise<{ worktrees: RuntimeWorktreePsSummary[] totalCount: number truncated: boolean }> { if (!Number.isInteger(limit) || limit <= 0) { throw new Error('invalid_limit') } const resolvedWorktrees = (await this.listResolvedWorktrees()).filter((worktree) => this.isRuntimeWorktreeVisible(worktree) ) // Why: worktree.ps backs the mobile sidebar, so it must use the same // host-owned imported-worktree visibility gate as worktree.list/desktop. await this.refreshPtyWorktreeRecordsFromController(resolvedWorktrees) const repoById = new Map((this.store?.getRepos() ?? []).map((repo) => [repo.id, repo])) const summaries = new Map() // Why: the GitHub cache is keyed by `repoPath::branch` (no refs/heads/ prefix), // matching how the renderer's fetchPRForBranch stores entries. We look up cached // PR info so mobile clients can group worktrees by PR state without making // expensive `gh` CLI calls. Falls back to meta.linkedPR if no cache entry exists. const ghCache = this.store?.getGitHubCache?.() for (const worktree of resolvedWorktrees) { const meta = this.store?.getWorktreeMeta?.(worktree.id) ?? this.store?.getAllWorktreeMeta()[worktree.id] const repo = repoById.get(worktree.repoId) let linkedPR: { number: number; state: string } | null = null const branch = worktree.branch.replace(/^refs\/heads\//, '') if (branch && ghCache) { // Why: the renderer keys the PR cache by `repoId::branch` (getGitHubPRCacheKey // prefers repo.id over repo.path), so read by id first and fall back to path // for legacy/path-keyed entries. Reading only by path missed every cached // entry, leaving mobile's linked-PR badge stuck on the 'unknown' fallback. const cached = (repo?.id ? ghCache.pr[`${repo.id}::${branch}`] : undefined) ?? (repo?.path ? ghCache.pr[`${repo.path}::${branch}`] : undefined) if (cached?.data) { linkedPR = { number: cached.data.number, state: cached.data.state } } } if (!linkedPR && meta?.linkedPR != null) { linkedPR = { number: meta.linkedPR, state: 'unknown' } } summaries.set(worktree.id, { // Why: mobile mirrors desktop workspace grouping/order from persisted // metadata, while older runtimes may not have hydrated every field yet. workspaceKind: 'git', worktreeId: worktree.id, repoId: worktree.repoId, repo: repo?.displayName ?? worktree.repoId, path: worktree.path, branch: worktree.branch, isArchived: worktree.isArchived, isMainWorktree: worktree.isMainWorktree, hasHostSidebarActivity: false, parentWorktreeId: worktree.parentWorktreeId, childWorktreeIds: worktree.childWorktreeIds, displayName: worktree.displayName, workspaceStatus: meta?.workspaceStatus ?? DEFAULT_WORKSPACE_STATUS_ID, sortOrder: meta?.sortOrder ?? 0, ...(meta?.manualOrder !== undefined ? { manualOrder: meta.manualOrder } : {}), linkedIssue: worktree.linkedIssue, linkedPR, linkedLinearIssue: meta?.linkedLinearIssue ?? null, linkedGitLabMR: meta?.linkedGitLabMR ?? null, linkedGitLabIssue: meta?.linkedGitLabIssue ?? null, comment: meta?.comment ?? '', isPinned: meta?.isPinned ?? false, isActive: false, unread: meta?.isUnread ?? false, liveTerminalCount: 0, hasAttachedPty: false, lastOutputAt: null, preview: '', status: 'inactive', agents: [] }) } const projectGroupById = new Map( (this.store?.getProjectGroups?.() ?? []).map((group) => [group.id, group]) ) for (const folderWorkspace of this.store?.getFolderWorkspaces?.() ?? []) { const projectGroup = projectGroupById.get(folderWorkspace.projectGroupId) if (!projectGroup?.parentPath) { continue } const worktree = folderWorkspaceToWorktree(folderWorkspace) summaries.set(worktree.id, { // Why: folder workspaces use the same mobile grouping/order contract as // git worktrees, but legacy records may be missing order metadata. workspaceKind: 'folder-workspace', worktreeId: worktree.id, repoId: worktree.repoId, repo: projectGroup.name, path: worktree.path, branch: worktree.branch, isArchived: worktree.isArchived, isMainWorktree: worktree.isMainWorktree, hasHostSidebarActivity: false, parentWorktreeId: null, childWorktreeIds: [], displayName: worktree.displayName, workspaceStatus: worktree.workspaceStatus ?? DEFAULT_WORKSPACE_STATUS_ID, sortOrder: worktree.sortOrder ?? 0, ...(worktree.manualOrder !== undefined ? { manualOrder: worktree.manualOrder } : {}), linkedIssue: worktree.linkedIssue ?? null, linkedPR: null, linkedLinearIssue: worktree.linkedLinearIssue ?? null, linkedGitLabMR: worktree.linkedGitLabMR ?? null, linkedGitLabIssue: worktree.linkedGitLabIssue ?? null, comment: worktree.comment, isPinned: worktree.isPinned, isActive: false, unread: worktree.isUnread, liveTerminalCount: 0, hasAttachedPty: false, lastOutputAt: null, preview: '', status: 'inactive', agents: [] }) } const countedPtyIds = new Set() for (const leaf of this.leaves.values()) { const summary = this.getSummaryForRuntimeWorktreeId( summaries, resolvedWorktrees, leaf.worktreeId ) if (!summary) { continue } if (leaf.ptyId) { countedPtyIds.add(leaf.ptyId) } if (leaf.ptyId && leaf.connected) { summary.hasHostSidebarActivity = true } const previousLastOutputAt = summary.lastOutputAt summary.liveTerminalCount += 1 summary.hasAttachedPty = summary.hasAttachedPty || leaf.connected summary.lastOutputAt = maxTimestamp(summary.lastOutputAt, leaf.lastOutputAt) summary.status = mergeWorktreeStatus( summary.status, getLeafWorktreeStatus(leaf, this.tabs.get(leaf.tabId)?.title ?? null) ) if ( leaf.preview && (summary.preview.length === 0 || (leaf.lastOutputAt ?? -1) >= (previousLastOutputAt ?? -1)) ) { summary.preview = leaf.preview } } for (const pty of this.ptysById.values()) { if (!pty.connected || countedPtyIds.has(pty.ptyId)) { continue } const summary = this.getSummaryForRuntimeWorktreeId( summaries, resolvedWorktrees, pty.worktreeId ) if (!summary) { continue } const previousLastOutputAt = summary.lastOutputAt summary.liveTerminalCount += 1 summary.hasAttachedPty = true summary.lastOutputAt = maxTimestamp(summary.lastOutputAt, pty.lastOutputAt) summary.status = mergeWorktreeStatus(summary.status, 'active') if ( pty.preview && (summary.preview.length === 0 || (pty.lastOutputAt ?? -1) >= (previousLastOutputAt ?? -1)) ) { summary.preview = pty.preview } } const session = this.store?.getWorkspaceSession?.() for (const [worktreeId, tabs] of Object.entries(session?.tabsByWorktree ?? {})) { if (tabs.length === 0) { continue } const summary = this.getSummaryForRuntimeWorktreeId(summaries, resolvedWorktrees, worktreeId) if (!summary) { continue } // Why: desktop can show terminal tabs that are not mounted as renderer // leaves and are not currently visible in the PTY provider list. Mobile // still needs those worktrees to show as terminal-bearing entries. summary.liveTerminalCount = Math.max(summary.liveTerminalCount, tabs.length) summary.hasAttachedPty = summary.hasAttachedPty || tabs.some((tab) => tab.ptyId !== null) if (tabs.some((tab) => tab.ptyId !== null && this.ptysById.get(tab.ptyId)?.connected)) { summary.hasHostSidebarActivity = true } for (const tab of tabs) { summary.status = mergeWorktreeStatus( summary.status, getSavedTabWorktreeStatus(tab.title, tab.ptyId !== null) ) } } // Why: surface the desktop's focused worktree so mobile can scroll it into // view and highlight it. Resolve through getSummaryForRuntimeWorktreeId so // SSH/remote path-projected ids match the same way tabsByWorktree does. if (session?.activeWorktreeId) { const activeSummary = this.getSummaryForRuntimeWorktreeId( summaries, resolvedWorktrees, session.activeWorktreeId ) if (activeSummary) { activeSummary.isActive = true } } this.attachAgentRowsToSummaries(summaries) const sorted = [...summaries.values()].sort(compareWorktreePs) return { worktrees: sorted.slice(0, limit), totalCount: sorted.length, truncated: sorted.length > limit } } // Why: maps the retained per-pane agent snapshots into each worktree's inline // agent list, mirroring the desktop sidebar. Lineage parent is resolved from // the orchestration db (paneKey-keyed), not the OSC payload, since spawn // hierarchy is pane-level state tracked separately from terminal output. private attachAgentRowsToSummaries(summaries: Map): void { // Why: most agents report via hooks (agent-hooks/server), not OSC, so the // hook snapshot is the primary source — same one the desktop sidebar reads. // OSC-only entries (no hook) are merged in as a fallback, keyed by paneKey. const rowSources = new Map< string, { paneKey: string worktreeId?: string state: ParsedAgentStatusPayload['state'] agentType: string | null prompt: string lastAssistantMessage: string | null toolName: string | null toolInput: string | null interrupted: boolean stateStartedAt: number updatedAt: number } >() for (const snapshot of this.latestAgentStatusByPaneKey.values()) { const { payload } = snapshot rowSources.set(snapshot.paneKey, { paneKey: snapshot.paneKey, worktreeId: snapshot.worktreeId, state: payload.state, agentType: payload.agentType ?? null, prompt: payload.prompt, lastAssistantMessage: payload.lastAssistantMessage ?? null, toolName: payload.toolName ?? null, toolInput: payload.toolInput ?? null, interrupted: payload.interrupted ?? false, stateStartedAt: snapshot.stateStartedAt, updatedAt: snapshot.updatedAt }) } for (const entry of this.getAgentStatusSnapshotFn?.() ?? []) { rowSources.set(entry.paneKey, { paneKey: entry.paneKey, worktreeId: entry.worktreeId, state: entry.state, agentType: entry.agentType ?? null, prompt: entry.prompt, lastAssistantMessage: entry.lastAssistantMessage ?? null, toolName: entry.toolName ?? null, toolInput: entry.toolInput ?? null, interrupted: entry.interrupted ?? false, stateStartedAt: entry.stateStartedAt, updatedAt: entry.receivedAt }) } if (rowSources.size === 0) { return } const orchestrationByPaneKey = this.buildAgentOrchestrationByPaneKey() const rowsByWorktree = new Map() for (const src of rowSources.values()) { const worktreeId = src.worktreeId if (!worktreeId || !summaries.has(worktreeId)) { continue } const taskTitle = orchestrationByPaneKey?.[src.paneKey]?.taskTitle ?? null const displayName = orchestrationByPaneKey?.[src.paneKey]?.displayName ?? null const row: RuntimeWorktreeAgentRow = { paneKey: src.paneKey, parentPaneKey: orchestrationByPaneKey?.[src.paneKey]?.parentPaneKey ?? null, state: src.state, agentType: src.agentType, prompt: src.prompt, taskTitle, displayName, lastAssistantMessage: src.lastAssistantMessage, toolName: src.toolName, toolInput: src.toolInput, interrupted: src.interrupted, stateStartedAt: src.stateStartedAt, updatedAt: src.updatedAt } const rows = rowsByWorktree.get(worktreeId) if (rows) { rows.push(row) } else { rowsByWorktree.set(worktreeId, [row]) } } for (const [worktreeId, rows] of rowsByWorktree) { // Oldest-started first, matching the desktop dashboard's start-order sort. rows.sort((a, b) => a.stateStartedAt - b.stateStartedAt) const summary = summaries.get(worktreeId) if (summary) { summary.agents = rows } } } listRepos(): Repo[] { return this.store?.getRepos() ?? [] } enrichMissingRepoGitRemoteIdentities(): void { if (!this.store) { return } enrichMissingRepoGitRemoteIdentities(this.store, { onChanged: () => { this.invalidateResolvedWorktreeCache() this.notifyReposChanged() } }) } listProjects(): Project[] { return this.store?.getProjects?.() ?? [] } updateProject(projectId: string, updates: ProjectUpdateArgs['updates']): Project { if (!this.store?.updateProject) { throw new Error('runtime_unavailable') } const project = this.store.updateProject(projectId, updates) if (!project) { throw new Error(`Project not found: ${projectId}`) } this.invalidateResolvedWorktreeCache() this.notifyReposChanged() return project } listProjectHostSetups(): ProjectHostSetup[] { return this.store?.getProjectHostSetups?.() ?? [] } createProjectHostSetup(args: ProjectHostSetupCreateArgs): ProjectHostSetupCreateResult { if (!this.store?.createProjectHostSetup) { throw new Error('runtime_unavailable') } const result = this.store.createProjectHostSetup(args) if (!result) { throw new Error(`Project not found: ${args.projectId}`) } return result } async setupProjectExistingFolder( args: ProjectHostSetupExistingFolderArgs ): Promise { if (!this.store) { throw new Error('runtime_unavailable') } let repo = await this.addRepo(args.path, args.kind === 'folder' ? 'folder' : 'git') let setup = getProjectHostSetupForRepo(this.listProjectHostSetups(), repo) if (setup.projectId !== args.projectId) { const existingProject = this.listProjects().find((project) => project.id === args.projectId) if ( !existingProject?.providerIdentity || existingProject.providerIdentity.provider !== 'github' ) { throw new Error('Imported folder does not match the selected project identity.') } const updated = this.store.updateRepo(repo.id, { upstream: { owner: existingProject.providerIdentity.owner, repo: existingProject.providerIdentity.repo } }) if (!updated) { throw new Error(`Project setup repo disappeared before it could be linked: ${repo.id}`) } repo = updated setup = getProjectHostSetupForRepo(this.listProjectHostSetups(), repo) } const setupMethod = args.setupMethod ?? 'imported-existing-folder' const updated = this.store.updateRepo(repo.id, { projectHostSetupMethod: setupMethod }) if (!updated) { throw new Error( `Project setup repo disappeared before setup metadata could be linked: ${repo.id}` ) } repo = updated setup = getProjectHostSetupForRepo(this.listProjectHostSetups(), repo) const project = this.listProjects().find((entry) => entry.id === setup.projectId) if (!project) { throw new Error(`Project setup was created without a project record: ${setup.projectId}`) } return { project, setup, repo } } async setupProjectClone(args: ProjectHostSetupCloneArgs): Promise { const repo = await this.cloneRepo(args.url, args.destination) return await this.setupProjectExistingFolder({ projectId: args.projectId, hostId: args.hostId, path: repo.path, kind: 'git', displayName: args.displayName, setupMethod: 'cloned' }) } updateProjectHostSetup(args: ProjectHostSetupUpdateArgs): ProjectHostSetupUpdateResult { if (!this.store?.updateProjectHostSetup) { throw new Error('runtime_unavailable') } const result = this.store.updateProjectHostSetup(args) if (!result) { throw new Error(`Project host setup not found: ${args.setupId}`) } if ('worktreeBasePath' in args.updates && result.repo) { void prepareLocalWorktreeRootForRepo(this.store, result.repo) invalidateAuthorizedRootsCache() } return result } deleteProjectHostSetup(args: ProjectHostSetupDeleteArgs): ProjectHostSetupDeleteResult { if (!this.store?.deleteProjectHostSetup) { throw new Error('runtime_unavailable') } const result = this.store.deleteProjectHostSetup(args) if (!result) { throw new Error(`Project host setup not found: ${args.setupId}`) } return result } listProjectGroups(): ProjectGroup[] { return this.store?.getProjectGroups?.() ?? [] } listFolderWorkspaces(): FolderWorkspace[] { return this.store?.getFolderWorkspaces?.() ?? [] } async createProjectGroup(input: { name: string parentPath?: string | null connectionId?: string | null parentGroupId?: string | null createdFrom?: ProjectGroup['createdFrom'] }): Promise { if (!this.store?.createProjectGroup) { throw new Error('runtime_unavailable') } const group = this.store.createProjectGroup({ name: input.name, parentPath: input.parentPath ?? null, connectionId: input.connectionId ?? null, parentGroupId: input.parentGroupId ?? null, createdFrom: input.createdFrom ?? 'manual' }) this.notifyReposChanged() return group } async updateProjectGroup( groupId: string, updates: Partial> ): Promise { if (!this.store?.updateProjectGroup) { throw new Error('runtime_unavailable') } const updated = this.store.updateProjectGroup(groupId, updates) if (updated) { this.notifyReposChanged() } return updated } async deleteProjectGroup(groupId: string): Promise<{ deleted: boolean }> { if (!this.store?.deleteProjectGroup) { throw new Error('runtime_unavailable') } const deleted = this.store.deleteProjectGroup(groupId) if (deleted) { this.notifyReposChanged() } return { deleted } } async moveProjectToGroup( repoSelector: string, groupId: string | null, order?: number ): Promise { if (!this.store?.moveProjectToGroup) { throw new Error('runtime_unavailable') } const repo = await this.resolveRepoSelector(repoSelector) const moved = this.store.moveProjectToGroup(repo.id, groupId, order) if (!moved) { throw new Error('repo_not_found') } this.notifyReposChanged() return moved } async createFolderWorkspace(input: { projectGroupId: string name?: string folderPath?: string | null connectionId?: string | null linkedTask?: FolderWorkspace['linkedTask'] createdWithAgent?: FolderWorkspace['createdWithAgent'] pendingFirstAgentMessageRename?: boolean }): Promise { if (!this.store?.createFolderWorkspace) { throw new Error('runtime_unavailable') } const projectGroups = this.store.getProjectGroups?.() ?? [] const group = projectGroups.find((entry) => entry.id === input.projectGroupId) const folderPath = typeof input.folderPath === 'string' && input.folderPath.trim().length > 0 ? input.folderPath : group?.parentPath if (!group || !folderPath) { throw new Error('folder_workspace_project_group_not_found') } const status = await getFolderWorkspacePathStatusForPath( { folderPath, projectGroupId: group.id, connectionId: input.connectionId ?? group.connectionId ?? null, projectGroups, repos: this.store.getRepos() }, { getSshFilesystemProvider } ) assertFolderWorkspacePathUsable(status) const workspace = this.store.createFolderWorkspace(input) this.notifyReposChanged() return workspace } async getFolderWorkspacePathStatus( request: FolderWorkspacePathStatusRequest ): Promise { if (!this.store) { throw new Error('runtime_unavailable') } return getFolderWorkspacePathStatus(this.store, request, { getSshFilesystemProvider }) } async updateFolderWorkspace( folderWorkspaceId: string, updates: Partial< Pick< FolderWorkspace, | 'name' | 'folderPath' | 'linkedTask' | 'comment' | 'isArchived' | 'isUnread' | 'isPinned' | 'sortOrder' | 'manualOrder' | 'workspaceStatus' | 'createdWithAgent' | 'pendingFirstAgentMessageRename' | 'firstAgentMessageRenameError' | 'lastActivityAt' > > ): Promise { if (!this.store?.updateFolderWorkspace) { throw new Error('runtime_unavailable') } if (typeof updates.folderPath === 'string' && updates.folderPath.trim().length > 0) { const workspace = this.store .getFolderWorkspaces?.() .find((entry) => entry.id === folderWorkspaceId) if (!workspace) { return null } const projectGroups = this.store.getProjectGroups?.() ?? [] const status = await getFolderWorkspacePathStatusForPath( { folderPath: updates.folderPath, projectGroupId: workspace.projectGroupId, connectionId: workspace.connectionId ?? projectGroups.find((entry) => entry.id === workspace.projectGroupId)?.connectionId ?? null, projectGroups, repos: this.store.getRepos() }, { getSshFilesystemProvider } ) assertFolderWorkspacePathUsable(status) } const updated = this.store.updateFolderWorkspace(folderWorkspaceId, updates) if (updated) { this.notifyReposChanged() } return updated } async deleteFolderWorkspace(folderWorkspaceId: string): Promise<{ deleted: boolean }> { if (!this.store?.removeFolderWorkspace) { throw new Error('runtime_unavailable') } const deleted = this.store.removeFolderWorkspace(folderWorkspaceId) if (deleted) { this.notifyReposChanged() } return { deleted } } async scanNestedRepos(path: string): Promise { if (!isAbsolute(path)) { throw new Error('Project path must be an absolute path') } return scanNestedRepos({ path, options: { timeoutMs: 15_000 } }) } async browseServerDir(pathValue: string): Promise<{ resolvedPath: string; entries: DirEntry[] }> { const dirPath = resolveServerBrowsePath(pathValue) const dirStat = await stat(dirPath) if (!dirStat.isDirectory()) { throw new Error(`${dirPath} is not a directory`) } const entries = await readdir(dirPath, { withFileTypes: true }) const mapped = entries .filter((entry) => entry.name !== '.' && entry.name !== '..') .map((entry) => ({ name: entry.name, isDirectory: entry.isDirectory(), isSymlink: entry.isSymbolicLink() })) mapped.sort((a, b) => { if (a.isDirectory !== b.isDirectory) { return a.isDirectory ? -1 : 1 } return a.name.localeCompare(b.name) }) return { resolvedPath: dirPath, entries: mapped } } async isGitAvailable(): Promise { try { await gitExecFileAsync(['--version'], { cwd: process.cwd(), timeout: 3000 }) return true } catch { return false } } async importNestedRepos(args: { parentPath: string groupName: string projectPaths: string[] mode: ProjectGroupImportMode }): Promise { if (!this.store?.createProjectGroup || !this.store?.moveProjectToGroup) { throw new Error('runtime_unavailable') } if (!isAbsolute(args.parentPath)) { throw new Error('Project path must be an absolute path') } const scan = await scanNestedRepos({ path: args.parentPath, options: { timeoutMs: 15_000 } }) const selection = resolveNestedRepoSelection({ scan, projectPaths: args.projectPaths }) const groupResolver = createNestedProjectGroupResolver({ parentPath: args.parentPath, groupName: args.groupName, mode: args.mode, connectionId: null, repoPaths: selection.selectedPaths, createGroup: (input) => this.store!.createProjectGroup!(input) }) const results: ProjectGroupImportResult['projects'] = selection.rejectedPaths.map( (repoPath) => ({ path: repoPath, status: 'failed', error: 'Repository was not found in the nested repo scan result' }) ) const importedProjectIdsByRepoPath = new Map() const importTargetResolver = createNestedRepoImportTargetResolver() for (const [projectGroupOrder, repoPath] of selection.selectedPaths.entries()) { try { if (!isGitRepo(repoPath)) { results.push({ path: repoPath, status: 'failed', error: 'Not a valid git repository' }) continue } const importRepoPath = await importTargetResolver.resolveLocal(repoPath) const normalizedImportRepoPath = normalizeRuntimePathForComparison(importRepoPath) const alreadyImportedProjectId = importedProjectIdsByRepoPath.get(normalizedImportRepoPath) if (alreadyImportedProjectId) { results.push({ path: repoPath, projectId: alreadyImportedProjectId, status: 'already-known' }) continue } const existing = this.store .getRepos() .find((repo) => normalizeRuntimePathForComparison(repo.path) === normalizedImportRepoPath) const group = groupResolver.getGroupForRepo(repoPath) if (existing) { if (group) { this.store.moveProjectToGroup(existing.id, group.id, projectGroupOrder) } importedProjectIdsByRepoPath.set(normalizedImportRepoPath, existing.id) results.push({ path: repoPath, projectId: existing.id, status: 'already-known' }) continue } const repo: Repo = { id: randomUUID(), path: importRepoPath, displayName: getRepoName(importRepoPath), badgeColor: DEFAULT_REPO_BADGE_COLOR, addedAt: Date.now(), kind: 'git', externalWorktreeVisibility: 'hide', externalWorktreeVisibilityLegacy: false, ...(group ? { projectGroupId: group.id, projectGroupOrder } : {}) } this.store.addRepo(repo) importedProjectIdsByRepoPath.set(normalizedImportRepoPath, repo.id) results.push({ path: repoPath, projectId: repo.id, status: 'imported' }) } catch (error) { results.push({ path: repoPath, status: 'failed', error: sanitizeNestedRepoRuntimeImportError( 'Failed to import nested repository in runtime', error ) }) } } const importedCount = results.filter((entry) => entry.status === 'imported').length const alreadyKnownCount = results.filter((entry) => entry.status === 'already-known').length const failedCount = results.filter((entry) => entry.status === 'failed').length if (importedCount + alreadyKnownCount === 0) { for (const group of groupResolver.getCreatedGroups().toReversed()) { this.store.deleteProjectGroup?.(group.id) } } this.invalidateResolvedWorktreeCache() this.notifyReposChanged() const rootGroup = groupResolver.getRootGroup() return { ...(rootGroup && importedCount + alreadyKnownCount > 0 ? { group: rootGroup } : {}), projects: results, importedCount, alreadyKnownCount, failedCount } } async listSparsePresets(repoSelector: string) { if (!this.store?.getSparsePresets) { throw new Error('runtime_unavailable') } const repo = await this.resolveRepoSelector(repoSelector) return this.store.getSparsePresets(repo.id) } async saveSparsePreset( repoSelector: string, args: { id?: string; name: string; directories: string[] } ) { if (!this.store?.getSparsePresets || !this.store.saveSparsePreset) { throw new Error('runtime_unavailable') } const repo = await this.resolveRepoSelector(repoSelector) const name = normalizeSparsePresetName(args.name) const directories = normalizeSparsePresetDirectoriesForSave(args.directories) const now = Date.now() const existing = args.id ? this.store.getSparsePresets(repo.id).find((preset) => preset.id === args.id) : undefined return this.store.saveSparsePreset({ id: existing?.id ?? randomUUID(), repoId: repo.id, name, directories, createdAt: existing?.createdAt ?? now, updatedAt: now }) } async addRepo(path: string, kind: 'git' | 'folder' = 'git'): Promise { if (!this.store) { throw new Error('runtime_unavailable') } if (!isAbsolute(path)) { // Why: remote clients may run in a different cwd than the server. Require // server-side repo paths to be explicit so `orca serve` cwd is irrelevant. throw new Error('Project path must be an absolute path') } if (kind === 'git' && !isGitRepo(path)) { throw new Error(`Not a valid git repository: ${path}`) } const existing = this.store.getRepos().find((repo) => runtimePathsEqual(repo.path, path)) if (existing) { return existing } const detected = await detectRepoIconAndUpstream({ repoPath: path, kind }) const repo: Repo = { id: randomUUID(), path, displayName: getRepoName(path), badgeColor: DEFAULT_REPO_BADGE_COLOR, ...detected, addedAt: Date.now(), kind, ...(kind === 'git' ? { externalWorktreeVisibility: 'hide' as const, externalWorktreeVisibilityLegacy: false } : {}) } this.store.addRepo(repo) await prepareLocalWorktreeRootForRepo(this.store, repo) this.invalidateResolvedWorktreeCache() this.notifyReposChanged() return this.store.getRepo(repo.id) ?? repo } async createRepo( parentPath: string, name: string, kind: 'git' | 'folder' = 'git' ): Promise<{ repo: Repo } | { error: string }> { if (!this.store) { throw new Error('runtime_unavailable') } const trimmedName = name.trim() const trimmedParentPath = parentPath.trim() const repoKind: 'git' | 'folder' = kind === 'folder' ? 'folder' : 'git' if (!trimmedName) { return { error: 'Name cannot be empty' } } if (/[\\/]/.test(trimmedName) || trimmedName === '.' || trimmedName === '..') { return { error: 'Name cannot contain slashes or be "." / ".."' } } if (!trimmedParentPath) { return { error: 'Parent directory is required' } } if (!isAbsolute(trimmedParentPath)) { return { error: 'Parent directory must be an absolute path' } } const targetPath = join(trimmedParentPath, trimmedName) const existing = this.store.getRepos().find((repo) => runtimePathsEqual(repo.path, targetPath)) if (existing) { return { repo: existing } } let createdDir = false try { // Why: default create-project parents are host-home based and may not exist // before the first project is created on a fresh runtime. await mkdir(trimmedParentPath, { recursive: true }) const existingStat = await stat(targetPath).catch((error: unknown) => { if (isENOENT(error)) { return null } throw error }) if (existingStat) { if (!existingStat.isDirectory()) { return { error: `"${trimmedName}" already exists at this location and is not a folder.` } } const entries = await readdir(targetPath) if (entries.length > 0) { return { error: `"${trimmedName}" already exists at this location and is not empty.` } } } else { await mkdir(targetPath, { recursive: false }) createdDir = true } } catch (error) { const message = error instanceof Error ? error.message : String(error) return { error: `Failed to prepare directory: ${message}` } } if (repoKind === 'git') { let step: 'init' | 'commit' = 'init' try { await gitExecFileAsync(['init'], { cwd: targetPath }) step = 'commit' await gitExecFileAsync(['commit', '--allow-empty', '-m', 'Initial commit'], { cwd: targetPath }) } catch (error) { if (createdDir) { await rm(targetPath, { recursive: true, force: true }).catch(() => {}) } else if (step === 'commit') { await rm(join(targetPath, '.git'), { recursive: true, force: true }).catch(() => {}) } const message = error instanceof Error ? error.message : String(error) if ( step === 'commit' && /Please tell me who you are|user\.name|user\.email/i.test(message) ) { return { error: 'Git author identity is not configured. Run `git config --global user.name "Your Name"` and `git config --global user.email "you@example.com"`, then try again.' } } const stepLabel = step === 'init' ? 'Failed to initialize git repository' : 'Failed to create initial commit' return { error: `${stepLabel}: ${message}` } } } const raceWinner = this.store .getRepos() .find((repo) => runtimePathsEqual(repo.path, targetPath)) if (raceWinner) { return { repo: raceWinner } } const detected = await detectRepoIconAndUpstream({ repoPath: targetPath, kind: repoKind }) const repo: Repo = { id: randomUUID(), path: targetPath, displayName: trimmedName, badgeColor: DEFAULT_REPO_BADGE_COLOR, ...detected, addedAt: Date.now(), kind: repoKind, ...(repoKind === 'git' ? { externalWorktreeVisibility: 'hide' as const, externalWorktreeVisibilityLegacy: false } : {}) } this.store.addRepo(repo) await prepareLocalWorktreeRootForRepo(this.store, repo) invalidateAuthorizedRootsCache() this.invalidateResolvedWorktreeCache() this.notifyReposChanged() return { repo: this.store.getRepo(repo.id) ?? repo } } async cloneRepo(url: string, destination: string): Promise { if (!this.store) { throw new Error('runtime_unavailable') } const trimmedUrl = url.trim() const trimmedDestination = destination.trim() if (!trimmedDestination) { throw new Error('Clone destination is required') } const clonePath = deriveValidatedClonePath({ url: trimmedUrl, destination: trimmedDestination }) const clonePathKey = getClonePathComparisonKey(clonePath) const previous = this.cloneInFlightByPath.get(clonePathKey) ?? Promise.resolve() let release!: () => void const current = new Promise((resolve) => { release = resolve }) const tail = previous.then( () => current, () => current ) this.cloneInFlightByPath.set(clonePathKey, tail) try { await previous return await this.cloneRepoAfterPathLock( trimmedUrl, trimmedDestination, clonePath, clonePathKey ) } finally { release() if (this.cloneInFlightByPath.get(clonePathKey) === tail) { this.cloneInFlightByPath.delete(clonePathKey) } } } private async cloneRepoAfterPathLock( trimmedUrl: string, trimmedDestination: string, clonePath: string, clonePathKey: string ): Promise { if (!this.store) { throw new Error('runtime_unavailable') } const existingBeforeClone = this.store .getRepos() .find((repo) => getClonePathComparisonKey(repo.path) === clonePathKey) if (existingBeforeClone && !isFolderRepo(existingBeforeClone)) { return existingBeforeClone } await mkdir(trimmedDestination, { recursive: true }) const claimedTarget = await claimCloneTarget(clonePath) await new Promise((resolve, reject) => { let proc: ReturnType try { proc = wslAwareSpawn('git', ['clone', '--progress', '--', trimmedUrl, clonePath], { cwd: trimmedDestination, stdio: ['ignore', 'ignore', 'pipe'] }) } catch (err) { void cleanupClaimedCloneTarget(clonePath, claimedTarget).finally(() => { const message = err instanceof Error ? err.message : String(err) reject(new Error(`Clone failed: ${message}`)) }) return } let stderrTail = '' let settled = false proc.stderr?.on('data', (chunk: Buffer) => { stderrTail = (stderrTail + chunk.toString()).slice(-4096) }) const finishClone = async ( code: number | null, signal: NodeJS.Signals | null, error?: Error ) => { if (settled) { return } settled = true const cloneSucceeded = !error && code === 0 && !signal if (!cloneSucceeded) { await cleanupClaimedCloneTarget(clonePath, claimedTarget) } if (error) { reject(new Error(`Clone failed: ${error.message}`)) } else if (signal === 'SIGTERM') { reject(new Error('Clone aborted')) } else if (code === 0) { resolve() } else { reject(new Error(`Clone failed: ${getGitCloneFailureMessage(stderrTail, { clonePath })}`)) } } proc.on('error', (error) => { void finishClone(null, null, error) }) proc.on('close', (code, signal) => { void finishClone(code, signal) }) }) const existing = this.store .getRepos() .find((repo) => getClonePathComparisonKey(repo.path) === clonePathKey) if (existing) { if (isFolderRepo(existing)) { const updated = this.store.updateRepo(existing.id, { kind: 'git' }) if (updated) { await prepareLocalWorktreeRootForRepo(this.store, updated) invalidateAuthorizedRootsCache() this.invalidateResolvedWorktreeCache() this.notifyReposChanged() return updated } } return existing } const detected = await detectRepoIconAndUpstream({ repoPath: clonePath, kind: 'git' }) const repo: Repo = { id: randomUUID(), path: clonePath, displayName: getRepoName(clonePath), badgeColor: DEFAULT_REPO_BADGE_COLOR, ...detected, addedAt: Date.now(), kind: 'git', externalWorktreeVisibility: 'hide', externalWorktreeVisibilityLegacy: false } this.store.addRepo(repo) await prepareLocalWorktreeRootForRepo(this.store, repo) invalidateAuthorizedRootsCache() this.invalidateResolvedWorktreeCache() this.notifyReposChanged() return this.store.getRepo(repo.id) ?? repo } async showRepo(repoSelector: string): Promise { return await this.resolveRepoSelector(repoSelector) } async setRepoBaseRef(repoSelector: string, baseRef: string): Promise { if (!this.store) { throw new Error('runtime_unavailable') } const repo = await this.resolveRepoSelector(repoSelector) if (isFolderRepo(repo)) { throw new Error('Folder mode does not support base refs.') } const updated = this.store.updateRepo(repo.id, { worktreeBaseRef: baseRef }) if (!updated) { throw new Error('repo_not_found') } this.invalidateResolvedWorktreeCache() this.notifyReposChanged() return updated } async updateRepo( repoSelector: string, updates: Partial< Pick< Repo, | 'displayName' | 'badgeColor' | 'repoIcon' | 'upstream' | 'hookSettings' | 'worktreeBaseRef' | 'worktreeBasePath' | 'kind' | 'symlinkPaths' | 'issueSourcePreference' | 'externalWorktreeVisibility' | 'externalWorktreeVisibilityPromptDismissedAt' | 'externalWorktreeInboxBaselinePaths' | 'importedExternalWorktreePaths' | 'projectGroupId' | 'projectGroupOrder' > > & { sourceControlAi?: Repo['sourceControlAi'] | null externalWorktreeDiscoverySuppressedAt?: Repo['externalWorktreeDiscoverySuppressedAt'] | null } ): Promise { if (!this.store) { throw new Error('runtime_unavailable') } const repo = await this.resolveRepoSelector(repoSelector) const sanitizedUpdates = omitUndefinedProperties(updates) if ('worktreeBasePath' in updates && updates.worktreeBasePath === undefined) { sanitizedUpdates.worktreeBasePath = undefined } if ( 'externalWorktreeDiscoverySuppressedAt' in updates && updates.externalWorktreeDiscoverySuppressedAt === null ) { sanitizedUpdates.externalWorktreeDiscoverySuppressedAt = undefined } if ('sourceControlAi' in updates && updates.sourceControlAi === null) { sanitizedUpdates.sourceControlAi = null } const updated = this.store.updateRepo(repo.id, sanitizedUpdates) if (!updated) { throw new Error('repo_not_found') } if ('worktreeBasePath' in updates) { await prepareLocalWorktreeRootForRepo(this.store, updated) invalidateAuthorizedRootsCache() } this.invalidateResolvedWorktreeCache() this.notifyReposChanged() return updated } async removeProject(repoSelector: string): Promise<{ removed: true }> { if (!this.store?.removeProject) { throw new Error('runtime_unavailable') } const repo = await this.resolveRepoSelector(repoSelector) this.store.removeProject(repo.id) this.invalidateResolvedWorktreeCache() invalidateAuthorizedRootsCache() this.notifyReposChanged() return { removed: true } } async inspectTerminalProcess( terminalSelector: string ): Promise<{ foregroundProcess: string | null; hasChildProcesses: boolean }> { const leaf = this.resolveLeafForHandle(terminalSelector) if (!leaf?.ptyId || !this.ptyController) { return { foregroundProcess: null, hasChildProcesses: false } } const foregroundProcess = await this.ptyController.getForegroundProcess(leaf.ptyId) const hasChildProcesses = (await this.ptyController.hasChildProcesses?.(leaf.ptyId).catch(() => false)) ?? false return { foregroundProcess, hasChildProcesses } } reorderRepos(orderedIds: string[]): { status: 'applied' | 'rejected' } { if (!this.store?.reorderRepos) { throw new Error('runtime_unavailable') } // Why: remote clients can race repo add/remove on the server just like // local drag-reorder can race another window. Let the store validate the // full permutation and signal a resync-worthy rejection. const applied = this.store.reorderRepos(orderedIds) if (!applied) { return { status: 'rejected' } } this.invalidateResolvedWorktreeCache() this.notifyReposChanged() return { status: 'applied' } } async searchRepoRefs( repoSelector: string, query: string, limit = DEFAULT_REPO_SEARCH_REFS_LIMIT ): Promise { if (!Number.isInteger(limit) || limit <= 0) { throw new Error('invalid_limit') } const repo = await this.resolveRepoSelector(repoSelector) if (isFolderRepo(repo)) { return { refs: [], truncated: false } } const refDetails = repo.connectionId ? await this.searchRemoteRepoRefs(repo, query, limit + 1) : await searchBaseRefDetails(repo.path, query, limit + 1) return { refs: refDetails.slice(0, limit).map((entry) => entry.refName), refDetails: refDetails.slice(0, limit), truncated: refDetails.length > limit } } async getRepoBaseRefDefault( repoSelector: string ): Promise<{ defaultBaseRef: string | null; remoteCount: number }> { const repo = await this.resolveRepoSelector(repoSelector) if (isFolderRepo(repo)) { return { defaultBaseRef: null, remoteCount: 0 } } if (repo.connectionId) { return this.getRemoteRepoBaseRefDefault(repo) } const [defaultBaseRef, remoteCount] = await Promise.all([ getBaseRefDefault(repo.path), getRemoteCount(repo.path) ]) return { defaultBaseRef, remoteCount } } private async getRemoteRepoBaseRefDefault( repo: Repo ): Promise<{ defaultBaseRef: string | null; remoteCount: number }> { const provider = repo.connectionId ? getSshGitProvider(repo.connectionId) : null if (!provider) { return { defaultBaseRef: null, remoteCount: 0 } } const [defaultBaseRef, remoteCount] = await Promise.all([ resolveDefaultBaseRefViaExec(async (argv) => { try { return await provider.exec(argv, repo.path) } catch (err) { if (argv[0] === 'symbolic-ref') { console.warn('[runtime:repo.baseRefDefault] SSH symbolic-ref failed', { path: repo.path, err }) } throw err } }), provider .exec(['remote'], repo.path) .then((result) => parseRemoteCount(result.stdout)) .catch((err) => { console.warn('[runtime:repo.baseRefDefault] SSH git remote count failed', { path: repo.path, err }) return 0 }) ]) return { defaultBaseRef, remoteCount } } private async searchRemoteRepoRefs( repo: Repo, query: string, limit: number ): Promise { const provider = repo.connectionId ? getSshGitProvider(repo.connectionId) : null if (!provider) { return [] } const normalizedQuery = normalizeRefSearchQuery(query) try { const remotesResult = await provider.exec(['remote'], repo.path).catch(() => ({ stdout: '' })) const remotes = remotesResult.stdout .split('\n') .map((line) => line.trim()) .filter(Boolean) const runSearch = async (patternGroup?: 'segmented' | 'branchRoot'): Promise => { try { return ( await provider.exec( buildSearchBaseRefsArgv(normalizedQuery, limit, { remoteNames: remotes, patternGroup }), repo.path ) ).stdout } catch (err) { if (!isForEachRefExcludeUnsupportedError(err)) { throw err } return ( await provider.exec( buildSearchBaseRefsArgv(normalizedQuery, limit, { excludeRemoteHead: false, remoteNames: remotes, patternGroup }), repo.path ) ).stdout } } const searchTokens = normalizedQuery.split('/').filter((token) => token.length > 0) if (searchTokens.length > 1) { const results = await Promise.all([runSearch('segmented'), runSearch('branchRoot')]) return mergeBaseRefSearchResultGroups( results.map((stdout) => parseAndFilterSearchRefDetails(stdout, limit, remotes)), limit ) } return parseAndFilterSearchRefDetails(await runSearch(), limit, remotes) } catch (err) { console.warn('[runtime:repo.searchRefs] SSH for-each-ref failed', { path: repo.path, err }) return [] } } private async resolveHostedReviewTarget(args: { repoSelector: string worktreeSelector?: string }): Promise<{ repo: Repo; repoPath: string }> { const repo = await this.resolveRepoSelector(args.repoSelector) if (!args.worktreeSelector) { return { repo, repoPath: repo.path } } const worktree = await this.resolveWorktreeSelector(args.worktreeSelector) if (worktree.repoId !== repo.id) { throw new Error('Access denied: worktree does not belong to repository') } return { repo, repoPath: worktree.path } } private getHostedReviewExecutionOptions( repo: Repo ): { localGitExecOptions: { wslDistro?: string } } | undefined { const localGitOptions = this.getLocalGitExecutionOptionArgs(repo)[0] ?? {} return Object.keys(localGitOptions).length > 0 ? { localGitExecOptions: localGitOptions } : undefined } private getLocalGitExecutionOptionArgs(repo: Repo): [] | [{ wslDistro?: string }] { const localGitOptions = getLocalProjectWorktreeGitOptions(this.requireStore(), repo) return Object.keys(localGitOptions).length > 0 ? [localGitOptions] : [] } private getAgentLaunchPlatformForRepo(repo: Repo): NodeJS.Platform { const projectRuntime = repo.connectionId ? undefined : resolveLocalProjectRuntimeForRepo(this.requireStore(), repo) return getAgentLaunchPlatformForRepo(repo, projectRuntime) } private getAgentLaunchPlatformForWorkspace(scope: TerminalWorkspaceLaunchScope): NodeJS.Platform { if (scope.repo) { return this.getAgentLaunchPlatformForRepo(scope.repo) } if (scope.connectionId) { return isWindowsAbsolutePathLike(scope.path) ? 'win32' : 'linux' } return isWslUncPath(scope.path) ? 'linux' : process.platform } async getRepoSlug(repoSelector: string): Promise<{ owner: string; repo: string } | null> { const repo = await this.resolveRepoSelector(repoSelector) const options = this.getHostedReviewExecutionOptions(repo) return options ? getRepoSlug(repo.path, repo.connectionId ?? null, options) : getRepoSlug(repo.path, repo.connectionId ?? null) } async getRepoUpstream(repoSelector: string): Promise<{ owner: string; repo: string } | null> { const repo = await this.resolveRepoSelector(repoSelector) const options = this.getHostedReviewExecutionOptions(repo) return options ? getRepoUpstream(repo.path, repo.connectionId ?? null, options) : getRepoUpstream(repo.path, repo.connectionId ?? null) } // Why: repos added before fork detection existed have no stored `upstream`, so // their avatar/badge would never self-correct. Resolve it once at startup for // local git repos; SSH repos resolve lazily when their settings open (their // connection may not be up yet). Sequential to respect the gh rate limit; // failures leave `upstream` unset so the next launch retries. private async backfillForkUpstreams(): Promise { try { const store = this.requireStore() let changed = false for (const repo of store.getRepos()) { if (repo.upstream !== undefined || repo.kind === 'folder' || repo.connectionId) { continue } let upstream: { owner: string; repo: string } | null try { upstream = await getRepoUpstream(repo.path, null) } catch { continue } const updates: Partial = { upstream: upstream ?? null } // Only migrate the auto-detected origin avatar; never touch a chosen icon. if (upstream && repo.repoIcon?.type === 'image' && repo.repoIcon.source === 'github') { updates.repoIcon = githubAvatarIcon(upstream) } store.updateRepo(repo.id, updates) changed = true } if (changed) { this.notifyReposChanged() } } catch { // Best-effort startup backfill; never disrupt launch. } } async listRepoWorkItems( repoSelector: string, limit?: number, query?: string, before?: string, noCache?: boolean ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return listWorkItems( repo.path, limit, query, before, repo.issueSourcePreference, repo.connectionId ?? null, noCache, ...this.getLocalGitExecutionOptionArgs(repo) ) } async listRepoIssues( repoSelector: string, limit?: number ): Promise>['items']> { const repo = await this.resolveRepoSelector(repoSelector) const result = await listGitHubIssues( repo.path, limit, repo.issueSourcePreference, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) return result.items } async getRepoWorkItem( repoSelector: string, number: number, type?: 'issue' | 'pr' ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return getWorkItem( repo.path, number, type, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async getRepoWorkItemByOwnerRepo( repoSelector: string, ownerRepo: { owner: string; repo: string }, number: number, type: 'issue' | 'pr' ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return getWorkItemByOwnerRepo( repo.path, ownerRepo, number, type, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async getRepoWorkItemDetails( repoSelector: string, number: number, type?: 'issue' | 'pr' ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return getWorkItemDetails( repo.path, number, type, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async countRepoWorkItems(repoSelector: string, query?: string): Promise { const repo = await this.resolveRepoSelector(repoSelector) return countWorkItems( repo.path, query, repo.issueSourcePreference, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async listRepoLabels(repoSelector: string): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return listLabels( repo.path, repo.issueSourcePreference, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async listRepoAssignableUsers( repoSelector: string ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return listAssignableUsers( repo.path, repo.issueSourcePreference, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } getGitHubRateLimit(options?: { force?: boolean }): Promise>> { return getRateLimit(options) } async getRepoPRForBranch( repoSelector: string, branch: string, linkedPRNumber?: number | null, fallbackPRNumber?: number | null, acceptMergedFallbackPR?: boolean ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) const options: GitHubPRBranchLookupOptions = this.getHostedReviewExecutionOptions(repo) ?? {} const lookupOptions = { ...options } if (acceptMergedFallbackPR === true) { lookupOptions.acceptMergedFallbackPR = true } const lookupOptionArgs: [] | [GitHubPRBranchLookupOptions] = Object.keys(lookupOptions).length > 0 ? [lookupOptions] : [] return getPRForBranch( repo.path, branch, linkedPRNumber ?? null, repo.connectionId ?? null, linkedPRNumber == null ? (fallbackPRNumber ?? null) : null, ...lookupOptionArgs ) } async getHostedReviewForBranch(args: { repoSelector: string branch: string currentHeadOid?: string | null linkedGitHubPR?: number | null fallbackGitHubPR?: number | null linkedGitLabMR?: number | null linkedBitbucketPR?: number | null linkedAzureDevOpsPR?: number | null linkedGiteaPR?: number | null }): Promise { const repo = await this.resolveRepoSelector(args.repoSelector) const executionOptions = this.getHostedReviewExecutionOptions(repo) const review = await getHostedReviewForBranchFromRepo({ repoPath: repo.path, connectionId: repo.connectionId ?? null, branch: args.branch, currentHeadOid: args.currentHeadOid ?? null, linkedGitHubPR: args.linkedGitHubPR ?? null, fallbackGitHubPR: args.linkedGitHubPR == null ? (args.fallbackGitHubPR ?? null) : null, linkedGitLabMR: args.linkedGitLabMR ?? null, linkedBitbucketPR: args.linkedBitbucketPR ?? null, linkedAzureDevOpsPR: args.linkedAzureDevOpsPR ?? null, linkedGiteaPR: args.linkedGiteaPR ?? null, ...executionOptions }) if (review?.provider === 'github' && this.stats && !this.stats.hasCountedPR(review.url)) { this.stats.record({ type: 'pr_created', at: Date.now(), repoId: repo.id, meta: { prNumber: review.number, prUrl: review.url } }) } return review } async getHostedReviewCreationEligibility( args: Omit & { repoSelector: string worktreeSelector?: string } ): Promise { const { repo, repoPath } = await this.resolveHostedReviewTarget(args) const executionOptions = this.getHostedReviewExecutionOptions(repo) return getHostedReviewCreationEligibilityFromRepo({ repoPath, connectionId: repo.connectionId ?? null, branch: args.branch, base: args.base ?? null, hasUncommittedChanges: args.hasUncommittedChanges, hasUpstream: args.hasUpstream, ahead: args.ahead, behind: args.behind, linkedGitHubPR: args.linkedGitHubPR ?? null, fallbackGitHubPR: args.linkedGitHubPR == null ? (args.fallbackGitHubPR ?? null) : null, linkedGitLabMR: args.linkedGitLabMR ?? null, linkedBitbucketPR: args.linkedBitbucketPR ?? null, linkedAzureDevOpsPR: args.linkedAzureDevOpsPR ?? null, linkedGiteaPR: args.linkedGiteaPR ?? null, ...executionOptions }) } async createHostedReview( args: CreateHostedReviewInput & { repoSelector: string; worktreeSelector?: string } ): Promise { const { repo, repoPath } = await this.resolveHostedReviewTarget(args) const executionOptions = this.getHostedReviewExecutionOptions(repo) const input = { provider: args.provider, base: args.base, head: args.head, title: args.title, body: args.body, draft: args.draft, ...(args.useTemplate !== undefined ? { useTemplate: args.useTemplate } : {}) } const result = executionOptions ? await createHostedReviewFromRepo( repoPath, input, repo.connectionId ?? null, executionOptions ) : await createHostedReviewFromRepo(repoPath, input, repo.connectionId ?? null) if (result.ok && this.stats && !this.stats.hasCountedPR(result.url)) { this.stats.record({ type: 'pr_created', at: Date.now(), repoId: repo.id, meta: { prNumber: result.number, prUrl: result.url } }) } return result } async listGitLabRepoWorkItems( repoSelector: string, state?: MRListState, page?: number, perPage?: number, query?: string ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return listGitLabWorkItems( repo.path, state ?? 'opened', page ?? 1, perPage ?? 20, repo.issueSourcePreference, query, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async listGitLabRepoMRs( repoSelector: string, state?: MRListState, page?: number, perPage?: number, query?: string ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return listGitLabMergeRequests( repo.path, normalizeGitLabMRListState(state), normalizeGitLabPositiveInteger(page, 1, 10_000), normalizeGitLabPositiveInteger(perPage, 20, 100), repo.issueSourcePreference, query, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async listGitLabRepoIssues( repoSelector: string, state?: GitLabIssueListState, assignee?: string, limit?: number ): Promise<{ items: GitLabWorkItem[] error?: Awaited>['error'] }> { const repo = await this.resolveRepoSelector(repoSelector) const normalized = normalizeGitLabIssueListArgs({ state, assignee, limit }) const result = await listGitLabIssues( repo.path, normalized.limit, repo.issueSourcePreference, normalized.state, normalized.assignee, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) // Why: web runtime mirrors the desktop preload contract, where GitLab // issue rows share the GitLabWorkItem shape with MRs on TaskPage. const items: GitLabWorkItem[] = result.items.map((issue) => ({ id: `gitlab-issue-${repo.id}-${issue.number}`, type: 'issue' as const, number: issue.number, title: issue.title, state: issue.state, url: issue.url, labels: issue.labels, updatedAt: issue.updatedAt ?? '', author: issue.author ?? null, repoId: repo.id })) return { items, ...(result.error ? { error: result.error } : {}) } } async listGitLabRepoTodos( repoSelector: string ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return listGitLabTodos( repo.path, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async diagnoseGitLabAuth(): Promise>> { return diagnoseGitLabAuthClient() } async getGitLabRateLimit(options?: { force?: boolean host?: string | null }): Promise>> { return getGitLabRateLimit(options) } async listGitLabRepoLabels( repoSelector: string ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return listGitLabLabels( repo.path, repo.issueSourcePreference, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async createGitLabRepoIssue( repoSelector: string, title: string, body: string ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return createGitLabIssue( repo.path, title, body, repo.issueSourcePreference, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async updateGitLabRepoIssue( repoSelector: string, number: number, updates: GitLabIssueUpdate, projectRef?: GitLabProjectRef | null ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return updateGitLabIssue( repo.path, number, updates, repo.issueSourcePreference, repo.connectionId ?? null, projectRef, ...this.getLocalGitExecutionOptionArgs(repo) ) } async addGitLabRepoIssueComment( repoSelector: string, number: number, body: string, projectRef?: GitLabProjectRef | null ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return addGitLabIssueComment( repo.path, number, body, repo.issueSourcePreference, repo.connectionId ?? null, projectRef, ...this.getLocalGitExecutionOptionArgs(repo) ) } async addGitLabRepoMRComment( repoSelector: string, iid: number, body: string, projectRef?: GitLabProjectRef | null ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return addGitLabMRComment( repo.path, iid, body, repo.issueSourcePreference, repo.connectionId ?? null, projectRef, ...this.getLocalGitExecutionOptionArgs(repo) ) } async addGitLabRepoMRInlineComment( repoSelector: string, iid: number, input: GitLabMRInlineCommentInput, projectRef?: GitLabProjectRef | null ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return addGitLabMRInlineComment( repo.path, iid, input, repo.issueSourcePreference, repo.connectionId ?? null, projectRef, ...this.getLocalGitExecutionOptionArgs(repo) ) } async resolveGitLabRepoMRDiscussion( repoSelector: string, iid: number, discussionId: string, resolved: boolean, projectRef?: GitLabProjectRef | null ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return resolveGitLabMRDiscussion( repo.path, iid, discussionId, resolved, repo.issueSourcePreference, repo.connectionId ?? null, projectRef, ...this.getLocalGitExecutionOptionArgs(repo) ) } async getGitLabRepoJobTrace( repoSelector: string, jobId: number, projectRef?: GitLabProjectRef | null ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return getGitLabJobTrace( repo.path, jobId, repo.issueSourcePreference, repo.connectionId ?? null, projectRef, ...this.getLocalGitExecutionOptionArgs(repo) ) } async retryGitLabRepoJob( repoSelector: string, jobId: number, projectRef?: GitLabProjectRef | null ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return retryGitLabJob( repo.path, jobId, repo.issueSourcePreference, repo.connectionId ?? null, projectRef, ...this.getLocalGitExecutionOptionArgs(repo) ) } async mergeGitLabRepoMR( repoSelector: string, iid: number, method?: 'merge' | 'squash' | 'rebase', projectRef?: GitLabProjectRef | null ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return mergeGitLabMR( repo.path, iid, method ?? 'merge', repo.issueSourcePreference, repo.connectionId ?? null, projectRef, ...this.getLocalGitExecutionOptionArgs(repo) ) } async updateGitLabRepoMRState( repoSelector: string, iid: number, state: 'opened' | 'closed', projectRef?: GitLabProjectRef | null ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return state === 'closed' ? closeGitLabMR( repo.path, iid, repo.issueSourcePreference, repo.connectionId ?? null, projectRef, ...this.getLocalGitExecutionOptionArgs(repo) ) : reopenGitLabMR( repo.path, iid, repo.issueSourcePreference, repo.connectionId ?? null, projectRef, ...this.getLocalGitExecutionOptionArgs(repo) ) } async updateGitLabRepoMR( repoSelector: string, iid: number, updates: { title?: string; body?: string; addLabels?: string[]; removeLabels?: string[] }, projectRef?: GitLabProjectRef | null ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return updateGitLabMR( repo.path, iid, updates, repo.issueSourcePreference, repo.connectionId ?? null, projectRef, ...this.getLocalGitExecutionOptionArgs(repo) ) } async updateGitLabRepoMRReviewers( repoSelector: string, iid: number, reviewerIds: number[], projectRef?: GitLabProjectRef | null ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return updateGitLabMRReviewers( repo.path, iid, reviewerIds, repo.issueSourcePreference, repo.connectionId ?? null, projectRef, ...this.getLocalGitExecutionOptionArgs(repo) ) } async getGitLabRepoWorkItemDetails( repoSelector: string, iid: number, type: 'issue' | 'mr', projectRef?: GitLabProjectRef | null ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return getGitLabWorkItemDetails( repo.path, iid, type, repo.issueSourcePreference, repo.connectionId ?? null, projectRef, ...this.getLocalGitExecutionOptionArgs(repo) ) } async getGitLabRepoWorkItemByPath( repoSelector: string, projectRef: GitLabProjectRef, iid: number, type: 'issue' | 'mr' ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) const result = await getGitLabWorkItemByProjectRef( repo.path, projectRef, iid, type, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) // Why: remote pasted-URL lookups should update GitLab recents exactly // like the desktop IPC path, but only after a successful lookup. if (result && this.store?.updateSettings) { const store = this.store recordGitLabProjectRecent( { getSettings: () => store.getSettings(), updateSettings: (updates) => store.updateSettings?.(updates) }, projectRef.host, projectRef.path ) } return result } async getRepoIssue( repoSelector: string, number: number ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return getIssue( repo.path, number, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async getRepoPRChecks( repoSelector: string, prNumber: number, headSha?: string, prRepo?: GitHubOwnerRepo | null, options?: { noCache?: boolean } ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return getPRChecks( repo.path, prNumber, headSha, prRepo ?? null, options, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async rerunRepoPRChecks( repoSelector: string, prNumber: number, options?: { headSha?: string; failedOnly?: boolean } ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return rerunPRChecks( repo.path, prNumber, options, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async getRepoPRCheckDetails( repoSelector: string, args: { checkRunId?: number workflowRunId?: number checkName?: string url?: string | null prRepo?: GitHubOwnerRepo | null } ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return getPRCheckDetails( repo.path, { ...args, prRepo: args.prRepo ?? null }, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async getRepoPRComments( repoSelector: string, prNumber: number, prRepo?: GitHubOwnerRepo | null, options?: { noCache?: boolean } ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return getPRComments( repo.path, prNumber, { ...options, prRepo: prRepo ?? null }, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async getRepoPRFileContents( repoSelector: string, args: { prNumber: number path: string oldPath?: string status: GitHubPRFile['status'] headSha: string baseSha: string } ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return getPRFileContents({ repoPath: repo.path, connectionId: repo.connectionId ?? null, localGitOptions: this.getLocalGitExecutionOptionArgs(repo)[0], ...args }) } async resolveRepoReviewThread( repoSelector: string, threadId: string, resolve: boolean ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return resolveReviewThread( repo.path, threadId, resolve, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async setRepoPRFileViewed( repoSelector: string, args: { pullRequestId: string path: string viewed: boolean } ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return setPRFileViewed({ repoPath: repo.path, connectionId: repo.connectionId ?? null, localGitOptions: this.getLocalGitExecutionOptionArgs(repo)[0], ...args }) } async updateRepoPRTitle( repoSelector: string, prNumber: number, title: string, prRepo?: GitHubOwnerRepo | null ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return updatePRTitle( repo.path, prNumber, title, repo.connectionId ?? null, prRepo ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async updateRepoPRDetails( repoSelector: string, prNumber: number, updates: { title?: string; body?: string }, prRepo?: GitHubOwnerRepo | null ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return updatePRDetails( repo.path, prNumber, updates, repo.connectionId ?? null, prRepo ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async mergeRepoPR( repoSelector: string, prNumber: number, method?: 'merge' | 'squash' | 'rebase', prRepo?: GitHubOwnerRepo | null ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return mergePR( repo.path, prNumber, method, repo.connectionId ?? null, prRepo ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async setRepoPRAutoMerge( repoSelector: string, prNumber: number, enabled: boolean, method?: 'merge' | 'squash' | 'rebase', prRepo?: GitHubOwnerRepo | null ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return setPRAutoMerge( repo.path, prNumber, enabled, method, repo.connectionId ?? null, prRepo ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async updateRepoPRState( repoSelector: string, prNumber: number, updates: GitHubPullRequestStateUpdate ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return updatePRState( repo.path, prNumber, updates, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async requestRepoPRReviewers( repoSelector: string, prNumber: number, reviewers: string[] ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return requestPRReviewers( repo.path, prNumber, reviewers, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async removeRepoPRReviewers( repoSelector: string, prNumber: number, reviewers: string[] ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return removePRReviewers( repo.path, prNumber, reviewers, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async createRepoIssue( repoSelector: string, title: string, body: string, fields?: GitHubCreateIssueFields ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return createIssue( repo.path, title, body, repo.issueSourcePreference, repo.connectionId ?? null, fields, ...this.getLocalGitExecutionOptionArgs(repo) ) } async updateRepoIssue( repoSelector: string, number: number, updates: GitHubIssueUpdate ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return updateIssue( repo.path, number, updates, repo.connectionId ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async addRepoIssueComment( repoSelector: string, number: number, body: string, prRepo?: GitHubOwnerRepo | null ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return addIssueComment( repo.path, number, body, repo.connectionId ?? null, prRepo ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async addRepoPRReviewComment( repoSelector: string, args: Omit ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return addPRReviewComment({ repoPath: repo.path, connectionId: repo.connectionId ?? null, localGitOptions: this.getLocalGitExecutionOptionArgs(repo)[0], ...args }) } async addRepoPRReviewCommentReply( repoSelector: string, args: { prNumber: number commentId: number body: string threadId?: string path?: string line?: number prRepo?: GitHubOwnerRepo | null } ): Promise>> { const repo = await this.resolveRepoSelector(repoSelector) return addPRReviewCommentReply( repo.path, args.prNumber, args.commentId, args.body, args.threadId, args.path, args.line, repo.connectionId ?? null, args.prRepo ?? null, ...this.getLocalGitExecutionOptionArgs(repo) ) } async listGitHubProjects(): Promise>> { return listAccessibleProjects() } async listGitHubLabelsBySlug( args: ListLabelsBySlugArgs ): Promise>> { return listLabelsBySlug(args) } async listGitHubAssignableUsersBySlug( args: ListAssignableUsersBySlugArgs ): Promise>> { return listAssignableUsersBySlug(args) } async listGitHubIssueTypesBySlug( args: ListIssueTypesBySlugArgs ): Promise>> { return listIssueTypesBySlug(args) } async resolveGitHubProjectRef( args: ResolveProjectRefArgs ): Promise>> { return resolveProjectRef(args) } async listGitHubProjectViews( args: ListProjectViewsArgs ): Promise>> { return listProjectViews(args) } async getGitHubProjectViewTable( args: GetProjectViewTableArgs ): Promise>> { return getProjectViewTable(args) } async getGitHubProjectWorkItemDetailsBySlug( args: ProjectWorkItemDetailsBySlugArgs ): Promise>> { return getWorkItemDetailsBySlug(args) } async updateGitHubProjectItemField( args: UpdateProjectItemFieldArgs ): Promise>> { return updateProjectItemFieldValue(args) } async clearGitHubProjectItemField( args: ClearProjectItemFieldArgs ): Promise>> { return clearProjectItemFieldValue(args) } async updateGitHubIssueBySlug( args: UpdateIssueBySlugArgs ): Promise>> { return updateIssueBySlug(args) } async updateGitHubPullRequestBySlug( args: UpdatePullRequestBySlugArgs ): Promise>> { return updatePullRequestBySlug(args) } async updateGitHubIssueTypeBySlug( args: UpdateIssueTypeBySlugArgs ): Promise>> { return updateIssueTypeBySlug(args) } async addGitHubIssueCommentBySlug( args: AddIssueCommentBySlugArgs ): Promise>> { return addIssueCommentBySlug(args) } async updateGitHubIssueCommentBySlug( args: UpdateIssueCommentBySlugArgs ): Promise>> { return updateIssueCommentBySlug(args) } async deleteGitHubIssueCommentBySlug( args: DeleteIssueCommentBySlugArgs ): Promise>> { return deleteIssueCommentBySlug(args) } private getSetupHookTrustPayload( repo: Repo, scriptContentValue: string | undefined ): { contentHash: string; scriptContent: string } | undefined { const scriptContent = scriptContentValue?.trim() if (!scriptContent || repo.hookSettings?.commandSourcePolicy === 'local-only') { return undefined } return { contentHash: createHash('sha256').update(scriptContent).digest('hex'), scriptContent } } private getSharedSetupHookTrustPayload( repo: Repo, sharedSetupScript: string | undefined ): { contentHash: string; scriptContent: string } | undefined { if (repo.hookSettings?.commandSourcePolicy === 'local-only') { return undefined } return this.getSetupHookTrustPayload(repo, sharedSetupScript) } async getRepoHooks(repoSelector: string) { const repo = await this.resolveRepoSelector(repoSelector) if (repo.connectionId) { const fsProvider = getSshFilesystemProvider(repo.connectionId) if (!fsProvider) { return { hasHooksFile: false, hooks: null, setupRunPolicy: getEffectiveSetupRunPolicy(repo), source: null } } try { const result = await fsProvider.readFile(joinWorktreeRelativePath(repo.path, 'orca.yaml')) const hooks = result.isBinary ? null : parseOrcaYaml(result.content) return { hasHooksFile: Boolean(hooks), hooks, setupRunPolicy: getEffectiveSetupRunPolicy(repo), source: hooks ? 'orca.yaml' : null, setupTrust: this.getSharedSetupHookTrustPayload( repo, getDefaultTabCommandTrustContent(hooks) ) } } catch { return { hasHooksFile: false, hooks: null, setupRunPolicy: getEffectiveSetupRunPolicy(repo), source: null } } } const hasFile = hasHooksFile(repo.path) const hooks = getEffectiveHooks(repo) const sharedHooks = hasFile ? loadHooks(repo.path) : null const setupRunPolicy = getEffectiveSetupRunPolicy(repo) return { hasHooksFile: hasFile, hooks, setupRunPolicy, source: hasFile ? 'orca.yaml' : hooks ? 'legacy' : null, setupTrust: this.getSharedSetupHookTrustPayload( repo, getDefaultTabCommandTrustContent(sharedHooks) ) } } async checkRepoHooks(repoSelector: string) { const repo = await this.resolveRepoSelector(repoSelector) if (isFolderRepo(repo)) { return { hasHooks: false, hooks: null, mayNeedUpdate: false } } if (repo.connectionId) { const fsProvider = getSshFilesystemProvider(repo.connectionId) if (!fsProvider) { return { hasHooks: false, hooks: null, mayNeedUpdate: false } } try { const result = await fsProvider.readFile(joinWorktreeRelativePath(repo.path, 'orca.yaml')) if (result.isBinary) { return { hasHooks: false, hooks: null, mayNeedUpdate: false } } return { hasHooks: true, hooks: parseOrcaYaml(result.content), mayNeedUpdate: false } } catch { return { hasHooks: false, hooks: null, mayNeedUpdate: false } } } const has = hasHooksFile(repo.path) const hooks = has ? loadHooks(repo.path) : null return { hasHooks: has, hooks, mayNeedUpdate: has && !hooks && hasUnrecognizedOrcaYamlKeys(repo.path) } } async inspectRepoSetupScriptImports(repoSelector: string) { const repo = await this.resolveRepoSelector(repoSelector) if (isFolderRepo(repo)) { return [] } return inspectSetupScriptImportCandidates(async (relativePath) => { const filePath = joinWorktreeRelativePath(repo.path, relativePath) if (repo.connectionId) { const fsProvider = getSshFilesystemProvider(repo.connectionId) if (!fsProvider) { return null } try { const result = await fsProvider.readFile(filePath) return result.isBinary ? null : result.content } catch { return null } } try { return await readFile(filePath, 'utf-8') } catch (error) { if (!isENOENT(error)) { console.warn('[runtime] Failed to inspect setup script import candidate:', error) } return null } }) } async readRepoIssueCommand(repoSelector: string) { const repo = await this.resolveRepoSelector(repoSelector) if (isFolderRepo(repo)) { return { localContent: null, sharedContent: null, effectiveContent: null, localFilePath: '', source: 'none' as const } } if (repo.connectionId) { const issueCommandPath = joinWorktreeRelativePath(repo.path, '.orca/issue-command') const fsProvider = getSshFilesystemProvider(repo.connectionId) if (!fsProvider) { return { localContent: null, sharedContent: null, effectiveContent: null, localFilePath: issueCommandPath, source: 'none' as const } } const localContent = await this.readRemoteIssueCommandOverride(fsProvider, issueCommandPath) const sharedContent = await this.readRemoteSharedIssueCommand(fsProvider, repo.path) const effectiveContent = localContent ?? sharedContent return { localContent, sharedContent, effectiveContent, localFilePath: issueCommandPath, source: localContent ? ('local' as const) : sharedContent ? ('shared' as const) : ('none' as const) } } return readIssueCommand(repo.path) } private async readRemoteIssueCommandOverride( fsProvider: IFilesystemProvider, issueCommandPath: string ): Promise { try { const result = await fsProvider.readFile(issueCommandPath) if (result.isBinary) { return null } return result.content.trim() || null } catch { return null } } private async readRemoteSharedIssueCommand( fsProvider: IFilesystemProvider, repoPath: string ): Promise { try { const result = await fsProvider.readFile(joinWorktreeRelativePath(repoPath, 'orca.yaml')) if (result.isBinary) { return null } return parseOrcaYaml(result.content)?.issueCommand?.trim() || null } catch { return null } } async writeRepoIssueCommand(repoSelector: string, content: string): Promise<{ ok: true }> { const repo = await this.resolveRepoSelector(repoSelector) if (isFolderRepo(repo)) { return { ok: true } } if (repo.connectionId) { const issueCommandPath = joinWorktreeRelativePath(repo.path, '.orca/issue-command') const fsProvider = getSshFilesystemProvider(repo.connectionId) if (!fsProvider) { return { ok: true } } const trimmed = content.trim() if (!trimmed) { await fsProvider.deletePath(issueCommandPath, false).catch((error: unknown) => { if (!isENOENT(error)) { throw error } }) return { ok: true } } await fsProvider.createDir(joinWorktreeRelativePath(repo.path, '.orca')) await this.ensureRemoteOrcaDirIgnored(fsProvider, repo.path) await fsProvider.writeFile(issueCommandPath, `${trimmed}\n`) return { ok: true } } writeIssueCommand(repo.path, content) return { ok: true } } private async ensureRemoteOrcaDirIgnored( fsProvider: IFilesystemProvider, repoPath: string, options: { required?: boolean } = {} ): Promise { const gitignorePath = joinWorktreeRelativePath(repoPath, '.gitignore') let result: Awaited> try { result = await fsProvider.readFile(gitignorePath) } catch (error) { if (!isENOENT(error)) { if (options.required) { throw error } console.warn('[runtime] Could not inspect remote .gitignore for .orca', error) return } try { await fsProvider.writeFile(gitignorePath, '.orca\n') } catch (writeError) { if (options.required) { throw writeError } console.warn('[runtime] Could not update remote .gitignore to exclude .orca', writeError) } return } if (result.isBinary) { if (options.required) { throw new Error('Remote .gitignore is binary; cannot verify .orca is ignored') } return } if (/^\.orca\/?$/m.test(result.content)) { return } const separator = result.content.endsWith('\n') ? '' : '\n' try { await fsProvider.writeFile(gitignorePath, `${result.content}${separator}.orca\n`) } catch (writeError) { if (options.required) { throw writeError } console.warn('[runtime] Could not update remote .gitignore to exclude .orca', writeError) } } async listManagedWorktrees( repoSelector?: string, limit = DEFAULT_WORKTREE_LIST_LIMIT ): Promise { if (!Number.isInteger(limit) || limit <= 0) { throw new Error('invalid_limit') } const resolved = await this.listResolvedWorktrees() const repoId = repoSelector ? (await this.resolveRepoSelector(repoSelector)).id : null const worktrees = resolved.filter((worktree) => { if (repoId && worktree.repoId !== repoId) { return false } return this.isRuntimeWorktreeVisible(worktree) }) return { worktrees: worktrees.slice(0, limit), totalCount: worktrees.length, truncated: worktrees.length > limit } } async listDetectedManagedWorktrees(repoSelector: string): Promise { const repo = await this.resolveRepoSelector(repoSelector) if (isFolderRepo(repo)) { const worktrees = listRuntimeFolderWorkspaces(this.requireStore(), repo) return { repoId: repo.id, authoritative: true, source: 'git', worktrees: worktrees.map((worktree) => this.toRuntimeDetectedWorktree(repo, worktree)) } } let scan: RuntimeWorktreeScanResult try { scan = await this.listRepoWorktreesForResolution(repo) } catch { scan = { ok: false, worktrees: [] } } if (scan.ok) { this.pruneLineageForMissingRepoWorktrees(repo, scan.worktrees) } const detected = scan.worktrees.map((gitWorktree) => { const worktreeId = `${repo.id}::${gitWorktree.path}` const meta = this.store?.getWorktreeMeta(worktreeId) const worktree = mergeWorktree(repo.id, gitWorktree, meta, repo.displayName) const detectedWorktree = this.toRuntimeDetectedWorktree(repo, worktree) if (scan.ok) { return detectedWorktree } return { ...detectedWorktree, visible: true, ownership: detectedWorktree.ownership === 'orca-managed' ? 'orca-managed' : 'unknown-legacy' } satisfies DetectedWorktree }) return { repoId: repo.id, authoritative: scan.ok, source: scan.ok ? 'git' : 'metadata-fallback', worktrees: detected } } private isRuntimeWorktreeVisible(worktree: Worktree): boolean { const repo = this.store?.getRepo(worktree.repoId) if (!repo || !this.store) { return true } return this.toRuntimeDetectedWorktree(repo, worktree).visible } private toRuntimeDetectedWorktree(repo: Repo, worktree: Worktree): DetectedWorktree { const settings = this.store?.getSettings() if (!settings) { return { ...worktree, ownership: 'unknown-legacy', selectedCheckout: false, visible: true } } return toDetectedWorktree({ repo, worktree, meta: this.store?.getWorktreeMeta(worktree.id), settings, knownOrcaLayouts: buildKnownOrcaWorkspaceLayouts(settings, repo), isLegacyRepoForVisibility: isLegacyRepoForExternalWorktreeVisibility(repo) }) } async showManagedWorktree(worktreeSelector: string) { return await this.resolveWorktreeSelector(worktreeSelector) } async scanWorkspacePorts(repoId?: string): Promise { return scanWorkspacePortProbes(await this.getWorkspacePortProbes(repoId)) } async killWorkspacePort(args: WorkspacePortKillRequest): Promise { return killWorkspacePort(await this.getWorkspacePortProbes(args.repoId), args) } // Why: remote clients may invoke this over RPC, so the runtime derives // allowed worktree paths from its own store instead of trusting client paths. private async getWorkspacePortProbes(repoId?: string): Promise { const reposById = new Map( this.requireStore() .getRepos() .map((repo) => [repo.id, repo]) ) return filterWorkspacePortProbes( (await this.listResolvedWorktrees()).map((worktree) => ({ id: worktree.id, repoId: worktree.repoId, displayName: worktree.displayName, path: worktree.git.path, connectionId: reposById.get(worktree.repoId)?.connectionId ?? null })), repoId ) } async sleepManagedWorktree(worktreeSelector: string): Promise<{ worktreeId: string }> { const worktree = await this.resolveWorktreeSelector(worktreeSelector) // Why: sleep is renderer-initiated on desktop (it tears down tab state // before killing PTYs). The notifier tells the renderer to run its own // sleep flow so all cleanup happens in the correct order. this.notifier?.sleepWorktree(worktree.id) return { worktreeId: worktree.id } } async activateManagedWorktree( worktreeSelector: string, opts: { notifyClients?: boolean } = {} ): Promise<{ repoId: string worktreeId: string activated: boolean }> { this.assertGraphReady() const worktree = await this.resolveWorktreeSelector(worktreeSelector) const repo = this.store?.getRepo(worktree.repoId) if (!repo) { throw new Error('repo_not_found') } if (opts.notifyClients === false && this.store?.getWorktreeMeta(worktree.id)?.isUnread) { // Why: mobile/web session activation intentionally bypasses renderer // selection, so the runtime must acknowledge the unread state itself. this.store.setWorktreeMeta(worktree.id, { isUnread: false }) this.notifyWorktreesChanged(repo.id) } if (opts.notifyClients !== false) { // Why: inactive worktree terminal panes are renderer-owned and may not have // live PTYs until the desktop activates the worktree and mounts them. this.notifyActivateWorktree(repo.id, worktree.id) } else { // Why: mobile/web selection needs fresh session surfaces without forcing // every attached desktop renderer to navigate to the phone's workspace. this.hydrateHeadlessMobileSessionTabsFromWorkspaceSession(worktree.id, { allowAttachedWindow: true }) await this.refreshMobileSessionPtyRecords() this.notifyMobileSessionTabsChanged(worktree.id) } return { repoId: repo.id, worktreeId: worktree.id, activated: true } } private async buildStartupForDraft( repo: Repo, draft: string, requestedAgent?: TuiAgent ): Promise<{ agent: TuiAgent startup: WorktreeStartupLaunch draftPaste?: WorktreeStartupDraftPaste } | null> { if (!this.store) { return null } const content = draft.trim() if (!content) { return null } const settings = this.store.getSettings() const preferredAgent = requestedAgent ?? settings.defaultTuiAgent if (preferredAgent === 'blank') { // Why: `blank` is an explicit user preference to create a shell-only // workspace, so linked task drafts must not auto-pick a detected agent. return null } let agent = isTuiAgent(preferredAgent) && isTuiAgentEnabled(preferredAgent, settings.disabledTuiAgents) ? preferredAgent : null if (!agent) { let detected: string[] = [] try { // Why: startup-draft fallback can run from sparse runtime launch envs too. detected = repo.connectionId ? await detectRemoteAgents({ connectionId: repo.connectionId }) : await detectInstalledAgentsWithShellPathHydration() } catch { detected = [] } const typedDetected = detected.filter(isTuiAgent) agent = pickTuiAgent(null, typedDetected, settings.disabledTuiAgents) } if (!agent) { return null } // Why: a mobile client can run on Windows while the workspace shell is // Linux over SSH. Startup command quoting must target the shell that runs it. const agentLaunchPlatform = this.getAgentLaunchPlatformForRepo(repo) const isRemote = repoIsRemote(repo) const draftLaunchPlan = buildAgentDraftLaunchPlan({ agent, draft: content, cmdOverrides: settings.agentCmdOverrides ?? {}, agentArgs: resolveTuiAgentLaunchArgs(agent, settings.agentDefaultArgs), agentEnv: resolveTuiAgentLaunchEnv(agent, settings.agentDefaultEnv), platform: agentLaunchPlatform, isRemote }) if (draftLaunchPlan) { return { agent, startup: { command: draftLaunchPlan.launchCommand, launchConfig: draftLaunchPlan.launchConfig, ...(draftLaunchPlan.startupCommandDelivery ? { startupCommandDelivery: draftLaunchPlan.startupCommandDelivery } : {}), ...(draftLaunchPlan.env ? { env: draftLaunchPlan.env } : {}) } } } const startupPlan = buildAgentStartupPlan({ agent, prompt: '', cmdOverrides: settings.agentCmdOverrides ?? {}, agentArgs: resolveTuiAgentLaunchArgs(agent, settings.agentDefaultArgs), agentEnv: resolveTuiAgentLaunchEnv(agent, settings.agentDefaultEnv), platform: agentLaunchPlatform, isRemote, allowEmptyPromptLaunch: true }) if (!startupPlan) { return null } return { agent, startup: { command: startupPlan.launchCommand, launchConfig: startupPlan.launchConfig, ...(startupPlan.startupCommandDelivery ? { startupCommandDelivery: startupPlan.startupCommandDelivery } : {}), ...(startupPlan.env ? { env: startupPlan.env } : {}) }, draftPaste: { agent, content } } } private buildStartupForAgent( repo: Repo, agent: TuiAgent, prompt: string | undefined ): { agent: TuiAgent; startup: WorktreeStartupLaunch; followup?: WorktreeStartupFollowup } { if (!this.store) { throw new Error('runtime_unavailable') } const settings = this.store.getSettings() if (!isTuiAgentEnabled(agent, settings.disabledTuiAgents)) { throw new Error('Selected agent is disabled. Choose an enabled agent before creating.') } // Why: CLI clients may target SSH runtimes from macOS/Windows, so quote for // the workspace shell rather than the client shell. const agentLaunchPlatform = this.getAgentLaunchPlatformForRepo(repo) const startupPlan = buildAgentStartupPlan({ agent, prompt: prompt ?? '', cmdOverrides: settings.agentCmdOverrides ?? {}, agentArgs: resolveTuiAgentLaunchArgs(agent, settings.agentDefaultArgs), agentEnv: resolveTuiAgentLaunchEnv(agent, settings.agentDefaultEnv), platform: agentLaunchPlatform, isRemote: repoIsRemote(repo), allowEmptyPromptLaunch: true }) if (!startupPlan) { throw new Error(`Could not build launch command for ${agent}.`) } return { agent, startup: { command: startupPlan.launchCommand, launchConfig: startupPlan.launchConfig, ...(startupPlan.startupCommandDelivery ? { startupCommandDelivery: startupPlan.startupCommandDelivery } : {}), ...(startupPlan.env ? { env: startupPlan.env } : {}) }, ...(startupPlan.followupPrompt ? { followup: { expectedProcess: startupPlan.expectedProcess, prompt: startupPlan.followupPrompt } } : {}) } } private markLocalWorkspaceTrustedForAgent(agent: TuiAgent, workspacePath: string): void { const preset = TUI_AGENT_CONFIG[agent].preflightTrust if (!preset) { return } try { if (preset === 'cursor') { markCursorWorkspaceTrusted(workspacePath) } else if (preset === 'copilot') { markCopilotFolderTrusted(workspacePath) } else if (preset === 'codex') { markCodexProjectTrusted(workspacePath) } } catch { // Best-effort: the user can still accept the agent trust prompt manually. } } private async markRemoteWorkspaceTrustedForAgent( agent: TuiAgent, connectionId: string, workspacePath: string ): Promise { const preset = TUI_AGENT_CONFIG[agent].preflightTrust if (!preset) { return } try { await markRemoteAgentWorkspaceTrusted({ preset, connectionId, workspacePath }) } catch { // Best-effort: the user can still accept the remote agent trust prompt manually. } } private recordCreatedWorktreeLineage( worktree: Pick, lineageResolution: WorktreeLineageResolution ): { lineage: WorktreeLineage | null workspaceLineage: WorkspaceLineage | null warnings: WorktreeLineageWarning[] } { const warnings = lineageResolution.kind === 'none' ? [...lineageResolution.warnings] : [] let lineage: WorktreeLineage | null = null let workspaceLineage: WorkspaceLineage | null = null if (lineageResolution.kind !== 'lineage') { return { lineage, workspaceLineage, warnings } } const childInstanceId = worktree.instanceId const parentInstanceId = lineageResolution.parent.instanceId const createdAt = Date.now() if ( lineageResolution.parent.type === 'worktree' && childInstanceId && parentInstanceId && this.store?.setWorktreeLineage ) { lineage = this.store.setWorktreeLineage(worktree.id, { worktreeId: worktree.id, worktreeInstanceId: childInstanceId, parentWorktreeId: lineageResolution.parent.worktree.id, parentWorktreeInstanceId: parentInstanceId, origin: lineageResolution.origin, capture: lineageResolution.capture, ...(lineageResolution.orchestrationRunId ? { orchestrationRunId: lineageResolution.orchestrationRunId } : {}), ...(lineageResolution.taskId ? { taskId: lineageResolution.taskId } : {}), ...(lineageResolution.coordinatorHandle ? { coordinatorHandle: lineageResolution.coordinatorHandle } : {}), ...(lineageResolution.createdByTerminalHandle ? { createdByTerminalHandle: lineageResolution.createdByTerminalHandle } : {}), createdAt }) } else if (lineageResolution.parent.type === 'worktree') { warnings.push({ code: 'LINEAGE_PARENT_CONTEXT_MISSING', message: 'Worktree created, but Orca could not record lineage because instance identity was unavailable.', details: { childHasInstanceId: Boolean(childInstanceId), parentHasInstanceId: Boolean(parentInstanceId), storeSupportsLineage: Boolean(this.store?.setWorktreeLineage) } }) } if (childInstanceId && this.store?.setWorkspaceLineage) { workspaceLineage = this.store.setWorkspaceLineage({ childWorkspaceKey: worktreeWorkspaceKey(worktree.id), childInstanceId, parentWorkspaceKey: lineageResolution.parent.workspaceKey, parentInstanceId, origin: lineageResolution.origin, capture: lineageResolution.capture, ...(lineageResolution.taskId ? { taskId: lineageResolution.taskId } : {}), ...(lineageResolution.orchestrationRunId ? { orchestrationRunId: lineageResolution.orchestrationRunId } : {}), ...(lineageResolution.coordinatorHandle ? { coordinatorHandle: lineageResolution.coordinatorHandle } : {}), ...(lineageResolution.createdByTerminalHandle ? { createdByTerminalHandle: lineageResolution.createdByTerminalHandle } : {}), createdAt }) } return { lineage, workspaceLineage, warnings } } private pasteStartupDraftWhenReady(handle: string, draft: WorktreeStartupDraftPaste): void { void this.waitForStartupDraftReady(handle, draft.agent) .then((ptyId) => { if (!ptyId) { console.warn('[worktree-create] agent did not become ready for draft paste') return } this.ptyController?.write( ptyId, `${BRACKETED_PASTE_BEGIN}${draft.content}${BRACKETED_PASTE_END}` ) }) .catch((error) => { console.warn('[worktree-create] failed to paste startup draft:', error) }) } private sendStartupFollowupWhenReady(handle: string, followup: WorktreeStartupFollowup): void { void this.waitForStartupFollowupReady(handle, followup.expectedProcess) .then((ptyId) => { if (!ptyId) { console.warn('[worktree-create] agent did not become ready for follow-up prompt') return } this.ptyController?.write(ptyId, `${followup.prompt}\r`) }) .catch((error) => { console.warn('[worktree-create] failed to send startup follow-up prompt:', error) }) } private async createDefaultTabTerminals( worktreeSelector: string, worktreeId: string, defaultTabs: CreateWorktreeResult['defaultTabs'] | undefined ): Promise { if (!defaultTabs || defaultTabs.tabs.length === 0 || !this.ptyController?.spawn) { return [] } const handles: string[] = [] for (const template of defaultTabs.tabs) { try { const command = template.command?.trim() const terminal = await this.createTerminal(worktreeSelector, { ...(template.title ? { title: template.title } : {}), ...(command && defaultTabs.runCommands ? { command } : {}) }) handles.push(terminal.handle) if (template.color && terminal.tabId) { await this.setMobileSessionTabProps(`id:${worktreeId}`, { tabId: terminal.tabId, color: template.color }) } } catch (error) { console.warn(`[worktree-create] Failed to create default tab for ${worktreeId}:`, error) } } return handles } private async provisionManagedWorktreeTerminals(args: { worktreeSelector: string worktreeId: string worktreePath: string setup?: CreateWorktreeResult['setup'] defaultTabs?: CreateWorktreeResult['defaultTabs'] primaryTerminalHandle?: string | null hasStartupTerminal: boolean setupCommandPlatform: 'windows' | 'posix' // Why: when the agent startup is sequenced to wait for setup // (waitForAgentStartup), the startup PTY runs a wrapper that already embeds // the setup command. Pass that wrapped command through so the Setup tab runs // the same script the agent is waiting on instead of a bare runner. wrappedSetupCommand?: string }): Promise<{ setupSpawned: boolean }> { if (!this.ptyController?.spawn) { return { setupSpawned: false } } let setupSpawned = false try { const defaultTabHandles = await this.createDefaultTabTerminals( args.worktreeSelector, args.worktreeId, args.defaultTabs ) let primaryTerminalHandle = args.primaryTerminalHandle ?? defaultTabHandles[0] ?? null const setupLaunchMode = ( this.requireStore().getSettings() as Partial< Pick > ).setupScriptLaunchMode ?? 'new-tab' if (!args.hasStartupTerminal && !primaryTerminalHandle) { const terminal = await this.createTerminal(args.worktreeSelector) primaryTerminalHandle = terminal.handle } if (args.setup) { const setupCommand = args.wrappedSetupCommand ?? buildSetupRunnerCommand(args.setup.runnerScriptPath, args.setupCommandPlatform) const shouldSplitSetup = primaryTerminalHandle && (setupLaunchMode === 'split-vertical' || setupLaunchMode === 'split-horizontal') await (shouldSplitSetup ? this.splitTerminal(primaryTerminalHandle!, { direction: setupLaunchMode === 'split-horizontal' ? 'horizontal' : 'vertical', command: setupCommand, env: args.setup.envVars, activate: false }) : this.createTerminal(args.worktreeSelector, { title: 'Setup', command: setupCommand, env: args.setup.envVars })) setupSpawned = true } } catch (err) { const message = err instanceof Error ? err.message : String(err) console.warn( `[worktree-create] Failed to create setup/default terminals for ${args.worktreePath}: ${message}` ) } return { setupSpawned } } private async waitForStartupFollowupReady( handle: string, expectedProcess: string ): Promise { const livePty = this.getLivePtyForHandle(handle) const ptyId = livePty?.pty.ptyId if (!ptyId || !this.ptyController) { return null } for (let attempt = 0; attempt < 30; attempt += 1) { if (attempt > 0) { await new Promise((resolve) => setTimeout(resolve, 150)) } try { const foregroundProcess = await this.ptyController.getForegroundProcess(ptyId) if (isExpectedAgentProcess(foregroundProcess, expectedProcess)) { return ptyId } if (attempt >= 4 && !isShellProcess(foregroundProcess ?? '')) { const hasChildProcesses = (await this.ptyController.hasChildProcesses?.(ptyId).catch(() => false)) ?? false if (hasChildProcesses) { return ptyId } } } catch { // Ignore transient PTY inspection failures and keep polling. } } return null } private waitForStartupDraftReady(handle: string, agent: TuiAgent): Promise { const livePty = this.getLivePtyForHandle(handle) const ptyId = livePty?.pty.ptyId if (!ptyId) { return Promise.resolve(null) } const readySignal = TUI_AGENT_CONFIG[agent].draftPasteReadySignal ?? 'render-quiet-after-bracketed-paste' return new Promise((resolve) => { let settled = false const scanner = createDraftPasteReadyScanner(readySignal) let quietTimer: NodeJS.Timeout | null = null let hardTimer: NodeJS.Timeout | null = null let unsubscribe: (() => void) | null = null const finish = (value: string | null): void => { if (settled) { return } settled = true if (quietTimer) { clearTimeout(quietTimer) } if (hardTimer) { clearTimeout(hardTimer) } unsubscribe?.() resolve(value) } const armQuietTimer = (): void => { if (quietTimer) { clearTimeout(quietTimer) } quietTimer = setTimeout(() => finish(ptyId), BRACKETED_PASTE_QUIET_MS) } const observeData = (data: string): void => { const { ready, armQuietTimer: shouldArm } = scanner.observe(data) if (ready) { finish(ptyId) return } if (shouldArm) { armQuietTimer() } } unsubscribe = this.subscribeToTerminalData(ptyId, observeData) const replay = this.recentPtyOutputById.get(ptyId) if (replay) { observeData(replay) } hardTimer = setTimeout(() => finish(null), DRAFT_PASTE_READY_TIMEOUT_MS) }) } async prefetchManagedWorktreeCreateBase(args: { repoSelector: string baseBranch?: string }): Promise { if (!this.store) { throw new Error('runtime_unavailable') } const repo = await this.resolveRepoSelector(args.repoSelector) await prefetchWorktreeCreateBase({ repo, baseBranch: args.baseBranch, runtime: this }) } async createManagedWorktree(args: { repoSelector: string name: string baseBranch?: string compareBaseRef?: string branchNameOverride?: string linkedIssue?: number | null linkedPR?: number | null linkedLinearIssue?: string linkedLinearIssueWorkspaceId?: string | null linkedLinearIssueOrganizationUrlKey?: string | null linkedGitLabMR?: number | null linkedGitLabIssue?: number | null linkedBitbucketPR?: number | null linkedAzureDevOpsPR?: number | null linkedGiteaPR?: number | null comment?: string displayName?: string telemetrySource?: WorkspaceCreateTelemetrySource workspaceStatus?: string manualOrder?: number sparseCheckout?: { directories: string[]; presetId?: string } pushTarget?: GitPushTarget runHooks?: boolean activate?: boolean setupDecision?: 'run' | 'skip' | 'inherit' createdWithAgent?: TuiAgent startupAgent?: TuiAgent startupPrompt?: string pendingFirstAgentMessageRename?: boolean automationProvenance?: AutomationWorkspaceProvenance startup?: WorktreeStartupLaunch startupDraft?: string startupDraftPaste?: WorktreeStartupDraftPaste lineage?: WorktreeLineageInput }): Promise { if (!this.store) { throw new Error('runtime_unavailable') } const repo = await this.resolveRepoSelector(args.repoSelector) const createSettings = this.store.getSettings() const requestedAgent = args.startupAgent ?? args.createdWithAgent const requestedAgentEnabled = requestedAgent !== undefined ? isTuiAgentEnabled(requestedAgent, createSettings.disabledTuiAgents) : false if ((args.startup || args.startupAgent) && requestedAgent && !requestedAgentEnabled) { throw new Error('Selected agent is disabled. Choose an enabled agent before creating.') } if ( args.startup && args.startupDraftPaste && !isTuiAgentEnabled(args.startupDraftPaste.agent, createSettings.disabledTuiAgents) ) { throw new Error('Selected agent is disabled. Choose an enabled agent before creating.') } const agentStartup = !args.startup && args.startupAgent ? this.buildStartupForAgent(repo, args.startupAgent, args.startupPrompt) : null const draftStartup = !args.startup && !agentStartup && args.startupDraft ? await this.buildStartupForDraft(repo, args.startupDraft, requestedAgent) : null const effectiveStartup = args.startup ?? agentStartup?.startup ?? draftStartup?.startup const effectiveStartupFollowup = agentStartup?.followup const effectiveCreatedWithAgent = args.startup ? args.createdWithAgent : (agentStartup?.agent ?? draftStartup?.agent ?? (requestedAgentEnabled ? requestedAgent : undefined)) const effectiveDraftPaste = args.startupDraftPaste ?? draftStartup?.draftPaste if (isFolderRepo(repo)) { const now = Date.now() const settings = createSettings const instanceId = randomUUID() const worktreeId = getRuntimeFolderWorkspaceInstanceId(repo, instanceId) const meta = this.store.setWorktreeMeta(worktreeId, { instanceId, ...getProjectHostSetupWorktreeMeta(this.store.getProjectHostSetups?.() ?? [], repo), displayName: args.displayName?.trim() || args.name, lastActivityAt: now, createdAt: now, orcaCreatedAt: now, orcaCreationSource: 'runtime', orcaCreationWorkspaceLayout: { path: settings.workspaceDir, nestWorkspaces: settings.nestWorkspaces }, ...(args.automationProvenance ? { automationProvenance: args.automationProvenance } : {}), ...(args.linkedIssue !== undefined ? { linkedIssue: args.linkedIssue } : {}), ...(args.linkedPR !== undefined ? { linkedPR: args.linkedPR } : {}), ...(args.linkedLinearIssue !== undefined ? { linkedLinearIssue: args.linkedLinearIssue } : {}), ...(args.linkedLinearIssueWorkspaceId !== undefined ? { linkedLinearIssueWorkspaceId: args.linkedLinearIssueWorkspaceId } : {}), ...(args.linkedLinearIssueOrganizationUrlKey !== undefined ? { linkedLinearIssueOrganizationUrlKey: args.linkedLinearIssueOrganizationUrlKey } : {}), ...(args.linkedGitLabIssue !== undefined ? { linkedGitLabIssue: args.linkedGitLabIssue } : {}), ...(args.linkedGitLabMR !== undefined ? { linkedGitLabMR: args.linkedGitLabMR } : {}), ...(args.linkedBitbucketPR !== undefined ? { linkedBitbucketPR: args.linkedBitbucketPR } : {}), ...(args.linkedAzureDevOpsPR !== undefined ? { linkedAzureDevOpsPR: args.linkedAzureDevOpsPR } : {}), ...(args.linkedGiteaPR !== undefined ? { linkedGiteaPR: args.linkedGiteaPR } : {}), ...(effectiveCreatedWithAgent ? { createdWithAgent: effectiveCreatedWithAgent } : {}), ...(args.comment !== undefined ? { comment: args.comment } : {}), ...(args.manualOrder !== undefined ? { manualOrder: args.manualOrder } : {}), ...(args.workspaceStatus !== undefined ? { workspaceStatus: args.workspaceStatus } : {}) }) const worktree = mergeRuntimeFolderWorkspace(repo, worktreeId, meta) this.invalidateResolvedWorktreeCache() this.notifyWorktreesChanged(repo.id) const shouldActivate = args.activate === true || args.runHooks === true let warning: string | undefined let didSpawnStartup = false if (effectiveStartup && this.ptyController?.spawn) { try { const startupTrustAgent = effectiveDraftPaste?.agent ?? effectiveCreatedWithAgent if (startupTrustAgent) { this.markLocalWorkspaceTrustedForAgent(startupTrustAgent, worktree.path) } const terminal = await this.createTerminal(`id:${worktree.id}`, { command: effectiveStartup.command, env: effectiveStartup.env, ...(effectiveStartup.launchConfig ? { launchConfig: effectiveStartup.launchConfig } : {}), ...(effectiveCreatedWithAgent ? { launchAgent: effectiveCreatedWithAgent } : {}), startupCommandDelivery: effectiveStartup.startupCommandDelivery, telemetry: effectiveStartup.telemetry }) if (effectiveDraftPaste) { this.pasteStartupDraftWhenReady(terminal.handle, effectiveDraftPaste) } if (effectiveStartupFollowup) { this.sendStartupFollowupWhenReady(terminal.handle, effectiveStartupFollowup) } didSpawnStartup = true } catch (err) { const message = err instanceof Error ? err.message : String(err) warning = `Failed to create the startup terminal for ${worktree.path}: ${message}` console.warn(`[worktree-create] ${warning}`) } } if (shouldActivate) { if (effectiveStartup && !didSpawnStartup) { this.notifyActivateWorktree(repo.id, worktree.id, undefined, effectiveStartup) } else { this.notifyActivateWorktree(repo.id, worktree.id) } } else if (this.ptyController?.spawn && !didSpawnStartup) { try { await this.createTerminal(`id:${worktree.id}`) } catch (err) { const message = err instanceof Error ? err.message : String(err) warning = warning ? `${warning} Also failed to create the initial terminal for ${worktree.path}: ${message}` : `Failed to create the initial terminal for ${worktree.path}: ${message}` console.warn(`[worktree-create] ${warning}`) } } return { worktree: { ...worktree, parentWorktreeId: null, childWorktreeIds: [], lineage: null, git: { path: worktree.path, head: worktree.head, branch: worktree.branch, isBare: worktree.isBare, isMainWorktree: worktree.isMainWorktree } }, ...(warning ? { warning } : {}) } } const lineageInput = args.lineage || args.comment ? { ...args.lineage, comment: args.comment } : undefined const lineageResolution = await this.resolveLineageForWorktreeCreate(lineageInput) if (repo.connectionId) { const result = await this.createManagedRemoteWorktree(repo, { ...args, activate: args.activate, ...(effectiveStartup ? { startup: effectiveStartup } : {}), ...(effectiveStartupFollowup ? { startupFollowup: effectiveStartupFollowup } : {}), ...(effectiveCreatedWithAgent ? { createdWithAgent: effectiveCreatedWithAgent } : {}), ...(effectiveDraftPaste ? { startupDraftPaste: effectiveDraftPaste } : {}) }) const recordedLineage = this.recordCreatedWorktreeLineage(result.worktree, lineageResolution) return { ...result, worktree: { ...result.worktree, parentWorktreeId: recordedLineage.lineage?.parentWorktreeId ?? null, childWorktreeIds: result.worktree.childWorktreeIds ?? [], lineage: recordedLineage.lineage, workspaceLineage: recordedLineage.workspaceLineage }, ...(lineageInput ? { lineage: recordedLineage.lineage, workspaceLineage: recordedLineage.workspaceLineage, warnings: recordedLineage.warnings } : {}) } } const settings = createSettings const worktreePathSettings = getWorktreePathSettings(repo, settings) const localGitExecOptions = getLocalProjectGitExecOptions(this.requireStore(), repo) const localWorktreeGitOptions = getLocalProjectWorktreeGitOptions(this.requireStore(), repo) const hasLocalWorktreeGitOptions = hasLocalGitOptions(localWorktreeGitOptions) const localWorktreeGitOptionArgs: [] | [{ wslDistro?: string }] = hasLocalWorktreeGitOptions ? [localWorktreeGitOptions] : [] const addProjectGitOptions = (options?: AddWorktreeOptions): AddWorktreeOptions | undefined => { if (!hasLocalWorktreeGitOptions) { return options } return { ...options, ...localWorktreeGitOptions } } const hostedReviewExecutionContext = this.getHostedReviewExecutionOptions(repo) let effectiveRequestedName = args.name const requestedDisplayName = args.displayName?.trim() || undefined const sanitizedName = sanitizeWorktreeName(args.name) let effectiveSanitizedName = sanitizedName const username = getGitUsername(repo.path) const baseBranch = args.baseBranch || repo.worktreeBaseRef || (hasLocalWorktreeGitOptions ? await resolveDefaultBaseRefViaExec((argv) => gitExecFileAsync(argv, localGitExecOptions)) : getDefaultBaseRef(repo.path)) if (!baseBranch) { // Why: getDefaultBaseRef returns null when no suitable ref exists. // Don't fabricate 'origin/main' — passing it to addWorktree would // produce an opaque git failure. Surface a clear error so the CLI // caller can pick an explicit --base ref. throw new Error( 'Could not resolve a default base ref for this repo. Pass an explicit --base and try again.' ) } const workspaceRoot = computeWorkspaceRoot(repo.path, worktreePathSettings) // Why: CLI-managed WSL worktrees live under ~/orca/workspaces inside the // distro filesystem through computeWorkspaceRoot. If home lookup fails, // still validate against the effective workspace dir. let branchName = '' let checkoutExistingBranch = false let selectedExistingLocalBranchName: string | null = null let branchConflictKind: 'local' | 'remote' | null = null let worktreePath = '' let worktreePathResolved = false // Why: runtime/mobile create-from-review callers should get a new workspace // even when the PR branch or review branch name is already in use. for (let suffix = 1; suffix <= WORKTREE_CREATE_MAX_SUFFIX_ATTEMPTS; suffix += 1) { effectiveSanitizedName = getWorktreeCreateCandidate(sanitizedName, suffix) effectiveRequestedName = args.name.trim() ? getWorktreeCreateCandidate(args.name, suffix) : effectiveSanitizedName branchName = await resolveCreateBranchName( repo.path, selectedExistingLocalBranchName ?? getBranchNameOverrideCandidate(args.branchNameOverride, suffix), effectiveSanitizedName, settings, username, localWorktreeGitOptions ) checkoutExistingBranch = await canCheckoutExistingLocalBranch( repo.path, branchName, baseBranch, ...localWorktreeGitOptionArgs ) if (checkoutExistingBranch && !selectedExistingLocalBranchName) { // Why: once a user-selected branch is safe to reuse, path retries should // keep that branch exact instead of creating a sibling branch. selectedExistingLocalBranchName = branchName } branchConflictKind = checkoutExistingBranch ? null : await getBranchConflictKind( repo.path, branchName, baseBranch, ...localWorktreeGitOptionArgs ) const allowedPushTargetRemoteConflict = branchConflictKind && isAllowedPushTargetRemoteConflict(branchConflictKind, branchName, args) let selectedReviewConflictMatched = false if (branchConflictKind) { if (allowedPushTargetRemoteConflict) { let existingPR: Awaited> | null = null const selectedReview = getSelectedReviewBranch(args) if (selectedReview?.provider === 'github') { try { existingPR = await getLocalGitHubPrForBranch( repo.path, branchName, localWorktreeGitOptions ) } catch { // Retry with a suffixed branch when selected review verification is unavailable. } if (isMatchingSelectedGitHubPr(existingPR, args, branchName)) { branchConflictKind = null selectedReviewConflictMatched = true } } else if (selectedReview) { const hostedReview = await getSelectedHostedReviewForBranch( repo, branchName, args, hostedReviewExecutionContext ).catch(() => null) if (hostedReview?.matchesSelected) { branchConflictKind = null selectedReviewConflictMatched = true } } } if (branchConflictKind) { continue } } if (!checkoutExistingBranch && !selectedReviewConflictMatched) { let existingPR: Awaited> | null = null try { existingPR = await getLocalGitHubPrForBranch( repo.path, branchName, localWorktreeGitOptions ) } catch { // Why: GitHub reachability should not block creating a suffixed // workspace; git conflicts still decide whether this candidate works. } if (existingPR && !isMatchingSelectedGitHubPr(existingPR, args, branchName)) { continue } } worktreePath = ensurePathWithinWorkspace( computeWorktreePath(effectiveSanitizedName, repo.path, worktreePathSettings), workspaceRoot ) if (!(await pathExists(worktreePath))) { worktreePathResolved = true break } } if (!worktreePathResolved) { if (branchConflictKind) { throw new Error( `Branch "${branchName}" already exists ${branchConflictKind === 'local' ? 'locally' : 'on a remote'}.` ) } throw new Error( `Could not find an available worktree path for "${sanitizedName}". Pick a different worktree name.` ) } const remoteTrackingBase = await this.resolveRemoteTrackingBase( repo.path, baseBranch, ...localWorktreeGitOptionArgs ) if (remoteTrackingBase) { const hadLocalBaseRef = await this.hasRemoteTrackingRef( repo.path, remoteTrackingBase, ...localWorktreeGitOptionArgs ) const refreshResult = await this.getOrStartRemoteTrackingBaseRefresh( repo.path, remoteTrackingBase, ...localWorktreeGitOptionArgs ) if (!refreshResult.ok) { throw new Error( `Could not refresh base ref "${baseBranch}" from "${remoteTrackingBase.remote}". Check your network and try again.` ) } if ( !hadLocalBaseRef && !(await this.hasRemoteTrackingRef( repo.path, remoteTrackingBase, ...localWorktreeGitOptionArgs )) ) { throw new Error(`Base ref "${baseBranch}" was not found after fetching.`) } } else if (!(await hasLocalCommitObject(repo.path, baseBranch))) { // Why: local bases keep legacy best-effort fetch behavior. Verified PR // SHA bases already have the commit object needed by `git worktree add`. try { await this.fetchRemoteWithCache(repo.path, 'origin', ...localWorktreeGitOptionArgs) } catch { // Why: belt-and-suspenders. fetchRemoteWithCache already logs and does // not throw; the outer try/catch guarantees create-path tolerance even // if future refactors change that contract. } } const sparseDirectories = args.sparseCheckout ? normalizeSparseDirectories(args.sparseCheckout.directories) : [] if (args.sparseCheckout && sparseDirectories.length === 0) { throw new Error('Sparse checkout requires at least one repo-relative directory.') } let preparedPushTarget: GitPushTarget | undefined if (args.pushTarget) { // Why: fork-PR worktrees created through a remote runtime need the same // upstream target setup as local desktop creates, or Push would publish // to the wrong remote after the client/server split. preparedPushTarget = await prepareWorktreePushTarget( repo.path, args.pushTarget, this.store, repo.id, localWorktreeGitOptions ) } const suggestLocalBaseRefUpdate = !settings.refreshLocalBaseRefOnWorktreeCreate && !settings.localBaseRefSuggestionDismissed && Boolean(remoteTrackingBase) const remoteTrackingBaseOption = remoteTrackingBase ? { remoteTrackingBase } : undefined const existingBranchOption = { checkoutExistingBranch, ...remoteTrackingBaseOption, ...(suggestLocalBaseRefUpdate ? { suggestLocalBaseRefUpdate } : {}) } const defaultAddWorktreeOption = addProjectGitOptions() const addResult: AddWorktreeResult = (await (sparseDirectories.length > 0 ? checkoutExistingBranch ? addSparseWorktree( repo.path, worktreePath, branchName, sparseDirectories, baseBranch, settings.refreshLocalBaseRefOnWorktreeCreate, addProjectGitOptions(existingBranchOption) ) : suggestLocalBaseRefUpdate ? addSparseWorktree( repo.path, worktreePath, branchName, sparseDirectories, baseBranch, settings.refreshLocalBaseRefOnWorktreeCreate, addProjectGitOptions({ ...remoteTrackingBaseOption, suggestLocalBaseRefUpdate }) ) : remoteTrackingBaseOption ? addSparseWorktree( repo.path, worktreePath, branchName, sparseDirectories, baseBranch, settings.refreshLocalBaseRefOnWorktreeCreate, addProjectGitOptions(remoteTrackingBaseOption) ) : defaultAddWorktreeOption ? addSparseWorktree( repo.path, worktreePath, branchName, sparseDirectories, baseBranch, settings.refreshLocalBaseRefOnWorktreeCreate, defaultAddWorktreeOption ) : addSparseWorktree( repo.path, worktreePath, branchName, sparseDirectories, baseBranch, settings.refreshLocalBaseRefOnWorktreeCreate ) : checkoutExistingBranch ? addWorktree( repo.path, worktreePath, branchName, baseBranch, settings.refreshLocalBaseRefOnWorktreeCreate, false, addProjectGitOptions(existingBranchOption) ) : suggestLocalBaseRefUpdate ? addWorktree( repo.path, worktreePath, branchName, baseBranch, settings.refreshLocalBaseRefOnWorktreeCreate, false, addProjectGitOptions({ ...remoteTrackingBaseOption, suggestLocalBaseRefUpdate }) ) : remoteTrackingBaseOption ? addWorktree( repo.path, worktreePath, branchName, baseBranch, settings.refreshLocalBaseRefOnWorktreeCreate, false, addProjectGitOptions(remoteTrackingBaseOption) ) : defaultAddWorktreeOption ? addWorktree( repo.path, worktreePath, branchName, baseBranch, settings.refreshLocalBaseRefOnWorktreeCreate, false, defaultAddWorktreeOption ) : addWorktree( repo.path, worktreePath, branchName, baseBranch, settings.refreshLocalBaseRefOnWorktreeCreate ))) ?? {} let configuredPushTarget: GitPushTarget | undefined if (preparedPushTarget) { configuredPushTarget = await configureCreatedWorktreePushTarget( worktreePath, branchName, preparedPushTarget, localWorktreeGitOptions ) } const gitWorktrees = hasLocalWorktreeGitOptions ? await listWorktrees(repo.path, localWorktreeGitOptions) : await listWorktrees(repo.path) const created = gitWorktrees.find((gw) => areWorktreePathsEqual(gw.path, worktreePath)) if (!created) { throw new Error('Worktree created but not found in listing') } const worktreeId = `${repo.id}::${created.path}` const now = Date.now() // Why: PR/MR-created worktrees can start from a head ref/SHA while Source // Control must compare against the review target branch. const metadataBaseRef = args.compareBaseRef ?? remoteTrackingBase?.ref ?? baseBranch const displayNameMeta = requestedDisplayName ? { displayName: requestedDisplayName } : shouldSetDisplayName(effectiveRequestedName, branchName, effectiveSanitizedName) ? { displayName: effectiveRequestedName } : {} const meta = this.store.setWorktreeMeta(worktreeId, { // Why: worktree IDs are path-derived. If a path is deleted outside Orca // and later recreated, creation must mint a fresh instance identity so // stale lineage records tied to the old occupant fail validation. instanceId: randomUUID(), ...getProjectHostSetupWorktreeMeta(this.store.getProjectHostSetups?.() ?? [], repo), lastActivityAt: now, // See createRemoteWorktree: createdAt grants the new worktree a grace // window in Recent sort so ambient PTY bumps in OTHER worktrees can't // push it down before the user has had a chance to notice it. Smart-sort // uses max(lastActivityAt, createdAt + CREATE_GRACE_MS). createdAt: now, orcaCreatedAt: now, orcaCreationSource: 'runtime', orcaCreationWorkspaceLayout: getWorktreeCreationLayout(repo, settings), ...displayNameMeta, baseRef: metadataBaseRef, ...(checkoutExistingBranch ? { preserveBranchOnDelete: true } : {}), ...(configuredPushTarget ? { pushTarget: configuredPushTarget } : {}), ...(sparseDirectories.length > 0 ? { sparseDirectories, sparseBaseRef: metadataBaseRef, sparsePresetId: args.sparseCheckout?.presetId } : {}), ...(args.linkedIssue !== undefined ? { linkedIssue: args.linkedIssue } : {}), ...(args.linkedPR !== undefined ? { linkedPR: args.linkedPR } : {}), ...(args.linkedLinearIssue !== undefined ? { linkedLinearIssue: args.linkedLinearIssue } : {}), ...(args.linkedLinearIssueWorkspaceId !== undefined ? { linkedLinearIssueWorkspaceId: args.linkedLinearIssueWorkspaceId } : {}), ...(args.linkedLinearIssueOrganizationUrlKey !== undefined ? { linkedLinearIssueOrganizationUrlKey: args.linkedLinearIssueOrganizationUrlKey } : {}), ...(args.linkedGitLabIssue !== undefined ? { linkedGitLabIssue: args.linkedGitLabIssue } : {}), ...(args.linkedGitLabMR !== undefined ? { linkedGitLabMR: args.linkedGitLabMR } : {}), ...(args.linkedBitbucketPR !== undefined ? { linkedBitbucketPR: args.linkedBitbucketPR } : {}), ...(args.linkedAzureDevOpsPR !== undefined ? { linkedAzureDevOpsPR: args.linkedAzureDevOpsPR } : {}), ...(args.linkedGiteaPR !== undefined ? { linkedGiteaPR: args.linkedGiteaPR } : {}), ...(effectiveCreatedWithAgent ? { createdWithAgent: effectiveCreatedWithAgent } : {}), ...(args.pendingFirstAgentMessageRename === true && effectiveCreatedWithAgent ? { pendingFirstAgentMessageRename: true } : {}), ...(args.automationProvenance ? { automationProvenance: args.automationProvenance } : {}), ...(args.comment !== undefined ? { comment: args.comment } : {}), ...(args.manualOrder !== undefined ? { manualOrder: args.manualOrder } : {}), ...(args.workspaceStatus !== undefined ? { workspaceStatus: args.workspaceStatus } : {}) }) const worktree = mergeWorktree(repo.id, created, meta) const { lineage, workspaceLineage, warnings: lineageWarnings } = this.recordCreatedWorktreeLineage(worktree, lineageResolution) if ( settings.experimentalWorktreeSymlinks && repo.symlinkPaths && repo.symlinkPaths.length > 0 ) { await createWorktreeLinkedPaths(repo.path, created.path, repo.symlinkPaths) } let setup: CreateWorktreeResult['setup'] let warning: string | undefined // Why: CLI-created worktrees do not have a renderer preview to mismatch // against. Trust is granted by the direct CLI invocation (`--run-hooks`), // so loading the setup hook from the created worktree is intentional here. const yamlHooks = loadHooks(worktreePath) const hooks = getEffectiveHooks(repo, worktreePath) // Why: setupDecision lets mobile/CLI callers control whether the setup // script runs. 'skip' suppresses it, 'run' forces it, 'inherit' (default) // defers to the repo's orca.yaml setupRunPolicy. runHooks === true maps // to 'run' for backwards compatibility with the desktop create flow. const effectiveDecision = args.runHooks ? 'run' : (args.setupDecision ?? 'inherit') let defaultTabs: CreateWorktreeResult['defaultTabs'] try { defaultTabs = getDefaultTabsLaunch(yamlHooks, repo, effectiveDecision) } catch (error) { console.warn(`[hooks] default tab commands skipped for ${worktreePath}:`, error) defaultTabs = yamlHooks?.defaultTabs ? { tabs: yamlHooks.defaultTabs, runCommands: false } : undefined } const shouldRunSetup = hooks?.scripts.setup && shouldRunSetupForCreate(repo, effectiveDecision) if (shouldRunSetup && hooks?.scripts.setup) { const shouldUseSetupRunner = this.authoritativeWindowId !== null || Boolean(effectiveStartup) if (shouldUseSetupRunner) { try { // Why: setup+startup must share the terminal runner path even without // a renderer window, so the startup shell can wait on setup completion. setup = createSetupRunnerScript( repo, worktreePath, hooks.scripts.setup, this.getLocalGitExecutionOptionArgs(repo)[0] ) } catch (error) { // Why: the git worktree is already real at this point. If runner // generation fails, keep creation successful and surface the problem in // logs rather than pretending the worktree was never created. console.error(`[hooks] Failed to prepare setup runner for ${worktreePath}:`, error) } } else { void runHook( 'setup', worktreePath, repo, worktreePath, this.getLocalGitExecutionOptionArgs(repo)[0] ).then((result) => { if (!result.success) { console.error(`[hooks] setup hook failed for ${worktreePath}:`, result.output) } }) } } else if (hooks?.scripts.setup && effectiveDecision !== 'skip') { // Runtime RPC calls have no renderer trust prompt, so hooks require explicit CLI opt-in. warning = `orca.yaml setup hook skipped for ${worktreePath}; pass --setup run to run it.` console.warn(`[hooks] ${warning}`) } this.invalidateResolvedWorktreeCache() // Why: the filesystem-auth layer maintains a separate cache of registered // worktree roots used by git IPC handlers (branchCompare, diff, status, etc.) // to authorize paths. Without invalidating it here, CLI-created worktrees // are not recognized and all git operations fail with "Access denied: // unknown repository or worktree path". invalidateAuthorizedRootsCache() this.notifyWorktreesChanged(repo.id) const shouldActivate = args.activate === true || args.runHooks === true let didSpawnStartup = false // Why: tracks whether runtime itself launched the setup script (via // provisionManagedWorktreeTerminals). When true, renderer activation and the // RPC return value must omit setup so the client does not spawn it a second // time. Mirrors the wait-for-agent setup contract from #6298. let didSpawnSetup = false let startupTerminalHandle: string | null = null let startupTerminalTabId: string | null = null let startupTerminalPaneKey: string | null = null let startupTerminalPtyId: string | null = null let sequencedStartup = effectiveStartup let wrappedSetupCommandStr: string | undefined if (effectiveStartup && setup?.waitForAgentStartup === true) { const platform = getSetupRunnerCommandPlatformForPath( setup.runnerScriptPath, process.platform === 'win32' ? 'windows' : 'posix' ) const sequenced = createSequencedSetupAgentCommands({ runnerScriptPath: setup.runnerScriptPath, startupCommand: effectiveStartup.command, platform }) sequencedStartup = { ...effectiveStartup, command: sequenced.startupCommand, ...(sequenced.startupEnv ? { env: { ...effectiveStartup.env, ...sequenced.startupEnv } } : {}) } wrappedSetupCommandStr = sequenced.setupCommand } if (sequencedStartup && this.ptyController?.spawn) { try { // Why: automation startup must not depend on a renderer TerminalPane // mounting. Runtime-spawned PTYs run immediately and the UI adopts the // session later, matching `orca terminal create` background semantics. const startupTrustAgent = effectiveDraftPaste?.agent ?? effectiveCreatedWithAgent if (startupTrustAgent) { this.markLocalWorkspaceTrustedForAgent(startupTrustAgent, worktreePath) } const terminal = await this.createTerminal(`id:${worktree.id}`, { command: sequencedStartup.command, ...(setup && effectiveStartup ? { claudeAgentTeamsSourceCommand: effectiveStartup.command } : {}), env: sequencedStartup.env, ...(sequencedStartup.launchConfig ? { launchConfig: sequencedStartup.launchConfig } : {}), ...(effectiveCreatedWithAgent ? { launchAgent: effectiveCreatedWithAgent } : {}), startupCommandDelivery: sequencedStartup.startupCommandDelivery, telemetry: sequencedStartup.telemetry }) if (effectiveDraftPaste) { this.pasteStartupDraftWhenReady(terminal.handle, effectiveDraftPaste) } if (effectiveStartupFollowup) { this.sendStartupFollowupWhenReady(terminal.handle, effectiveStartupFollowup) } didSpawnStartup = true startupTerminalHandle = terminal.handle startupTerminalTabId = terminal.tabId ?? null startupTerminalPaneKey = terminal.paneKey ?? null startupTerminalPtyId = terminal.ptyId ?? null } catch (err) { const message = err instanceof Error ? err.message : String(err) warning = warning ? `${warning} Also failed to create the startup terminal for ${worktreePath}: ${message}` : `Failed to create the startup terminal for ${worktreePath}: ${message}` console.warn(`[worktree-create] ${warning}`) } } if (shouldActivate) { // Why: plain CLI creates should not steal the user's current workspace. // Explicit activation and hook-running still use renderer activation so // the user can watch prompts/output in a visible pane. const runtimeWillProvisionTerminals = didSpawnStartup && Boolean(setup || defaultTabs) if (runtimeWillProvisionTerminals) { // Why: once runtime spawned the startup PTY, renderer activation may see // an existing terminal and skip setup/default tabs. Await provisioning so // a failed setup spawn falls back to renderer activation (which still // carries the wrapped command for retry); #6298's wait-for-setup // guarantee is enforced by the shell marker, not by spawn timing. const provisioned = await this.provisionManagedWorktreeTerminals({ worktreeSelector: `id:${worktree.id}`, worktreeId: worktree.id, worktreePath, ...(setup ? { setup } : {}), ...(defaultTabs ? { defaultTabs } : {}), primaryTerminalHandle: startupTerminalHandle, hasStartupTerminal: didSpawnStartup, setupCommandPlatform: setup ? isWindowsAbsolutePathLike(setup.runnerScriptPath) ? 'windows' : 'posix' : 'posix', // Why: carry the wait-for-agent wrapped setup command (#6298) so the // Setup tab runs the same script the sequenced agent waits on. ...(wrappedSetupCommandStr ? { wrappedSetupCommand: wrappedSetupCommandStr } : {}) }) didSpawnSetup = provisioned.setupSpawned } // Why: when runtime spawned setup, omit it from activation. When setup // spawn failed, fall through with the wrapped command so renderer // activation retries it. const activationSetup = didSpawnSetup ? undefined : setup ? { ...setup, ...(didSpawnStartup && wrappedSetupCommandStr ? { command: wrappedSetupCommandStr } : {}) } : undefined const activationDefaultTabs = runtimeWillProvisionTerminals ? undefined : defaultTabs if (effectiveStartup && !didSpawnStartup) { this.notifyActivateWorktree( repo.id, worktree.id, activationSetup, effectiveStartup, activationDefaultTabs ) } else { this.notifyActivateWorktree( repo.id, worktree.id, activationSetup, undefined, activationDefaultTabs ) } } else if (this.ptyController?.spawn && (setup || defaultTabs || didSpawnStartup)) { // Why: inactive terminal materialization matches normal worktree creation, // but setup/default tab failures must not gate automation dispatch. void this.provisionManagedWorktreeTerminals({ worktreeSelector: `id:${worktree.id}`, worktreeId: worktree.id, worktreePath, ...(setup ? { setup } : {}), ...(defaultTabs ? { defaultTabs } : {}), primaryTerminalHandle: startupTerminalHandle, hasStartupTerminal: didSpawnStartup, setupCommandPlatform: setup ? isWindowsAbsolutePathLike(setup.runnerScriptPath) ? 'windows' : 'posix' : 'posix', ...(wrappedSetupCommandStr ? { wrappedSetupCommand: wrappedSetupCommandStr } : {}) }) // Why: runtime owns setup spawning here, so the RPC result must omit setup // to keep the headless/mobile caller from launching it a second time. if (setup) { didSpawnSetup = true } } else if (this.ptyController?.spawn) { try { await this.createTerminal(`id:${worktree.id}`) } catch (err) { const message = err instanceof Error ? err.message : String(err) warning = warning ? `${warning} Also failed to create the initial terminal for ${worktreePath}: ${message}` : `Failed to create the initial terminal for ${worktreePath}: ${message}` console.warn(`[worktree-create] ${warning}`) } } const returnedSetup = didSpawnSetup ? undefined : setup ? { ...setup, ...(didSpawnStartup && wrappedSetupCommandStr ? { command: wrappedSetupCommandStr } : {}) } : undefined return { worktree: { ...worktree, parentWorktreeId: lineage?.parentWorktreeId ?? null, childWorktreeIds: [], lineage, workspaceLineage, git: created }, ...(lineageInput ? { lineage, workspaceLineage, warnings: lineageWarnings } : {}), ...(returnedSetup ? { setup: returnedSetup } : {}), ...(defaultTabs ? { defaultTabs } : {}), ...(warning ? { warning } : {}), ...(addResult.localBaseRefRefresh ? { localBaseRefRefresh: addResult.localBaseRefRefresh } : {}), ...(addResult.localBaseRefUpdateSuggestion ? { localBaseRefUpdateSuggestion: addResult.localBaseRefUpdateSuggestion } : {}), ...(didSpawnStartup && startupTerminalHandle ? { startupTerminal: { spawned: true, handle: startupTerminalHandle, ...(startupTerminalTabId ? { tabId: startupTerminalTabId } : {}), ...(startupTerminalPaneKey ? { paneKey: startupTerminalPaneKey } : {}), ...(startupTerminalPtyId ? { ptyId: startupTerminalPtyId } : {}), surface: 'background' as const } } : {}) } } private async createManagedRemoteWorktree( repo: Repo, args: { name: string baseBranch?: string compareBaseRef?: string branchNameOverride?: string linkedIssue?: number | null linkedPR?: number | null linkedLinearIssue?: string linkedLinearIssueWorkspaceId?: string | null linkedLinearIssueOrganizationUrlKey?: string | null linkedGitLabMR?: number | null linkedGitLabIssue?: number | null linkedBitbucketPR?: number | null linkedAzureDevOpsPR?: number | null linkedGiteaPR?: number | null comment?: string displayName?: string workspaceStatus?: string manualOrder?: number sparseCheckout?: { directories: string[]; presetId?: string } pushTarget?: GitPushTarget runHooks?: boolean activate?: boolean setupDecision?: 'run' | 'skip' | 'inherit' createdWithAgent?: TuiAgent pendingFirstAgentMessageRename?: boolean automationProvenance?: AutomationWorkspaceProvenance startup?: WorktreeStartupLaunch startupFollowup?: WorktreeStartupFollowup startupDraftPaste?: WorktreeStartupDraftPaste } ): Promise { if (!this.store) { throw new Error('runtime_unavailable') } // Why: runtime/mobile callers do not own a renderer BrowserWindow, but the // SSH create helper only uses it for progress and change notifications. // Runtime emits those through RuntimeNotifier after the create succeeds. const headlessWindow = { isDestroyed: () => false, webContents: { send: () => undefined } } as unknown as BrowserWindow const result = await createRemoteWorktree( { repoId: repo.id, name: args.name, ...(args.displayName ? { displayName: args.displayName } : {}), ...(args.baseBranch ? { baseBranch: args.baseBranch } : {}), ...(args.compareBaseRef ? { compareBaseRef: args.compareBaseRef } : {}), ...(args.branchNameOverride ? { branchNameOverride: args.branchNameOverride } : {}), ...(args.runHooks ? { setupDecision: 'run' as const } : {}), ...(!args.runHooks && args.setupDecision ? { setupDecision: args.setupDecision } : {}), ...(args.sparseCheckout ? { sparseCheckout: args.sparseCheckout } : {}), ...(args.linkedIssue != null ? { linkedIssue: args.linkedIssue } : {}), ...(args.linkedPR != null ? { linkedPR: args.linkedPR } : {}), ...(args.linkedLinearIssue ? { linkedLinearIssue: args.linkedLinearIssue } : {}), ...(args.linkedLinearIssueWorkspaceId !== undefined ? { linkedLinearIssueWorkspaceId: args.linkedLinearIssueWorkspaceId } : {}), ...(args.linkedLinearIssueOrganizationUrlKey !== undefined ? { linkedLinearIssueOrganizationUrlKey: args.linkedLinearIssueOrganizationUrlKey } : {}), ...(args.linkedGitLabMR != null ? { linkedGitLabMR: args.linkedGitLabMR } : {}), ...(args.linkedGitLabIssue != null ? { linkedGitLabIssue: args.linkedGitLabIssue } : {}), ...(args.linkedBitbucketPR != null ? { linkedBitbucketPR: args.linkedBitbucketPR } : {}), ...(args.linkedAzureDevOpsPR != null ? { linkedAzureDevOpsPR: args.linkedAzureDevOpsPR } : {}), ...(args.linkedGiteaPR != null ? { linkedGiteaPR: args.linkedGiteaPR } : {}), ...(args.pushTarget ? { pushTarget: args.pushTarget } : {}), ...(args.workspaceStatus ? { workspaceStatus: args.workspaceStatus as never } : {}), ...(args.manualOrder !== undefined ? { manualOrder: args.manualOrder } : {}), ...(args.createdWithAgent ? { createdWithAgent: args.createdWithAgent } : {}), ...(args.pendingFirstAgentMessageRename === true ? { pendingFirstAgentMessageRename: true } : {}), ...(args.automationProvenance ? { automationProvenance: args.automationProvenance } : {}) }, repo, this.store as unknown as Store, headlessWindow ) if (args.comment !== undefined) { this.store.setWorktreeMeta(result.worktree.id, { comment: args.comment }) result.worktree.comment = args.comment } this.invalidateResolvedWorktreeCache() this.notifyWorktreesChanged(repo.id) let warning = result.warning let didSpawnStartup = false // Why: same no-double-spawn contract as the local path — once runtime // provisions setup, omit it from activation and the RPC result. let didSpawnSetup = false let startupTerminalHandle: string | null = null let startupTerminalTabId: string | null = null let startupTerminalPaneKey: string | null = null let startupTerminalPtyId: string | null = null let sequencedStartup = args.startup let wrappedSetupCommandStr: string | undefined if (args.startup && result.setup?.waitForAgentStartup === true) { const platform = getSetupRunnerCommandPlatformForPath(result.setup.runnerScriptPath, 'posix') const sequenced = createSequencedSetupAgentCommands({ runnerScriptPath: result.setup.runnerScriptPath, startupCommand: args.startup.command, platform }) sequencedStartup = { ...args.startup, command: sequenced.startupCommand, ...(sequenced.startupEnv ? { env: { ...args.startup.env, ...sequenced.startupEnv } } : {}) } wrappedSetupCommandStr = sequenced.setupCommand } if (sequencedStartup && this.ptyController?.spawn) { try { const startupTrustAgent = args.startupDraftPaste?.agent ?? args.createdWithAgent if (startupTrustAgent) { await this.markRemoteWorkspaceTrustedForAgent( startupTrustAgent, repo.connectionId!, result.worktree.path ) } const terminal = await this.createTerminal(`path:${result.worktree.path}`, { command: sequencedStartup.command, ...(result.setup && args.startup ? { claudeAgentTeamsSourceCommand: args.startup.command } : {}), env: sequencedStartup.env, ...(sequencedStartup.launchConfig ? { launchConfig: sequencedStartup.launchConfig } : {}), ...(args.createdWithAgent ? { launchAgent: args.createdWithAgent } : {}), startupCommandDelivery: sequencedStartup.startupCommandDelivery, telemetry: sequencedStartup.telemetry }) if (args.startupDraftPaste) { this.pasteStartupDraftWhenReady(terminal.handle, args.startupDraftPaste) } if (args.startupFollowup) { this.sendStartupFollowupWhenReady(terminal.handle, args.startupFollowup) } didSpawnStartup = true startupTerminalHandle = terminal.handle startupTerminalTabId = terminal.tabId ?? null startupTerminalPaneKey = terminal.paneKey ?? null startupTerminalPtyId = terminal.ptyId ?? null } catch (err) { const message = err instanceof Error ? err.message : String(err) warning = warning ? `${warning} Also failed to create the startup terminal for ${result.worktree.path}: ${message}` : `Failed to create the startup terminal for ${result.worktree.path}: ${message}` } } const shouldActivate = args.activate === true || args.runHooks === true if (shouldActivate) { const runtimeWillProvisionTerminals = didSpawnStartup && Boolean(result.setup || result.defaultTabs) if (runtimeWillProvisionTerminals) { // Why: remote/mobile task creates spawn the agent terminal in runtime, // so renderer activation may not materialize setup/default tabs. Await so // a failed setup spawn falls back to renderer activation for retry. const provisioned = await this.provisionManagedWorktreeTerminals({ worktreeSelector: `path:${result.worktree.path}`, worktreeId: result.worktree.id, worktreePath: result.worktree.path, ...(result.setup ? { setup: result.setup } : {}), ...(result.defaultTabs ? { defaultTabs: result.defaultTabs } : {}), primaryTerminalHandle: startupTerminalHandle, hasStartupTerminal: didSpawnStartup, setupCommandPlatform: result.setup ? isWindowsAbsolutePathLike(result.setup.runnerScriptPath) ? 'windows' : 'posix' : 'posix', // Why: carry the wait-for-agent wrapped setup command (#6298) so the // remote Setup tab runs the same script the sequenced agent waits on. ...(wrappedSetupCommandStr ? { wrappedSetupCommand: wrappedSetupCommandStr } : {}) }) didSpawnSetup = provisioned.setupSpawned } // Why: omit setup from activation when runtime spawned it; on spawn // failure fall through with the wrapped command so renderer retries. const activationSetup = didSpawnSetup ? undefined : result.setup ? { ...result.setup, ...(didSpawnStartup && wrappedSetupCommandStr ? { command: wrappedSetupCommandStr } : {}) } : undefined const activationDefaultTabs = runtimeWillProvisionTerminals ? undefined : result.defaultTabs if (args.startup && !didSpawnStartup) { this.notifyActivateWorktree( repo.id, result.worktree.id, activationSetup, args.startup, activationDefaultTabs ) } else { this.notifyActivateWorktree( repo.id, result.worktree.id, activationSetup, undefined, activationDefaultTabs ) } } if ( !shouldActivate && this.ptyController?.spawn && (result.setup || result.defaultTabs || didSpawnStartup) ) { // Why: inactive terminal materialization matches normal worktree creation, // but setup/default tab failures must not gate automation dispatch. void this.provisionManagedWorktreeTerminals({ worktreeSelector: `path:${result.worktree.path}`, worktreeId: result.worktree.id, worktreePath: result.worktree.path, ...(result.setup ? { setup: result.setup } : {}), ...(result.defaultTabs ? { defaultTabs: result.defaultTabs } : {}), primaryTerminalHandle: startupTerminalHandle, hasStartupTerminal: didSpawnStartup, setupCommandPlatform: result.setup ? isWindowsAbsolutePathLike(result.setup.runnerScriptPath) ? 'windows' : 'posix' : 'posix', ...(wrappedSetupCommandStr ? { wrappedSetupCommand: wrappedSetupCommandStr } : {}) }) // Why: runtime owns setup spawning here, so omit setup from the RPC result // to keep the headless/mobile caller from launching it a second time. if (result.setup) { didSpawnSetup = true } } else if (!shouldActivate && this.ptyController?.spawn) { try { await this.createTerminal(`path:${result.worktree.path}`) } catch (err) { const message = err instanceof Error ? err.message : String(err) warning = warning ? `${warning} Also failed to create the initial terminal for ${result.worktree.path}: ${message}` : `Failed to create the initial terminal for ${result.worktree.path}: ${message}` } } const returnedSetup = didSpawnSetup ? undefined : result.setup ? { ...result.setup, ...(didSpawnStartup && wrappedSetupCommandStr ? { command: wrappedSetupCommandStr } : {}) } : undefined const resultForRenderer = returnedSetup ? { ...result, setup: returnedSetup } : (() => { const { setup: _setup, ...resultWithoutSetup } = result return resultWithoutSetup })() const resultWithStartupTerminal = didSpawnStartup && startupTerminalHandle ? { ...resultForRenderer, startupTerminal: { spawned: true, handle: startupTerminalHandle, ...(startupTerminalTabId ? { tabId: startupTerminalTabId } : {}), ...(startupTerminalPaneKey ? { paneKey: startupTerminalPaneKey } : {}), ...(startupTerminalPtyId ? { ptyId: startupTerminalPtyId } : {}), surface: 'background' as const } } : resultForRenderer return warning ? { ...resultWithStartupTerminal, warning } : resultWithStartupTerminal } /** * Fetch `remote` in `repoPath`, sharing the 30s freshness window + in-flight * serialization with all other callers. Never rejects — callers * log-and-proceed on offline failures (§3.3 Lifecycle). * * Why a shared cache on the runtime instead of module-scoped: §7.1 relies on * one cache for BOTH the renderer create path and `probeWorktreeDrift`. A * dispatch tick that reuses a just-completed create-path fetch is the * primary telemetry target; splitting the cache by call-site would double * the fetch load on warm repos. */ async getCanonicalFetchKey( repoPath: string, remote: string, gitOptions: { wslDistro?: string } = {} ): Promise { const runtimeKey = gitOptions.wslDistro ? `wsl:${gitOptions.wslDistro}` : 'local' const cacheKey = `${runtimeKey}::${repoPath}::${remote}` const cached = this.canonicalFetchKeyCache.get(cacheKey) if (cached !== undefined) { setBoundedMapEntry(this.canonicalFetchKeyCache, cacheKey, cached, REMOTE_FETCH_CACHE_MAX) return cached } let resolved = cacheKey try { const { stdout } = await gitExecFileAsync( ['rev-parse', '--path-format=absolute', '--git-common-dir'], { cwd: repoPath, ...gitOptions } ) const commonDir = stdout.trim() if (commonDir) { resolved = `${runtimeKey}::${commonDir}::${remote}` } } catch { // Fall through to the caller-provided path. The fetch still runs from // repoPath; this key only controls cache sharing. } setBoundedMapEntry(this.canonicalFetchKeyCache, cacheKey, resolved, REMOTE_FETCH_CACHE_MAX) return resolved } private enqueueRemoteFetch( remoteKey: string, runFetch: () => Promise ): Promise { const previous = this.remoteFetchQueueTail.get(remoteKey) const promise = previous ? previous.then(runFetch, runFetch) : runFetch() this.remoteFetchQueueTail.set(remoteKey, promise) promise.finally(() => { if (this.remoteFetchQueueTail.get(remoteKey) === promise) { this.remoteFetchQueueTail.delete(remoteKey) } }) return promise } private getFreshFetchCompletedAt(key: string): number | null { const lastAt = this.fetchLastCompletedAt.get(key) if (lastAt === undefined) { return null } if (Date.now() - lastAt < FETCH_FRESHNESS_MS) { setBoundedMapEntry(this.fetchLastCompletedAt, key, lastAt, REMOTE_FETCH_CACHE_MAX) return lastAt } this.fetchLastCompletedAt.delete(key) return null } private rememberFreshFetchCompletedAt(key: string, completedAt = Date.now()): void { setBoundedMapEntry(this.fetchLastCompletedAt, key, completedAt, REMOTE_FETCH_CACHE_MAX) } async getOrStartRemoteFetch( repoPath: string, remote: string, gitOptions: { wslDistro?: string } = {} ): Promise { const key = await this.getCanonicalFetchKey(repoPath, remote, gitOptions) if (this.getFreshFetchCompletedAt(key) !== null) { // Why: freshness window hit — skip the fetch entirely. Do NOT reuse any // in-flight promise here; the timestamp is only written on success, so // hitting this branch means a previous fetch did succeed recently. return { ok: true } } const existing = this.fetchInflight.get(key) if (existing) { // Why: genuine serialization (not check-then-set). Two callers racing // on the same repo+remote share the single underlying `git fetch`. return existing } const promise = this.enqueueRemoteFetch(key, () => gitExecFileAsync(['fetch', remote], { cwd: repoPath, ...gitOptions }) .then((): RemoteFetchResult => { // Why (§3.3 Lifecycle): timestamp on success ONLY. Writing on rejection // would make the freshness cache lie about the last known remote state. this.rememberFreshFetchCompletedAt(key) return { ok: true } }) .catch((err): RemoteFetchResult => { // Why: swallow here so awaiters don't throw at the await site. Outer // create/dispatch paths are already tolerant of offline fetch failure; // this is the behavioral contract of this helper. console.warn(`[fetchRemoteWithCache] ${remote} fetch failed for ${repoPath}:`, err) return { ok: false, errorKind: 'git_error' } }) ).finally(() => { // Why (§3.3 Lifecycle): evict on BOTH success and rejection. A // rejected entry that survived in the Map would wedge every future // create on this repo until Orca restarted (the F2 bug §3.3 pins). this.fetchInflight.delete(key) }) this.fetchInflight.set(key, promise) return promise } async getOrStartRemoteTrackingBaseRefresh( repoPath: string, base: RemoteTrackingBase, gitOptions: { wslDistro?: string } = {} ): Promise { const remoteKey = await this.getCanonicalFetchKey(repoPath, base.remote, gitOptions) const key = await this.getCanonicalFetchKey( repoPath, `base:${base.remote}:${base.branch}`, gitOptions ) if (this.getFreshFetchCompletedAt(key) !== null) { // Why: exact-base freshness is the safety boundary. A full remote fetch // can be narrowed by repo refspecs, so it must not prove this branch. return { ok: true } } const existing = this.fetchInflight.get(key) if (existing) { return existing } const promise = this.enqueueRemoteFetch(remoteKey, async () => { if (this.getFreshFetchCompletedAt(key) !== null) { return { ok: true } } return gitExecFileAsync( ['fetch', '--no-tags', base.remote, `+refs/heads/${base.branch}:${base.ref}`], { cwd: repoPath, ...gitOptions, // Why: exact remote-base refresh is the network gate for worktree // creation, so honor repo SSH routing and bound custom wrappers. useConfiguredSshCommandForNetwork: true, timeout: 60_000 } ) .then((): RemoteFetchResult => { this.rememberFreshFetchCompletedAt(key) return { ok: true } }) .catch((err): RemoteFetchResult => { console.warn( `[refreshRemoteTrackingBase] ${base.base} refresh failed for ${repoPath}:`, err ) return { ok: false, errorKind: 'git_error' } }) }).finally(() => { this.fetchInflight.delete(key) }) this.fetchInflight.set(key, promise) return promise } async fetchRemoteWithCache( repoPath: string, remote: string, gitOptions: { wslDistro?: string } = {} ): Promise { await this.getOrStartRemoteFetch(repoPath, remote, gitOptions) } async resolveRemoteTrackingBase( repoPath: string, baseBranch: string, gitOptions: { wslDistro?: string } = {} ): Promise { let remotes: string[] try { const { stdout } = await gitExecFileAsync(['remote'], { cwd: repoPath, ...gitOptions }) remotes = stdout .split('\n') .map((line) => line.trim()) .filter(Boolean) } catch { return null } const remoteRefPrefix = 'refs/remotes/' const shortBaseBranch = baseBranch.startsWith(remoteRefPrefix) ? baseBranch.slice(remoteRefPrefix.length) : baseBranch const remote = remotes .filter((candidate) => shortBaseBranch.startsWith(`${candidate}/`)) .sort((a, b) => b.length - a.length)[0] if (!remote) { return null } const branch = shortBaseBranch.slice(remote.length + 1) if (!branch) { return null } return { remote, branch, ref: `refs/remotes/${remote}/${branch}`, base: `${remote}/${branch}` } } async hasRemoteTrackingRef( repoPath: string, base: RemoteTrackingBase, gitOptions: { wslDistro?: string } = {} ): Promise { try { await gitExecFileAsync(['rev-parse', '--verify', `${base.ref}^{commit}`], { cwd: repoPath, ...gitOptions }) return true } catch { return false } } recordOptimisticReconcileToken(worktreeId: string): string { const token = randomUUID() this.optimisticReconcileTokens.set(worktreeId, token) return token } clearOptimisticReconcileToken(worktreeId: string): void { this.optimisticReconcileTokens.delete(worktreeId) } emitWorktreeBaseStatus(event: WorktreeBaseStatusEvent): void { this.notifier?.worktreeBaseStatus?.(event) } async reconcileWorktreeBaseStatus(args: { repoId: string repoPath: string worktreeId: string base: RemoteTrackingBase branchName: string createdBaseSha: string token: string fetchPromise: Promise }): Promise { const stillCurrent = (): boolean => this.optimisticReconcileTokens.get(args.worktreeId) === args.token const emit = (event: Omit): void => { if (!stillCurrent()) { return } this.notifier?.worktreeBaseStatus?.({ repoId: args.repoId, worktreeId: args.worktreeId, base: args.base.base, remote: args.base.remote, ...event }) } const resolvePublishRemote = async (): Promise => { // Why: repos whose canonical publish remote is named differently (e.g. // `upstream`, a forked `myfork`, or any non-`origin` configuration — // including multi-segment names like `foo/bar` that this PR's resolver // explicitly supports) would otherwise silently skip the conflict // signal. Resolve from git config in priority order: // 1) branch..pushRemote (explicit per-branch override) // 2) remote.pushDefault (workspace-wide override) // 3) branch..remote (tracked remote) // 4) the base ref's own remote (matches resolveRemoteTrackingBase) // 5) `origin` as a final fallback. const tryConfig = async (key: string): Promise => { try { const { stdout } = await gitExecFileAsync(['config', '--get', key], { cwd: args.repoPath }) const value = stdout.trim() return value || null } catch { return null } } return ( (await tryConfig(`branch.${args.branchName}.pushRemote`)) ?? (await tryConfig('remote.pushDefault')) ?? (await tryConfig(`branch.${args.branchName}.remote`)) ?? args.base.remote ?? 'origin' ) } const checkPublishRemoteConflict = async (): Promise => { const publishRemote = await resolvePublishRemote() try { if (publishRemote !== args.base.remote) { const result = await this.getOrStartRemoteFetch(args.repoPath, publishRemote) if (!result.ok) { return } } await gitExecFileAsync( ['rev-parse', '--verify', `refs/remotes/${publishRemote}/${args.branchName}^{commit}`], { cwd: args.repoPath } ) if (stillCurrent()) { this.notifier?.worktreeRemoteBranchConflict?.({ repoId: args.repoId, worktreeId: args.worktreeId, remote: publishRemote, branchName: args.branchName }) } } catch { // No publish-remote conflict is the common case; stay quiet. } } try { const fetchResult = await args.fetchPromise if (!stillCurrent()) { return } if (!fetchResult.ok) { emit({ status: 'unknown' }) return } const { stdout } = await gitExecFileAsync( ['rev-parse', '--verify', `${args.base.ref}^{commit}`], { cwd: args.repoPath } ) const postFetchSha = stdout.trim() if (postFetchSha === args.createdBaseSha) { emit({ status: 'current' }) await checkPublishRemoteConflict() return } try { await gitExecFileAsync(['merge-base', '--is-ancestor', args.createdBaseSha, postFetchSha], { cwd: args.repoPath }) } catch { emit({ status: 'base_changed' }) await checkPublishRemoteConflict() return } const { stdout: countStdout } = await gitExecFileAsync( ['rev-list', '--count', `${args.createdBaseSha}..${postFetchSha}`], { cwd: args.repoPath } ) const behind = Number(countStdout.trim()) if (!Number.isFinite(behind) || behind <= 0) { emit({ status: 'current' }) await checkPublishRemoteConflict() return } const { stdout: logStdout } = await gitExecFileAsync( ['log', '--format=%s', '-n', '5', `${args.createdBaseSha}..${postFetchSha}`], { cwd: args.repoPath } ) emit({ status: 'drift', behind, recentSubjects: logStdout.split('\n').filter((line) => line.trim().length > 0) }) await checkPublishRemoteConflict() } catch (err) { console.warn(`[worktree-base-status] reconcile failed for ${args.worktreeId}:`, err) emit({ status: 'unknown' }) } finally { // Why: reconcile is one-shot; clear the token so long-lived sessions // that create many worktrees without removing them don't grow the // optimisticReconcileTokens map monotonically. Removal still no-ops // because the entry is already gone. if (this.optimisticReconcileTokens.get(args.worktreeId) === args.token) { this.optimisticReconcileTokens.delete(args.worktreeId) } } } /** * Probe how far the worktree's HEAD is behind its tracking remote. Returns * null when the probe cannot establish a signal (no default base ref, or * git failure). Dispatch treats null as "unknown — proceed" (§3.1); only * knowing-and-stale refuses. */ async probeWorktreeDrift(worktreeSelector: string): Promise<{ base: string behind: number recentSubjects: string[] } | null> { const wt = await this.resolveWorktreeSelector(worktreeSelector) if (!this.store) { return null } const repo = this.store.getRepos().find((r) => r.id === wt.repoId) if (!repo) { return null } if (repo.connectionId) { // Why: the drift probe uses local git helpers. Until the SSH provider // exposes equivalent remote refs/log plumbing, fail closed to "unknown" // instead of probing a server path on the desktop filesystem. return null } const localGitExecOptions = getLocalProjectGitExecOptions(this.requireStore(), repo) const localWorktreeGitOptions = getLocalProjectWorktreeGitOptions(this.requireStore(), repo) const meta = this.store.getWorktreeMeta(wt.id) const base = meta?.baseRef || meta?.sparseBaseRef || repo.worktreeBaseRef || (await getBaseRefDefault(repo.path, localWorktreeGitOptions)) if (!base) { // Why: brand-new repo with no remote primary — nothing to compare // against, so there's no meaningful drift to report. Dispatch should // not block on a probe that cannot form an opinion. return null } const remoteTrackingBase = await this.resolveRemoteTrackingBase( repo.path, base, localWorktreeGitOptions ) if (!remoteTrackingBase) { return null } const remote = remoteTrackingBase.remote // Why: fetch failures are non-fatal; we proceed with whatever the // last-known remote ref points at. `fetchRemoteWithCache` never throws. await this.fetchRemoteWithCache(repo.path, remote, localWorktreeGitOptions) const drift = getRemoteDrift(wt.path, 'HEAD', base, localGitExecOptions) if (!drift) { return null } const recentSubjects = getRecentDriftSubjects( wt.path, 'HEAD', base, DRIFT_PROBE_SUBJECT_LIMIT, localGitExecOptions ) return { base, behind: drift.behind, recentSubjects } } async updateManagedWorktreeMeta( worktreeSelector: string, updates: Omit, 'pushTarget'> & { pushTarget?: GitPushTarget | null lineage?: { parentWorktree?: string noParent?: boolean } } ) { if (!this.store) { throw new Error('runtime_unavailable') } const worktree = await this.resolveWorktreeSelector(worktreeSelector) const { lineage, ...metaUpdates } = updates const shouldClearPushTarget = Object.prototype.hasOwnProperty.call(metaUpdates, 'pushTarget') && metaUpdates.pushTarget === null const normalizedMetaUpdates: Partial = shouldClearPushTarget ? { ...metaUpdates, pushTarget: undefined } : (metaUpdates as Partial) const persistedMetaUpdates: Partial = omitUndefinedProperties( normalizedMetaUpdates.displayName !== undefined ? { ...normalizedMetaUpdates, pendingFirstAgentMessageRename: false, firstAgentMessageRenameError: null } : normalizedMetaUpdates ) if (shouldClearPushTarget) { // Why: omitUndefinedProperties protects ordinary optional RPC fields, but // pushTarget:null is an explicit request to remove persisted target metadata. persistedMetaUpdates.pushTarget = undefined } if (lineage?.noParent === true) { this.store.removeWorktreeLineage?.(worktree.id) this.store.removeWorkspaceLineage?.(worktreeWorkspaceKey(worktree.id)) } else if (lineage?.parentWorktree) { const parent = await this.resolveWorktreeSelector(lineage.parentWorktree) this.validateLineageParent(worktree, parent) if (!worktree.instanceId || !parent.instanceId) { throw new RuntimeLineageError( 'LINEAGE_PARENT_CONTEXT_MISSING', 'Worktree instance identity was unavailable.' ) } if (!this.store.setWorktreeLineage) { throw new RuntimeLineageError( 'LINEAGE_PARENT_CONTEXT_MISSING', 'Worktree lineage storage was unavailable.' ) } const createdAt = Date.now() this.store.setWorktreeLineage(worktree.id, { worktreeId: worktree.id, worktreeInstanceId: worktree.instanceId, parentWorktreeId: parent.id, parentWorktreeInstanceId: parent.instanceId, origin: 'manual', capture: { source: 'manual-action', confidence: 'explicit' }, createdAt }) this.store.setWorkspaceLineage?.({ childWorkspaceKey: worktreeWorkspaceKey(worktree.id), childInstanceId: worktree.instanceId, parentWorkspaceKey: worktreeWorkspaceKey(parent.id), parentInstanceId: parent.instanceId, origin: 'manual', capture: { source: 'manual-action', confidence: 'explicit' }, createdAt }) } this.store.setWorktreeMeta(worktree.id, stripOrcaProvenanceMetaUpdates(persistedMetaUpdates)) // Why: unlike renderer-initiated optimistic updates, CLI callers need an // explicit push so the editor refreshes metadata changed outside the UI. this.invalidateResolvedWorktreeCache() this.notifyWorktreesChanged(worktree.repoId) return await this.showManagedWorktree(`id:${worktree.id}`) } persistManagedWorktreeSortOrder(orderedIds: string[]): { updated: number } { if (!this.store) { throw new Error('runtime_unavailable') } const now = Date.now() let updated = 0 for (let i = 0; i < orderedIds.length; i++) { this.store.setWorktreeMeta(orderedIds[i], { sortOrder: now - i * 1000 }) updated++ } this.invalidateResolvedWorktreeCache() this.notifyReposChanged() return { updated } } async resolveManagedPrBase(args: { repoSelector: string prNumber: number headRefName?: string baseRefName?: string isCrossRepository?: boolean }): Promise { if (!this.store) { throw new Error('runtime_unavailable') } let repo: Repo try { repo = await this.resolveRepoSelector(args.repoSelector) } catch { return { error: 'Repo not found' } } if (isFolderRepo(repo)) { return { error: 'Folder mode does not support creating worktrees.' } } const sshGitProvider = repo.connectionId ? requireSshGitProvider(repo.connectionId) : null const localGitExecOptions = sshGitProvider ? undefined : getLocalProjectGitExecOptions(this.requireStore(), repo) const localWorktreeGitOptions = sshGitProvider ? {} : getLocalProjectWorktreeGitOptions(this.requireStore(), repo) const gitExec = sshGitProvider ? (gitArgs: string[]) => sshGitProvider.exec(gitArgs, repo.path) : (gitArgs: string[]) => gitExecFileAsync(gitArgs, localGitExecOptions ?? { cwd: repo.path }) const resolveRemote = sshGitProvider ? async () => { const { stdout } = await sshGitProvider.exec(['remote'], repo.path) const remotes = stdout .split('\n') .map((line) => line.trim()) .filter(Boolean) if (remotes.includes('origin')) { return 'origin' } if (remotes.length === 1) { return remotes[0]! } if (remotes.length === 0) { throw new Error('Repo has no configured git remotes.') } throw new Error( `Repo has multiple remotes (${remotes.join(', ')}) and no default is configured.` ) } : () => getDefaultRemote(repo.path, localWorktreeGitOptions) // Why: SSH repos can't fetch over the relay's read-only git.exec channel, so // route the PR head fetch through the write-capable helper instead of gitExec. const fetchRemoteTrackingRef = (remote: string, branch: string): Promise => fetchPrHeadTrackingRef( repo, sshGitProvider, remote, branch, localGitExecOptions ? { localGitExecOptions } : {} ) return resolveGitHubPrStartPoint({ repoPath: repo.path, prNumber: args.prNumber, headRefName: args.headRefName, baseRefName: args.baseRefName, isCrossRepository: args.isCrossRepository, connectionId: repo.connectionId ?? null, localGitOptions: localWorktreeGitOptions, gitExec, fetchRemoteTrackingRef, resolveRemote }) } async resolveManagedMrBase(args: { repoSelector: string mrIid: number sourceBranch?: string targetBranch?: string isCrossRepository?: boolean }): Promise< { baseBranch: string; compareBaseRef?: string; pushTarget?: GitPushTarget } | { error: string } > { if (!this.store) { throw new Error('runtime_unavailable') } let repo: Repo try { repo = await this.resolveRepoSelector(args.repoSelector) } catch { return { error: 'Repo not found' } } if (isFolderRepo(repo)) { return { error: 'Folder mode does not support creating worktrees.' } } const sshGitProvider = repo.connectionId ? requireSshGitProvider(repo.connectionId) : null const localGitExecOptions = sshGitProvider ? undefined : getLocalProjectGitExecOptions(this.requireStore(), repo) const localWorktreeGitOptions = sshGitProvider ? {} : getLocalProjectWorktreeGitOptions(this.requireStore(), repo) const gitExec = sshGitProvider ? (gitArgs: string[]) => sshGitProvider.exec(gitArgs, repo.path) : (gitArgs: string[]) => gitExecFileAsync(gitArgs, localGitExecOptions ?? { cwd: repo.path }) let sourceBranch = args.sourceBranch?.trim() ?? '' let targetBranch = args.targetBranch?.trim() ?? '' let isCrossRepository = args.isCrossRepository === true if (!sourceBranch) { let remote: string try { remote = await this.resolveGitLabIssueSourceRemote( repo.path, repo.issueSourcePreference, repo.connectionId ?? null, localWorktreeGitOptions ) } catch (error) { return { error: error instanceof Error ? error.message : 'Could not resolve git remote.' } } const knownHosts = await getGlabKnownHosts() const projectRef = await getGitLabProjectRefForRemote( repo.path, remote, knownHosts, repo.connectionId ?? null, localWorktreeGitOptions ) if (!projectRef) { return { error: 'No GitLab project found for this repository.' } } const item = await getGitLabWorkItemByProjectRef( repo.path, projectRef, args.mrIid, 'mr', repo.connectionId ?? null, localWorktreeGitOptions ) if (!item || item.type !== 'mr') { return { error: `MR !${args.mrIid} not found.` } } sourceBranch = (item.branchName ?? '').trim() targetBranch = (item.baseRefName ?? '').trim() if (!sourceBranch) { return { error: `MR !${args.mrIid} has no source branch.` } } if (item.isCrossRepository === true) { isCrossRepository = true } } let remote: string try { remote = await this.resolveGitLabIssueSourceRemote( repo.path, repo.issueSourcePreference, repo.connectionId ?? null, localWorktreeGitOptions ) } catch (error) { return { error: error instanceof Error ? error.message : 'Could not resolve git remote.' } } const compareBaseRef = targetBranch ? `refs/remotes/${remote}/${targetBranch}` : undefined const fetchRemoteTrackingRef = async (branch: string, ref: string): Promise => { await (sshGitProvider ? sshGitProvider.fetchRemoteTrackingRef(repo.path, remote, branch, ref) : gitExec(['fetch', remote, `+refs/heads/${branch}:${ref}`])) } // Why: the target/compare branch is optional (it only powers the diff // base). A merged MR may have had its target ref deleted, so a fetch // failure must NOT abort the whole resolution — that would discard the // already-verified source-branch base and silently fall back to the repo // default branch. Degrade gracefully by dropping compareBaseRef instead. const fetchCompareBaseRef = async (): Promise => { if (!targetBranch || !compareBaseRef) { return false } try { await fetchRemoteTrackingRef(targetBranch, compareBaseRef) return true } catch (error) { console.warn('[runtime:resolveManagedMrBase] optional compare-base fetch failed', { remote, targetBranch, mrIid: args.mrIid, error: error instanceof Error ? error.message.split('\n')[0] : String(error) }) return false } } if (isCrossRepository) { const mrRef = `refs/merge-requests/${args.mrIid}/head` // Why: GitLab exposes fork MR heads on the target project, so mobile/SSH // can match desktop without adding the contributor fork as a remote. try { await (sshGitProvider ? sshGitProvider.fetchGitLabMergeRequestHead(repo.path, remote, args.mrIid) : gitExec(['fetch', remote, mrRef])) } catch (error) { const message = error instanceof Error ? error.message : String(error) return { error: `Failed to fetch ${mrRef}: ${message.split('\n')[0]}` } } let sha: string try { const { stdout } = await gitExec(['rev-parse', '--verify', 'FETCH_HEAD']) sha = stdout.trim() } catch { return { error: `Could not resolve fork MR !${args.mrIid} head after fetch.` } } if (!sha) { return { error: `Empty SHA resolving fork MR !${args.mrIid} head.` } } const compareBaseFetched = await fetchCompareBaseRef() return { baseBranch: sha, ...(compareBaseFetched ? { compareBaseRef } : {}) } } try { await fetchRemoteTrackingRef(sourceBranch, `refs/remotes/${remote}/${sourceBranch}`) } catch (error) { const message = error instanceof Error ? error.message : String(error) return { error: `Failed to fetch ${remote}/${sourceBranch}: ${message.split('\n')[0]}` } } const remoteRef = `${remote}/${sourceBranch}` try { await gitExec(['rev-parse', '--verify', remoteRef]) } catch { return { error: `Remote ref ${remoteRef} does not exist after fetch.` } } const compareBaseFetched = await fetchCompareBaseRef() return { baseBranch: remoteRef, ...(compareBaseFetched ? { compareBaseRef } : {}), pushTarget: { remoteName: remote, branchName: sourceBranch } } } private async resolveGitLabIssueSourceRemote( repoPath: string, preference?: Repo['issueSourcePreference'], connectionId?: string | null, localGitOptions: { wslDistro?: string } = {} ): Promise { const knownHosts = await getGlabKnownHosts() const localGitOptionArgs = Object.keys(localGitOptions).length > 0 ? ([localGitOptions] as const) : [] if (preference === 'origin') { const origin = await getGitLabProjectRefForRemote( repoPath, 'origin', knownHosts, connectionId, ...localGitOptionArgs ) if (origin) { return 'origin' } throw new Error('No GitLab project found for origin.') } if (preference === 'upstream') { const upstream = await getGitLabProjectRefForRemote( repoPath, 'upstream', knownHosts, connectionId, ...localGitOptionArgs ) if (upstream) { return 'upstream' } const origin = await getGitLabProjectRefForRemote( repoPath, 'origin', knownHosts, connectionId, ...localGitOptionArgs ) if (origin) { return 'origin' } throw new Error('No GitLab project found for upstream or origin.') } const upstream = await getGitLabProjectRefForRemote( repoPath, 'upstream', knownHosts, connectionId, ...localGitOptionArgs ) if (upstream) { return 'upstream' } const origin = await getGitLabProjectRefForRemote( repoPath, 'origin', knownHosts, connectionId, ...localGitOptionArgs ) if (origin) { return 'origin' } if (connectionId) { const provider = requireSshGitProvider(connectionId) const { stdout } = await provider.exec(['remote'], repoPath) const remotes = stdout .split('\n') .map((line) => line.trim()) .filter(Boolean) if (remotes.includes('origin')) { return 'origin' } if (remotes.length === 1) { return remotes[0]! } if (remotes.length === 0) { throw new Error('Repo has no configured git remotes.') } throw new Error( `Repo has multiple remotes (${remotes.join(', ')}) and no default is configured.` ) } return getDefaultRemote(repoPath, localGitOptions) } private async resolveWorktreeRemovalTarget( worktreeSelector: string ): Promise { try { const worktree = await this.resolveWorktreeSelector(worktreeSelector) const removalTarget = { id: worktree.id, repoId: worktree.repoId, path: worktree.path } return worktree.pushTarget ? { ...removalTarget, pushTarget: worktree.pushTarget } : removalTarget } catch (error) { if (!(error instanceof Error) || error.message !== 'selector_not_found') { throw error } const removalTarget = parseExactWorktreeIdSelector(worktreeSelector) const meta = removalTarget ? this.store?.getWorktreeMeta(removalTarget.id) : undefined if (!removalTarget || !meta) { throw error } // Why: delete requests can arrive after Git no longer lists the worktree. // Only exact IDs with persisted Orca metadata are accepted here so // branch/path selectors cannot resolve to an arbitrary missing path. return meta.pushTarget ? { ...removalTarget, pushTarget: meta.pushTarget } : removalTarget } } private removeWorktreeMetadataAndHistory(store: RuntimeStore, worktreeId: string): void { // Why: worktree IDs are path-derived and can be recreated, so removal must // purge history and process-local caches before the ID points at new state. store.removeWorktreeMeta(worktreeId) advertisedUrlWatcher.forgetWorktree(worktreeId) serveSimStateWatcher.forgetWorktree(worktreeId) deleteWorktreeHistoryDir(worktreeId) this.closeHeadlessBrowserPagesForWorktree(worktreeId) } // Why: headless offscreen browser pages are main-process BrowserWindows that // outlive a worktree unless explicitly closed — removing a worktree without // closing its open panes leaks the windows for the life of the serve process. private closeHeadlessBrowserPagesForWorktree(worktreeId: string): void { if (!this.offscreenBrowserBackend || !this.agentBrowserBridge?.tabList) { return } for (const tab of this.agentBrowserBridge.tabList(worktreeId).tabs) { void this.offscreenBrowserBackend.closeTab(tab.browserPageId).catch(() => {}) } } private rememberPreservedBranchCleanupTarget( worktreeId: string, result: RemoveWorktreeResult | undefined, fallbackHead: string | undefined, pushTarget: GitPushTarget | undefined ): void { if (result?.preservedBranch) { const head = result.preservedBranch.head ?? fallbackHead if (!head) { throw new Error( `Cannot safely offer force-delete for preserved branch "${result.preservedBranch.branchName}" without its saved commit.` ) } this.preservedBranchCleanupByWorktreeId.set(worktreeId, { branchName: result.preservedBranch.branchName, head, ...(pushTarget ? { pushTarget } : {}) }) return } this.preservedBranchCleanupByWorktreeId.delete(worktreeId) } private preserveBranchHeadFallback( result: RemoveWorktreeResult | undefined, fallbackHead: string | undefined ): RemoveWorktreeResult { if (!result?.preservedBranch || result.preservedBranch.head || !fallbackHead) { return result ?? {} } return { ...result, preservedBranch: { ...result.preservedBranch, head: fallbackHead } } } async forceDeletePreservedBranch( worktreeSelector: string, branchName: string, expectedHead: string ): Promise { if (!this.store) { throw new Error('runtime_unavailable') } const removalTarget = parseExactWorktreeIdSelector(worktreeSelector) const cleanupTarget = removalTarget ? this.preservedBranchCleanupByWorktreeId.get(removalTarget.id) : undefined if ( !removalTarget || !cleanupTarget || cleanupTarget.branchName !== branchName || cleanupTarget.head !== expectedHead ) { throw new Error(`No preserved branch cleanup is pending for "${branchName}".`) } const repo = this.store.getRepo(removalTarget.repoId) if (!repo) { throw new Error('repo_not_found') } if (isFolderRepo(repo)) { throw new Error('Folder workspaces do not have local Git branches.') } if (repo.connectionId) { const provider = requireSshGitProvider(repo.connectionId) // Why: SSH must use the write-capable relay RPC; the shared exec-based // helper routes through the read-only git.exec allowlist, which rejects // the worktree/update-ref/config writes this delete needs. await provider.forceDeletePreservedBranch( repo.path, cleanupTarget.branchName, cleanupTarget.head ) await cleanupUnusedWorktreePushTargetRemoteSsh( provider, repo.path, removalTarget.id, cleanupTarget.pushTarget, this.store ) } else { const localWorktreeGitOptions = getLocalProjectWorktreeGitOptions(this.requireStore(), repo) await (Object.keys(localWorktreeGitOptions).length > 0 ? forceDeleteLocalBranch( repo.path, cleanupTarget.branchName, cleanupTarget.head, (argv, cwd) => gitExecFileAsync(argv, { cwd, ...localWorktreeGitOptions }) ) : forceDeleteLocalBranch(repo.path, cleanupTarget.branchName, cleanupTarget.head)) await cleanupUnusedWorktreePushTargetRemote( repo.path, removalTarget.id, cleanupTarget.pushTarget, this.store, localWorktreeGitOptions ) } this.preservedBranchCleanupByWorktreeId.delete(removalTarget.id) return { deleted: true } } async removeManagedWorktree( worktreeSelector: string, force = false, runHooks = false ): Promise { if (!this.store) { throw new Error('runtime_unavailable') } const store = this.store const removalTarget = await this.resolveWorktreeRemovalTarget(worktreeSelector) const optionsKey = getRuntimeWorktreeRemovalOptionsKey(force, runHooks) const inFlightRemoval = this.removeManagedWorktreeInFlight.get(removalTarget.id) if (inFlightRemoval) { if (inFlightRemoval.optionsKey === optionsKey) { return inFlightRemoval.promise } throw new Error(`Worktree deletion already in progress: ${removalTarget.id}`) } // Why: runtime callers can race the same workspace through CLI/mobile // retries. Share one destructive Git/filesystem operation per worktree ID. const removal = (async (): Promise => { const repo = store.getRepo(removalTarget.repoId) if (!repo) { throw new Error('repo_not_found') } if (isFolderRepo(repo)) { if (removalTarget.id === getRuntimeFolderWorkspaceRootId(repo)) { throw new Error( 'Cannot delete the project root workspace. Remove the folder project instead.' ) } const localProvider = this.getLocalProvider() if (localProvider) { // Why: folder workspace deletion has no Git removal phase where PTYs // would otherwise be swept; tear them down before hiding the workspace. await killAllProcessesForWorktree(removalTarget.id, { runtime: this, localProvider, onPtyStopped: this.onPtyStopped ?? undefined }).catch((err) => { console.warn(`[worktree-teardown] failed for ${removalTarget.id}:`, err) }) } this.removeWorktreeMetadataAndHistory(store, removalTarget.id) this.preservedBranchCleanupByWorktreeId.delete(removalTarget.id) this.invalidateResolvedWorktreeCache() this.notifyWorktreesChanged(repo.id) return {} } const provider = repo.connectionId ? requireSshGitProvider(repo.connectionId) : null const fsProvider = repo.connectionId ? getSshFilesystemProvider(repo.connectionId) : null const localWorktreeGitOptions = repo.connectionId ? {} : getLocalProjectWorktreeGitOptions(this.requireStore(), repo) const hasLocalWorktreeGitOptions = Object.keys(localWorktreeGitOptions).length > 0 const registeredWorktrees = repo.connectionId ? await provider!.listWorktrees(repo.path) : hasLocalWorktreeGitOptions ? await listWorktreesStrict(repo.path, localWorktreeGitOptions) : await listWorktreesStrict(repo.path) const removedMeta = store.getWorktreeMeta(removalTarget.id) const removedPushTarget = removedMeta?.pushTarget ?? removalTarget.pushTarget const registeredWorktree = findRegisteredDeletableWorktree( repo.path, removalTarget.path, registeredWorktrees ) if (!registeredWorktree) { let canCleanOrphanedDirectory = false const knownOrcaLayouts = buildKnownOrcaWorkspaceLayouts(store.getSettings(), repo) if ( canCleanupUnregisteredOrcaWorktreeDirectory({ meta: removedMeta, worktreePath: removalTarget.path, repo, knownOrcaLayouts }) ) { if (repo.connectionId) { if (!fsProvider) { throw new Error('SSH filesystem provider unavailable') } if (!fsProvider.lstat) { throw new Error('SSH filesystem provider lstat unavailable') } canCleanOrphanedDirectory = await canSafelyRemoveOrphanedWorktreeDirectory( removalTarget.path, repo.path, (path) => fsProvider.lstat!(path), (path) => fsProvider.readFile(path) ) } else { const access = getLocalWorktreePathAccess(localWorktreeGitOptions) canCleanOrphanedDirectory = !isDangerousWorktreeRemovalPath(removalTarget.path, repo.path) && (await canSafelyRemoveOrphanedWorktreeDirectory( toLocalWorktreeRuntimePath(removalTarget.path, localWorktreeGitOptions), toLocalWorktreeRuntimePath(repo.path, localWorktreeGitOptions), access.statPath, access.readPath )) } } if (canCleanOrphanedDirectory) { assertWorktreeDoesNotContainRegisteredWorktree(removalTarget.path, registeredWorktrees) if (!force) { throw new Error(ORPHANED_WORKTREE_DIRECTORY_MESSAGE) } if (repo.connectionId) { await fsProvider!.deletePath(removalTarget.path, true) await cleanupUnusedWorktreePushTargetRemoteSsh( provider!, repo.path, removalTarget.id, removedPushTarget, store ) } else { await removeLocalWorktreePath(removalTarget.path, localWorktreeGitOptions) await cleanupUnusedWorktreePushTargetRemote( repo.path, removalTarget.id, removedPushTarget, store, localWorktreeGitOptions ) } this.clearOptimisticReconcileToken(removalTarget.id) this.removeWorktreeMetadataAndHistory(store, removalTarget.id) this.preservedBranchCleanupByWorktreeId.delete(removalTarget.id) this.invalidateResolvedWorktreeCache() invalidateAuthorizedRootsCache() this.notifyWorktreesChanged(repo.id) return {} } if (!repo.connectionId) { const access = getLocalWorktreePathAccess(localWorktreeGitOptions) const runtimeWorktreePath = toLocalWorktreeRuntimePath( removalTarget.path, localWorktreeGitOptions ) if ( await canCleanupUnregisteredOrcaLeftoverDirectory({ meta: removedMeta, worktreePath: removalTarget.path, runtimeWorktreePath, repo, runtimeRepoPath: toLocalWorktreeRuntimePath(repo.path, localWorktreeGitOptions), knownOrcaLayouts, registeredWorktrees, statPath: access.statPath, isGitRepository: (path) => isLocalRuntimeGitRepository(path, localWorktreeGitOptions) }) ) { if (!force) { throw new Error(ORPHANED_WORKTREE_DIRECTORY_MESSAGE) } await closeLocalWatcherForWorktreePath(removalTarget.path).catch((err) => { console.warn(`[filesystem-watcher] failed to close ${removalTarget.path}:`, err) }) await removeLocalWorktreePath(removalTarget.path, localWorktreeGitOptions) await cleanupUnusedWorktreePushTargetRemote( repo.path, removalTarget.id, removedPushTarget, store, localWorktreeGitOptions ) this.clearOptimisticReconcileToken(removalTarget.id) this.removeWorktreeMetadataAndHistory(store, removalTarget.id) this.preservedBranchCleanupByWorktreeId.delete(removalTarget.id) this.invalidateResolvedWorktreeCache() invalidateAuthorizedRootsCache() this.notifyWorktreesChanged(repo.id) return {} } } if (await isRuntimeWorktreePathMissing(repo, removalTarget.path, localWorktreeGitOptions)) { if (!force && !removedMeta) { // Why: without persisted metadata, require the renderer recovery // path before deleting Orca-only state for an unregistered path. throw new Error(UNREGISTERED_MISSING_WORKTREE_MESSAGE) } // Why: a manually deleted worktree is already gone from Git and disk. // Finish runtime metadata cleanup without requiring force or touching // any unregistered path that still exists. await (repo.connectionId ? cleanupUnusedWorktreePushTargetRemoteSsh( provider!, repo.path, removalTarget.id, removedPushTarget, store ) : cleanupUnusedWorktreePushTargetRemote( repo.path, removalTarget.id, removedPushTarget, store, localWorktreeGitOptions )) this.clearOptimisticReconcileToken(removalTarget.id) this.removeWorktreeMetadataAndHistory(store, removalTarget.id) this.preservedBranchCleanupByWorktreeId.delete(removalTarget.id) this.invalidateResolvedWorktreeCache() invalidateAuthorizedRootsCache() this.notifyWorktreesChanged(repo.id) return {} } throw new Error(`Refusing to delete unregistered worktree path: ${removalTarget.path}`) } const canonicalWorktreePath = registeredWorktree.path const deleteBranch = removedMeta?.preserveBranchOnDelete !== true // Why: a prior forced Windows recovery can delete the directory but leave // Git's stale registration; retry by pruning instead of removing a missing path. if ( !repo.connectionId && force === true && process.platform === 'win32' && (isWindowsAbsolutePathLike(canonicalWorktreePath) || !!localWorktreeGitOptions.wslDistro) && removedMeta && (await isRuntimeWorktreePathMissing(repo, canonicalWorktreePath, localWorktreeGitOptions)) ) { const removalResult = await pruneStaleLocalWorktreeRegistrationAfterFilesystemRemoval({ canonicalWorktreePath, repoPath: repo.path, localWorktreeGitOptions, registeredWorktree, deleteBranch }) await cleanupUnusedWorktreePushTargetRemote( repo.path, removalTarget.id, removedPushTarget, store, localWorktreeGitOptions ) this.rememberPreservedBranchCleanupTarget( removalTarget.id, removalResult, registeredWorktree.head, removedPushTarget ) this.clearOptimisticReconcileToken(removalTarget.id) this.removeWorktreeMetadataAndHistory(store, removalTarget.id) this.invalidateResolvedWorktreeCache() invalidateAuthorizedRootsCache() this.notifyWorktreesChanged(repo.id) return removalResult ?? {} } if (repo.connectionId) { const rawRemovalResult = await (deleteBranch ? provider!.removeWorktree(canonicalWorktreePath, force) : provider!.removeWorktree(canonicalWorktreePath, force, { deleteBranch })) const removalResult = this.preserveBranchHeadFallback( rawRemovalResult, registeredWorktree.head ) await cleanupUnusedWorktreePushTargetRemoteSsh( provider!, repo.path, removalTarget.id, removedPushTarget, store ) this.rememberPreservedBranchCleanupTarget( removalTarget.id, removalResult, registeredWorktree.head, removedPushTarget ) this.clearOptimisticReconcileToken(removalTarget.id) this.removeWorktreeMetadataAndHistory(store, removalTarget.id) this.invalidateResolvedWorktreeCache() invalidateAuthorizedRootsCache() this.notifyWorktreesChanged(repo.id) return removalResult ?? {} } const hooks = getEffectiveHooks(repo) let warning: string | undefined if (hooks?.scripts.archive && runHooks) { const result = await runHook( 'archive', canonicalWorktreePath, repo, undefined, hasLocalWorktreeGitOptions ? localWorktreeGitOptions : undefined ) if (!result.success) { console.error(`[hooks] archive hook failed for ${canonicalWorktreePath}:`, result.output) } } else if (hooks?.scripts.archive) { // Runtime RPC calls have no renderer trust prompt, so hooks require explicit CLI opt-in. warning = `orca.yaml archive hook skipped for ${canonicalWorktreePath}; pass --run-hooks to run it.` console.warn(`[hooks] ${warning}`) } let shouldTearDownPtys = true if (repo.symlinkPaths && repo.symlinkPaths.length > 0) { await removeWorktreeLinkedPaths(canonicalWorktreePath, repo.symlinkPaths) } try { await (hasLocalWorktreeGitOptions ? assertWorktreeCleanForRemoval(canonicalWorktreePath, force, localWorktreeGitOptions) : assertWorktreeCleanForRemoval(canonicalWorktreePath, force)) } catch (error) { if (!isOrphanCompatiblePreflightError(error)) { throw new Error(formatWorktreeRemovalError(error, canonicalWorktreePath, force)) } // Why: orphan cleanup does not need live shells to be killed first, // and preflight did not prove the worktree is cleanly removable. shouldTearDownPtys = false } const localProvider = this.getLocalProvider() await closeLocalWatcherForWorktreePath(canonicalWorktreePath).catch((err) => { console.warn(`[filesystem-watcher] failed to close ${canonicalWorktreePath}:`, err) }) if (localProvider && shouldTearDownPtys) { // Why: once preflight proves normal deletion is clean, kill PTYs before // git-level removal so Windows handles cannot keep the directory busy. This also // closes the headless-CLI leak for confirmed-removable worktrees. await killAllProcessesForWorktree(removalTarget.id, { runtime: this, localProvider, onPtyStopped: this.onPtyStopped ?? undefined }) .then((r) => { const total = r.runtimeStopped + r.providerStopped + r.registryStopped if (total > 0) { // Why (design §4.4 observability): breadcrumb lets ops // distinguish a renderer-state-induced leak (diff-path purge // non-empty) from a backend-induced one (nothing to kill but // memory still pinned). Emit only when the sweep actually did // work so steady-state logs stay quiet. console.info( `[worktree-teardown] ${removalTarget.id} killed runtime=${r.runtimeStopped} provider=${r.providerStopped} registry=${r.registryStopped}` ) } }) .catch((err) => { console.warn(`[worktree-teardown] failed for ${removalTarget.id}:`, err) }) } let removalResult: RemoveWorktreeResult | undefined try { const removeOptions = { ...(!deleteBranch ? { deleteBranch } : {}), // Why: removal already validated the Git row under the selected // project runtime; keep branch cleanup on that same canonical row. knownRemovedWorktree: registeredWorktree, ...localWorktreeGitOptions } removalResult = this.preserveBranchHeadFallback( await removeWorktree(repo.path, canonicalWorktreePath, force, removeOptions), registeredWorktree.head ) } catch (error) { // Why: Git for Windows can fail long-path directory deletion after // Orca has already validated the target and explicit force delete. const recoveredRemovalResult = await recoverLocalWindowsLongPathWorktreeRemoval({ error, force, canonicalWorktreePath, repoPath: repo.path, localWorktreeGitOptions, registeredWorktree, deleteBranch, closeWatcher: (worktreePath) => closeLocalWatcherForWorktreePath(worktreePath).catch((err) => { console.warn(`[filesystem-watcher] failed to close ${worktreePath}:`, err) }) }) if (recoveredRemovalResult) { removalResult = recoveredRemovalResult } else if (isOrphanedWorktreeError(error)) { const access = getLocalWorktreePathAccess(localWorktreeGitOptions) if ( await canSafelyRemoveOrphanedWorktreeDirectory( toLocalWorktreeRuntimePath(canonicalWorktreePath, localWorktreeGitOptions), toLocalWorktreeRuntimePath(repo.path, localWorktreeGitOptions), access.statPath, access.readPath ) ) { await closeLocalWatcherForWorktreePath(canonicalWorktreePath).catch((err) => { console.warn(`[filesystem-watcher] failed to close ${canonicalWorktreePath}:`, err) }) await removeLocalWorktreePath(canonicalWorktreePath, localWorktreeGitOptions).catch( () => {} ) } else { console.warn( `[worktrees] Refusing recursive cleanup for unproven worktree directory: ${canonicalWorktreePath}` ) } // Why: `git worktree remove` failed, so git's internal worktree tracking // (`.git/worktrees/`) is still intact. Without pruning, `git worktree // list` continues to show the stale entry and the branch it had checked out // remains locked — other worktrees cannot check it out. await gitExecFileAsync(['worktree', 'prune'], { cwd: repo.path, ...localWorktreeGitOptions }).catch(() => {}) await cleanupUnusedWorktreePushTargetRemote( repo.path, removalTarget.id, removedPushTarget, store, localWorktreeGitOptions ) this.clearOptimisticReconcileToken(removalTarget.id) this.removeWorktreeMetadataAndHistory(store, removalTarget.id) this.preservedBranchCleanupByWorktreeId.delete(removalTarget.id) this.invalidateResolvedWorktreeCache() invalidateAuthorizedRootsCache() this.notifyWorktreesChanged(repo.id) return { ...(warning ? { warning } : {}) } } else { throw new Error(formatWorktreeRemovalError(error, canonicalWorktreePath, force)) } } await cleanupUnusedWorktreePushTargetRemote( repo.path, removalTarget.id, removedPushTarget, store, localWorktreeGitOptions ) this.rememberPreservedBranchCleanupTarget( removalTarget.id, removalResult, registeredWorktree.head, removedPushTarget ) this.clearOptimisticReconcileToken(removalTarget.id) this.removeWorktreeMetadataAndHistory(store, removalTarget.id) this.invalidateResolvedWorktreeCache() invalidateAuthorizedRootsCache() this.notifyWorktreesChanged(repo.id) return { ...removalResult, ...(warning ? { warning } : {}) } })() this.removeManagedWorktreeInFlight.set(removalTarget.id, { optionsKey, promise: removal }) try { return await removal } finally { if (this.removeManagedWorktreeInFlight.get(removalTarget.id)?.promise === removal) { this.removeManagedWorktreeInFlight.delete(removalTarget.id) } } } async renameTerminal(handle: string, title: string | null): Promise { const pty = this.getLivePtyForHandle(handle) if (pty) { pty.pty.title = title // Why: a manual rename must outrank later agent OSC title updates (which // win by timestamp), so stamp it as the freshest title. pty.pty.titleUpdatedAt = Date.now() this.touchMobileSessionSnapshotsForPty(pty.pty.ptyId) // Why: without a renderer the rename only lived on the live pty and was // lost on restart. Persist customTitle so a headless rebuild keeps it. if (!this.notifier?.renameTerminal && pty.pty.tabId) { this.persistHeadlessTerminalTitle(pty.pty.worktreeId, pty.pty.tabId, title) } for (const leaf of this.leaves.values()) { if (leaf.ptyId === pty.pty.ptyId) { this.notifier?.renameTerminal(leaf.tabId, title) return { handle, tabId: leaf.tabId, title } } } return { handle, tabId: pty.pty.tabId ?? pty.record.tabId, title } } this.assertGraphReady() const { leaf } = this.getLiveLeafForHandle(handle) this.notifier?.renameTerminal(leaf.tabId, title) return { handle, tabId: leaf.tabId, title } } async createTerminal( worktreeSelector?: string, opts: { command?: string claudeAgentTeamsSourceCommand?: string env?: Record launchConfig?: WorktreeStartupLaunch['launchConfig'] launchToken?: string launchAgent?: TuiAgent startupCommandDelivery?: WorktreeStartupLaunch['startupCommandDelivery'] telemetry?: WorktreeStartupLaunch['telemetry'] title?: string focus?: boolean rendererBacked?: boolean activate?: boolean presentation?: RuntimeTerminalPresentation tabId?: string leafId?: string sessionId?: string persistHostSessionBinding?: boolean // Why: the headless mobile-session create publishes its own authoritative // snapshot (with the correct target group) right after spawn. Skip the // intermediate pty-backed publish so the new tab doesn't briefly flash in // the wrong (active) group before the corrected snapshot lands. deferMobileSessionPublish?: boolean } = {} ): Promise { const presentation = resolveTerminalPresentation(opts) const requiresRendererFocus = opts.presentation === 'focused' || opts.focus === true // Why: pre-diff createTerminal fell back to the renderer's active worktree // when no selector was provided. The new background-spawn branch hard- // requires a resolvable selector, so route the no-selector case through // the renderer IPC path to preserve that behavior. const rendererWindow = opts.rendererBacked === true ? this.getAvailableAuthoritativeWindow() : null const shouldCreateInBackground = worktreeSelector !== undefined && ((!requiresRendererFocus && opts.rendererBacked !== true) || // Why: `orca serve` exposes the local runtime without a renderer // window. Renderer-backed Codex terminals are preferred for the app, // but headless CLI users still need a usable terminal handle. (opts.rendererBacked === true && rendererWindow === null)) if (shouldCreateInBackground) { if (!this.ptyController?.spawn) { throw new Error('runtime_unavailable') } const workspace = await this.resolveTerminalWorkspaceLaunchScope(worktreeSelector) const preAllocatedHandle = this.createPreAllocatedTerminalHandle() // Why: mint tabId in main before spawn so paneKey is known at PTY env // build time. Hook-based agent status (Claude/Codex/Cursor/Gemini) keys // off `${tabId}:${leafId}` — without these vars set on the PTY, the // hook payload arrives with an empty paneKey and the renderer cannot // attribute the event. Use a stable UUID leaf because hooks reject the // legacy numeric pane keys after the pane-id migration. const hintedTabId = opts.tabId?.trim() const canAdoptPaneIdentity = hintedTabId !== undefined && isValidHostTerminalTabId(hintedTabId) && opts.leafId !== undefined && isTerminalLeafId(opts.leafId) const tabId = canAdoptPaneIdentity ? (hintedTabId as string) : randomUUID() const leafId = canAdoptPaneIdentity ? (opts.leafId as string) : randomUUID() const paneKey = makePaneKey(tabId, leafId) const launchToken = opts.launchConfig ? (opts.launchToken ?? randomUUID()) : undefined const baseEnv = { ...opts.env, ...(launchToken ? { ORCA_AGENT_LAUNCH_TOKEN: launchToken } : {}) } const claudeAgentTeamsSourceCommand = opts.claudeAgentTeamsSourceCommand?.trim() || opts.command?.trim() || undefined const claudeAgentTeamsMode = this.store?.getSettings?.().claudeAgentTeamsMode const effectiveClaudeAgentTeamsMode = inferCapturedClaudeAgentTeamsMode( opts.launchConfig, claudeAgentTeamsSourceCommand, claudeAgentTeamsMode ) const agentTeamsPlan = await buildClaudeAgentTeamsLaunchPlan({ command: claudeAgentTeamsSourceCommand, mode: effectiveClaudeAgentTeamsMode, baseEnv: { ...process.env, ...baseEnv }, createTeamEnv: (shimDir, shimBin) => this.claudeAgentTeams.createLaunchEnv({ leaderHandle: preAllocatedHandle, baseEnv: { ...process.env, ...baseEnv }, shimDir, shimBin }).env }) const sequencedStartupCommand = agentTeamsPlan && claudeAgentTeamsSourceCommand && opts.command && claudeAgentTeamsSourceCommand !== opts.command ? agentTeamsPlan.command : undefined const effectiveLaunchConfig = opts.launchConfig && agentTeamsPlan ? { ...opts.launchConfig, agentCommand: opts.launchConfig.agentCommand ? effectiveClaudeAgentTeamsMode === 'in-process' || process.platform === 'win32' ? addClaudeTeammateModeInProcess(opts.launchConfig.agentCommand) : addClaudeTeammateModeAuto(opts.launchConfig.agentCommand) : agentTeamsPlan.command, agentEnv: { ...opts.launchConfig.agentEnv, ...agentTeamsPlan.env } } : opts.launchConfig // Why: setup/agent sequencing wraps the PTY launch in a wait shell before // Claude Agent Teams runs. Preserve the direct Claude command separately // so the wrapper can exec the teammate-mode variant after setup completes. const env = this.buildTerminalWorkspaceEnv( workspace, { ...baseEnv, ...(sequencedStartupCommand ? { [SETUP_AGENT_SEQUENCE_STARTUP_COMMAND_ENV]: sequencedStartupCommand } : {}) }, paneKey, tabId, agentTeamsPlan?.env ) const result = await this.ptyController.spawn({ cols: 120, rows: 40, cwd: workspace.path, command: sequencedStartupCommand ? opts.command : (agentTeamsPlan?.command ?? opts.command), commandDelivery: 'provider', startupCommandDelivery: opts.startupCommandDelivery, env, envToDelete: agentTeamsPlan?.envToDelete, telemetry: opts.telemetry, connectionId: workspace.connectionId, worktreeId: workspace.id, preAllocatedHandle, tabId, leafId, ...(opts.sessionId ? { sessionId: opts.sessionId } : {}), ...(opts.persistHostSessionBinding ? { persistHostSessionBinding: true } : {}) }) this.registerPreAllocatedHandleForPty(result.id, preAllocatedHandle) this.registerPty(result.id, workspace.id, workspace.connectionId) const pty = this.getOrCreatePtyWorktreeRecord(result.id) if (pty) { if (opts.title) { const observedAt = this.nextTitleObservationSequence() pty.title = opts.title pty.titleUpdatedAt = observedAt this.setPtyManagementTitleFromObservedTitle(pty, opts.title, observedAt) } else { pty.title = null pty.titleUpdatedAt = null } pty.tabId = tabId pty.paneKey = paneKey pty.launchConfig = effectiveLaunchConfig ? copySleepingAgentLaunchConfig(effectiveLaunchConfig) : null pty.launchToken = launchToken ?? null pty.launchAgent = opts.launchAgent ?? null } const handle = pty ? this.issuePtyHandle(pty) : preAllocatedHandle if (pty && opts.deferMobileSessionPublish !== true) { this.publishPtyBackedMobileSessionTerminal(workspace.id, pty, { tabId, leafId, title: opts.title ?? null, activate: presentation === 'focused', // Why: explicit background presentation may carry legacy activate // metadata from an already-owned renderer pane; don't select it on mobile. selectIfNoActiveTab: presentation !== 'background' }) } let surface: RuntimeTerminalCreate['surface'] = 'background' let warning: string | undefined if (presentation !== 'background' && this.notifier?.revealTerminalSession) { try { // Why: after the PTY is spawned, renderer tab adoption is best-effort; // failing here must not strand a live process without returning a handle. // Pass the pre-minted tabId so the renderer adopts under the same id // already baked into the PTY env — keeps paneKey hook attribution intact. await this.notifier.revealTerminalSession(workspace.id, { ptyId: result.id, title: opts.title ?? null, ...(effectiveLaunchConfig ? { launchConfig: effectiveLaunchConfig } : {}), ...(launchToken ? { launchToken } : {}), ...(opts.launchAgent ? { launchAgent: opts.launchAgent } : {}), activate: presentation === 'focused', ...(presentation ? { presentation } : {}), tabId, leafId }) surface = 'visible' } catch (err) { console.warn(`[terminal-create] failed to create inactive tab for ${result.id}:`, err) warning = createTerminalRevealWarning(handle, err) } } else if (presentation !== 'background') { warning = createTerminalRevealWarning(handle) } return { handle, tabId, paneKey, ptyId: result.id, worktreeId: workspace.id, title: opts.title ?? null, surface, ...(warning ? { warning } : {}) } } this.assertGraphReady() const win = rendererWindow ?? this.getAuthoritativeWindow() // Why: mirrors browserTabCreate — when no worktree is specified, pass // undefined so the renderer uses its current active worktree. const worktreeId = worktreeSelector ? (await this.resolveTerminalWorkspaceLaunchScope(worktreeSelector)).id : undefined const requestId = randomUUID() // Why: terminal creation is a renderer-side Zustand store operation (like // browser tab creation). The main process sends a request, the renderer // creates the tab and replies with the tabId so we can resolve the handle. const reply = await new Promise<{ tabId: string; title: string }>((resolve, reject) => { const timer = setTimeout(() => { ipcMain.removeListener('terminal:tabCreateReply', handler) reject(new Error('Terminal creation timed out')) }, 10_000) const handler = ( event: Electron.IpcMainEvent, r: { requestId: string; tabId?: string; title?: string; error?: string } ): void => { if (event.sender !== win.webContents || r.requestId !== requestId) { return } clearTimeout(timer) ipcMain.removeListener('terminal:tabCreateReply', handler) if (r.error) { reject(new Error(r.error)) } else { resolve({ tabId: r.tabId!, title: r.title ?? opts.title ?? '' }) } } ipcMain.on('terminal:tabCreateReply', handler) win.webContents.send('terminal:requestTabCreate', { requestId, worktreeId, command: opts.command, ...(opts.env ? { env: opts.env } : {}), ...(opts.launchConfig ? { launchConfig: opts.launchConfig } : {}), ...(opts.launchToken ? { launchToken: opts.launchToken } : {}), ...(opts.launchAgent ? { launchAgent: opts.launchAgent } : {}), startupCommandDelivery: opts.startupCommandDelivery, title: opts.title, activate: presentation === 'focused', ...(presentation ? { presentation } : {}) }) }) // Why: the renderer created the tab immediately, but the graph sync that // populates this.leaves may not have arrived yet. Wait for the leaf to // appear so we can return a valid handle the caller can use right away. const handle = await this.waitForTerminalHandle(reply.tabId) return { handle, tabId: reply.tabId, worktreeId: worktreeId ?? '', title: reply.title, surface: 'visible' } } async launchAgentTerminal( worktreeSelector: string, opts: { agent: TuiAgent; prompt: string; title?: string } ): Promise { const worktree = await this.resolveWorktreeSelector(worktreeSelector) const repo = this.store?.getRepo(worktree.repoId) if (!repo) { throw new Error('Repository for the selected workspace is no longer available.') } const startup = this.buildStartupForAgent(repo, opts.agent, opts.prompt) if (repo.connectionId) { await this.markRemoteWorkspaceTrustedForAgent(opts.agent, repo.connectionId, worktree.path) } else { this.markLocalWorkspaceTrustedForAgent(opts.agent, worktree.path) } return await this.createTerminal(`id:${worktree.id}`, { command: startup.startup.command, env: startup.startup.env, ...(startup.startup.launchConfig ? { launchConfig: startup.startup.launchConfig } : {}), launchAgent: startup.agent, startupCommandDelivery: startup.startup.startupCommandDelivery, telemetry: startup.startup.telemetry, title: opts.title }) } async createMobileSessionTerminal( worktreeSelector: string, opts: { afterTabId?: string targetGroupId?: string command?: string env?: Record startupCommandDelivery?: WorktreeStartupLaunch['startupCommandDelivery'] agent?: TuiAgent launchConfig?: SleepingAgentLaunchConfig launchAgent?: TuiAgent activate?: boolean clientMutationId?: string } = {} ): Promise { const mutationId = opts.clientMutationId if (!mutationId) { return this.runCreateMobileSessionTerminal(worktreeSelector, opts) } const mutationKey = `${worktreeSelector}\0${mutationId}` // Why: a retried create (double-tap, reconnect replay) with the same // idempotency key must return the in-flight operation instead of spawning a // duplicate terminal. Settled entries are dropped so a later retry — after a // failure or after the result is consumed — can start a fresh create. const inflight = this.mobileTerminalCreateByMutationId.get(mutationKey) if (inflight) { return inflight } const run = this.runCreateMobileSessionTerminal(worktreeSelector, opts) this.mobileTerminalCreateByMutationId.set(mutationKey, run) void run .catch(() => {}) .finally(() => { if (this.mobileTerminalCreateByMutationId.get(mutationKey) === run) { this.mobileTerminalCreateByMutationId.delete(mutationKey) } }) return run } private async runCreateMobileSessionTerminal( worktreeSelector: string, opts: { afterTabId?: string targetGroupId?: string command?: string env?: Record startupCommandDelivery?: WorktreeStartupLaunch['startupCommandDelivery'] agent?: TuiAgent launchConfig?: SleepingAgentLaunchConfig launchAgent?: TuiAgent activate?: boolean clientMutationId?: string } = {} ): Promise { this.assertGraphReady() const workspace = await this.resolveTerminalWorkspaceLaunchScope(worktreeSelector) const worktreeId = workspace.id this.hydrateHeadlessMobileSessionTabsFromWorkspaceSession(worktreeId) let afterDesktopTabId: string | undefined if (opts.afterTabId) { const snapshot = this.mobileSessionTabsByWorktree.get(worktreeId) const anchor = snapshot?.tabs.find((tab) => tab.id === opts.afterTabId) if (!anchor) { throw new Error('after_tab_not_found') } afterDesktopTabId = anchor.type === 'terminal' ? anchor.parentTabId : anchor.id } const startupCommand = await this.resolveMobileSessionTerminalCommand(workspace, opts) const win = this.getAvailableAuthoritativeWindow() if (!win) { return await this.createHeadlessMobileSessionTerminal( worktreeId, opts.activate !== false, opts.afterTabId, startupCommand.command, startupCommand.env, startupCommand.startupCommandDelivery, undefined, startupCommand.launchAgent, opts.targetGroupId, startupCommand.launchConfig ) } const requestId = randomUUID() const reply = await new Promise<{ tabId: string; title: string }>((resolve, reject) => { const timer = setTimeout(() => { ipcMain.removeListener('terminal:tabCreateReply', handler) reject(new Error('Terminal creation timed out')) }, 10_000) const handler = ( event: Electron.IpcMainEvent, r: { requestId: string; tabId?: string; title?: string; error?: string } ): void => { if (event.sender !== win.webContents || r.requestId !== requestId) { return } clearTimeout(timer) ipcMain.removeListener('terminal:tabCreateReply', handler) if (r.error) { reject(new Error(r.error)) } else { resolve({ tabId: r.tabId!, title: r.title ?? '' }) } } ipcMain.on('terminal:tabCreateReply', handler) win.webContents.send('terminal:requestTabCreate', { requestId, worktreeId, afterTabId: afterDesktopTabId, targetGroupId: opts.targetGroupId, command: startupCommand.command, ...(startupCommand.env ? { env: startupCommand.env } : {}), ...(startupCommand.launchConfig ? { launchConfig: startupCommand.launchConfig } : {}), ...(startupCommand.launchAgent ? { launchAgent: startupCommand.launchAgent } : {}), startupCommandDelivery: startupCommand.startupCommandDelivery, source: 'runtime-session', activate: opts.activate }) }) if (opts.activate !== false) { this.notifier?.focusTerminal(reply.tabId, worktreeId, null) } try { const surface = await this.waitForMobileTerminalSurface(worktreeId, reply.tabId, { timeoutMs: MOBILE_TERMINAL_SURFACE_TIMEOUT_MS }) if (this.isReadyMobileTerminalSurface(surface)) { return surface } const readySurface = await this.waitForMobileTerminalSurface(worktreeId, reply.tabId, { timeoutMs: MOBILE_TERMINAL_READY_FALLBACK_MS, requireReady: true }).catch(() => null) if (readySurface) { return readySurface } const pendingSurface = this.findMobileTerminalSurface(worktreeId, reply.tabId) if (!pendingSurface) { throw new Error('Timed out waiting for terminal surface after creation') } // Why: hidden/occluded renderer windows can publish the tab shell before // TerminalPane mounts and spawns the PTY. Materialize into the same // identity so later renderer focus adopts instead of creating another tab. return await this.createHeadlessMobileSessionTerminal( worktreeId, opts.activate !== false, opts.afterTabId, startupCommand.command, startupCommand.env, startupCommand.startupCommandDelivery, { tabId: pendingSurface.tab.parentTabId, leafId: pendingSurface.tab.leafId }, startupCommand.launchAgent, opts.targetGroupId, startupCommand.launchConfig ) } catch (error) { // Why: the renderer created the tab but its terminal surface never // published (PTY spawn/handle failure). Roll the half-created tab back via // the renderer close path so it can't linger as a ghost in mobile // snapshots, then surface the failure to the caller. this.notifier?.closeTerminal(reply.tabId) throw error } } private async resolveMobileSessionTerminalCommand( workspace: TerminalWorkspaceLaunchScope, opts: { command?: string env?: Record startupCommandDelivery?: WorktreeStartupLaunch['startupCommandDelivery'] agent?: TuiAgent launchConfig?: SleepingAgentLaunchConfig launchAgent?: TuiAgent } ): Promise<{ command?: string env?: Record startupCommandDelivery?: WorktreeStartupLaunch['startupCommandDelivery'] launchConfig?: SleepingAgentLaunchConfig launchAgent?: TuiAgent }> { if (opts.command || !opts.agent) { return { command: opts.command, env: opts.env, launchConfig: opts.launchConfig, launchAgent: opts.launchAgent, startupCommandDelivery: opts.startupCommandDelivery } } if (!this.store) { throw new Error('runtime_unavailable') } const settings = this.store.getSettings() if (!isTuiAgentEnabled(opts.agent, settings.disabledTuiAgents)) { throw new Error('Selected agent is disabled. Choose an enabled agent before creating.') } // Why: mobile may be running on iOS while the actual terminal shell is // Windows/macOS/Linux or an SSH Linux host; quote for the host shell. const platform = this.getAgentLaunchPlatformForWorkspace(workspace) // Why: an SSH workspace runs the CLI through the relay shim (plain `orca`), // so the Linux-only `orca-ide` rename must not be applied. const isRemote = workspace.repo ? repoIsRemote(workspace.repo) : repoIsRemote(workspace) const startupPlan = buildAgentStartupPlan({ agent: opts.agent, prompt: '', cmdOverrides: settings.agentCmdOverrides ?? {}, agentArgs: resolveTuiAgentLaunchArgs(opts.agent, settings.agentDefaultArgs), agentEnv: resolveTuiAgentLaunchEnv(opts.agent, settings.agentDefaultEnv), platform, isRemote, allowEmptyPromptLaunch: true }) if (!startupPlan) { throw new Error(`Could not build launch command for ${opts.agent}.`) } if (workspace.connectionId) { await this.markRemoteWorkspaceTrustedForAgent( opts.agent, workspace.connectionId, workspace.path ) } else { this.markLocalWorkspaceTrustedForAgent(opts.agent, workspace.path) } return { command: startupPlan.launchCommand, env: startupPlan.env, launchConfig: startupPlan.launchConfig, launchAgent: opts.agent, startupCommandDelivery: startupPlan.startupCommandDelivery } } private async createHeadlessMobileSessionTerminal( worktreeId: string, activate: boolean, afterTabId?: string, command?: string, env?: Record, startupCommandDelivery?: WorktreeStartupLaunch['startupCommandDelivery'], identity?: { tabId: string; leafId: string; sessionId?: string }, launchAgent?: TuiAgent, targetGroupId?: string, launchConfig?: SleepingAgentLaunchConfig ): Promise { const workspace = await this.resolveTerminalWorkspaceLaunchScope(`id:${worktreeId}`) // Why: SshPtyProvider treats sessionId as a relay reattach request. Only // synthesize local serve ids; SSH fresh terminals must call pty.spawn. const stableSessionId = identity?.sessionId ?? (workspace.connectionId ? undefined : `serve-${randomUUID()}`) const terminal = await this.createTerminal(`id:${worktreeId}`, { focus: false, command, env, ...(launchConfig ? { launchConfig } : {}), ...(launchAgent ? { launchAgent } : {}), startupCommandDelivery, ...(identity ? { tabId: identity.tabId, leafId: identity.leafId, ...(stableSessionId ? { sessionId: stableSessionId } : {}) } : stableSessionId ? { sessionId: stableSessionId } : {}), persistHostSessionBinding: true, // Why: this method publishes the authoritative snapshot (with the target // group) below; skip the intermediate publish to avoid a wrong-group flash. deferMobileSessionPublish: true }) const livePty = this.getLivePtyForHandle(terminal.handle) if (!livePty) { throw new Error('terminal_handle_stale') } const parentTabId = livePty.pty.tabId ?? `pty:${livePty.pty.ptyId}` const leafId = parsePaneKey(livePty.pty.paneKey ?? '')?.leafId ?? randomUUID() const existing = this.mobileSessionTabsByWorktree.get(worktreeId) const existingSurface = existing?.tabs.find( (candidate): candidate is RuntimeMobileSessionTerminalTab => candidate.type === 'terminal' && candidate.parentTabId === parentTabId && candidate.leafId === leafId ) ?? null const parentLayout = this.buildMaterializedHeadlessParentLayout( leafId, livePty.pty.ptyId, existingSurface?.parentLayout ) const tab: RuntimeMobileSessionTerminalTab = { type: 'terminal', id: `${parentTabId}::${leafId}`, parentTabId, leafId, ptyId: livePty.pty.ptyId, title: terminal.title ?? livePty.pty.title ?? 'Terminal', ...(launchAgent ? { launchAgent } : {}), parentLayout, isActive: activate } const tabs = (existing?.tabs ?? []) .filter((candidate) => candidate.id !== tab.id) .map((candidate) => ({ ...candidate, ...(candidate.type === 'terminal' && candidate.parentTabId === parentTabId ? { parentLayout } : {}), isActive: activate ? false : candidate.isActive })) const insertAfter = afterTabId ? tabs.findIndex((candidate) => candidate.id === afterTabId) : -1 if (insertAfter >= 0) { tabs.splice(insertAfter + 1, 0, tab) } else { tabs.push(tab) } const next: RuntimeMobileSessionTabsSnapshot = { worktree: worktreeId, publicationEpoch: `headless:${Date.now().toString(36)}`, snapshotVersion: (existing?.snapshotVersion ?? 0) + 1, // Why: activating the new tab also focuses its group, so when "+" targeted // a specific split group, make that group active too. activeGroupId: activate && targetGroupId ? targetGroupId : (existing?.activeGroupId ?? this.getHeadlessMobileSessionGroupId(worktreeId)), activeTabId: activate ? tab.id : (existing?.activeTabId ?? null), activeTabType: activate ? 'terminal' : (existing?.activeTabType ?? null), tabGroups: this.buildHeadlessMobileSessionTabGroups( worktreeId, tabs, activate ? tab : null, existing?.tabGroups, targetGroupId ? { tabId: parentTabId, groupId: targetGroupId } : undefined ), // Why: keep the group split geometry when a new tab is created, otherwise // opening a terminal while split loses the groups' arrangement. ...(existing?.tabGroupLayout ? { tabGroupLayout: existing.tabGroupLayout } : {}), tabs } this.mobileSessionTabsByWorktree.set(worktreeId, next) const result = this.toMobileSessionTabsResult(next) for (const listener of this.mobileSessionTabListeners) { listener(result) } const created = result.tabs.find((candidate) => candidate.id === tab.id) if (!created || created.type !== 'terminal') { throw new Error('terminal_handle_stale') } return { tab: created, publicationEpoch: result.publicationEpoch, snapshotVersion: result.snapshotVersion } } private waitForMobileTerminalSurface( worktreeId: string, parentTabId: string, options: { timeoutMs?: number; requireReady?: boolean } = {} ): Promise { const timeoutMs = options.timeoutMs ?? MOBILE_TERMINAL_SURFACE_TIMEOUT_MS const existing = this.findMobileTerminalSurface(worktreeId, parentTabId, options) if (existing) { return Promise.resolve(existing) } return new Promise((resolve, reject) => { const timer = setTimeout(() => { const idx = this.graphSyncCallbacks.indexOf(check) if (idx !== -1) { this.graphSyncCallbacks.splice(idx, 1) } reject(new Error('Timed out waiting for terminal surface after creation')) }, timeoutMs) const check = (): void => { const next = this.findMobileTerminalSurface(worktreeId, parentTabId, options) if (!next) { return } clearTimeout(timer) const idx = this.graphSyncCallbacks.indexOf(check) if (idx !== -1) { this.graphSyncCallbacks.splice(idx, 1) } resolve(next) } this.graphSyncCallbacks.push(check) check() }) } private findMobileTerminalSurface( worktreeId: string, parentTabId: string, options: { requireReady?: boolean } = {} ): RuntimeMobileSessionCreateTerminalResult | null { const snapshot = this.mobileSessionTabsByWorktree.get(worktreeId) if (!snapshot) { return null } const result = this.toMobileSessionTabsResult(snapshot) const tab = result.tabs.find( (candidate) => candidate.type === 'terminal' && candidate.parentTabId === parentTabId ) if (!tab || tab.type !== 'terminal') { return null } const surface = { tab, publicationEpoch: result.publicationEpoch, snapshotVersion: result.snapshotVersion } if (options.requireReady === true && !this.isReadyMobileTerminalSurface(surface)) { return null } return surface } private isReadyMobileTerminalSurface( surface: RuntimeMobileSessionCreateTerminalResult | null ): boolean { return ( surface?.tab.status === 'ready' && typeof surface.tab.terminal === 'string' && surface.tab.terminal.length > 0 ) } private waitForTerminalHandle(tabId: string, timeoutMs = 10_000): Promise { const existing = this.resolveHandleForTab(tabId) if (existing) { return Promise.resolve(existing) } return new Promise((resolve, reject) => { const timer = setTimeout(() => { const idx = this.graphSyncCallbacks.indexOf(check) if (idx !== -1) { this.graphSyncCallbacks.splice(idx, 1) } reject(new Error('Timed out waiting for terminal handle after creation')) }, timeoutMs) const check = (): void => { const handle = this.resolveHandleForTab(tabId) if (handle) { clearTimeout(timer) const idx = this.graphSyncCallbacks.indexOf(check) if (idx !== -1) { this.graphSyncCallbacks.splice(idx, 1) } resolve(handle) } } this.graphSyncCallbacks.push(check) // Why: the graph sync may have fired between the initial check and // callback registration. Re-check immediately to avoid a missed wake-up. check() }) } // Why: mobile clients may subscribe before the PTY spawns (the left pane // of a new workspace). Instead of bailing with a bare scrollback+end, // wait for the PTY to appear so the subscribe can proceed with phone-fit. waitForLeafPtyId(handle: string, timeoutMs = 10_000, signal?: AbortSignal): Promise { const leaf = this.resolveLeafForHandle(handle) if (leaf?.ptyId) { return Promise.resolve(leaf.ptyId) } // Why: when the ptyId changes from null to a real value, the old handle // is invalidated (deleted from this.handles). Capture the tabId+leafId // now so we can look up the leaf directly even after handle invalidation. const record = this.handles.get(handle) const savedTabId = record?.tabId ?? null const savedLeafId = record?.leafId ?? null return new Promise((resolve, reject) => { let timer: ReturnType | null = null let check: () => void = () => {} const cleanup = (): void => { if (timer) { clearTimeout(timer) timer = null } const idx = this.graphSyncCallbacks.indexOf(check) if (idx !== -1) { this.graphSyncCallbacks.splice(idx, 1) } signal?.removeEventListener('abort', onAbort) } const finish = (ptyId: string): void => { cleanup() resolve(ptyId) } const fail = (error: Error): void => { cleanup() reject(error) } const onAbort = (): void => { fail(new Error('request_aborted')) } if (signal?.aborted) { reject(new Error('request_aborted')) return } signal?.addEventListener('abort', onAbort, { once: true }) timer = setTimeout(() => { fail(new Error('Timed out waiting for PTY to spawn')) }, timeoutMs) check = (): void => { // Try the handle first (works if handle wasn't invalidated yet) let ptyId = this.resolveLeafForHandle(handle)?.ptyId // Why: when ptyId transitions null→real, issueHandle invalidates the // old handle. Fall back to direct leaf lookup by the saved coordinates. if (!ptyId && savedTabId && savedLeafId) { const directLeaf = this.leaves.get(this.getLeafKey(savedTabId, savedLeafId)) ptyId = directLeaf?.ptyId ?? null } if (ptyId) { finish(ptyId) } } this.graphSyncCallbacks.push(check) check() }) } // Why: a leaf appears in the graph before its PTY spawns. If we issue a // handle while ptyId is null, the next graph sync after PTY spawn will // change ptyId and invalidate the handle. Wait for a connected PTY so // the handle is stable and immediately usable for send/read/wait. private countLeavesInTab(tabId: string): number { let count = 0 for (const leaf of this.leaves.values()) { if (leaf.tabId === tabId) { count++ } } return count } private resolveHandleForTab(tabId: string): string | null { for (const leaf of this.leaves.values()) { if (leaf.tabId === tabId && leaf.ptyId !== null) { return this.issueHandle(leaf) } } return null } async focusTerminal(handle: string): Promise { const pty = this.getLivePtyForHandle(handle) if (pty) { if (!pty.pty.connected) { throw new Error('terminal_exited') } const parsedPaneKey = parsePaneKey(pty.pty.paneKey ?? '') const revealed = await this.notifier?.revealTerminalSession?.(pty.pty.worktreeId, { ptyId: pty.pty.ptyId, title: getLatestPtyTitle(pty.pty), ...(pty.pty.launchConfig ? { launchConfig: copySleepingAgentLaunchConfig(pty.pty.launchConfig) } : {}), ...(pty.pty.launchToken ? { launchToken: pty.pty.launchToken } : {}), ...(pty.pty.launchAgent ? { launchAgent: pty.pty.launchAgent } : {}), ...(pty.pty.tabId !== null ? { tabId: pty.pty.tabId } : {}), ...(parsedPaneKey ? { leafId: parsedPaneKey.leafId } : {}) }) return { handle, tabId: revealed?.tabId ?? pty.pty.tabId ?? pty.record.tabId, worktreeId: pty.pty.worktreeId } } this.assertGraphReady() const { leaf } = this.getLiveLeafForHandle(handle) this.notifier?.focusTerminal(leaf.tabId, leaf.worktreeId, leaf.leafId) return { handle, tabId: leaf.tabId, worktreeId: leaf.worktreeId } } async closeTerminal(handle: string): Promise { const pty = this.getLivePtyForHandle(handle) this.claudeAgentTeams.removeTeamForLeaderHandle(handle) if (pty) { const ptyKilled = this.ptyController?.kill(pty.pty.ptyId) ?? false return { handle, tabId: pty.pty.tabId ?? pty.record.tabId, ptyKilled } } this.assertGraphReady() const { leaf } = this.getLiveLeafForHandle(handle) let ptyKilled = false if (leaf.ptyId) { ptyKilled = this.ptyController?.kill(leaf.ptyId) ?? false } // Why: killing the PTY in a multi-pane tab is sufficient — the renderer's // PTY exit handler already calls PaneManager.closePane() for split layouts. // Sending an additional IPC close would race with the exit handler and // incorrectly close the entire tab (the pane count drops to 1 before the // IPC arrives, triggering the single-pane fallback path). // We only send the notifier close when the PTY wasn't killed (e.g. PTY not // yet spawned) or when this is the only pane in the tab. const siblingCount = this.countLeavesInTab(leaf.tabId) if (!ptyKilled || siblingCount <= 1) { this.notifier?.closeTerminal(leaf.tabId, leaf.paneRuntimeId) } return { handle, tabId: leaf.tabId, ptyKilled } } async splitTerminal( handle: string, opts: { direction?: 'horizontal' | 'vertical' command?: string env?: Record envToDelete?: string[] activate?: boolean telemetrySource?: TerminalPaneSplitSource } = {} ): Promise { const livePty = this.getLivePtyForHandle(handle) if (livePty) { return await this.splitPtyBackedTerminal(livePty.pty, opts) } this.assertGraphReady() const { leaf } = this.getLiveLeafForHandle(handle) const direction = opts.direction ?? 'horizontal' // Why: snapshot current leaf keys for this tab so we can detect the new // pane that appears after the split via graph sync delta. const leafKeysBefore = new Set() for (const [key, l] of this.leaves) { if (l.tabId === leaf.tabId) { leafKeysBefore.add(key) } } this.notifier?.splitTerminal(leaf.tabId, leaf.paneRuntimeId, { direction, command: opts.command, telemetrySource: opts.telemetrySource }) const newHandle = await this.waitForNewLeafInTab(leaf.tabId, leafKeysBefore) return { handle: newHandle, tabId: leaf.tabId, paneRuntimeId: leaf.paneRuntimeId } } private async splitPtyBackedTerminal( pty: RuntimePtyWorktreeRecord, opts: { direction?: 'horizontal' | 'vertical' command?: string env?: Record envToDelete?: string[] activate?: boolean telemetrySource?: TerminalPaneSplitSource } = {} ): Promise { if (!this.ptyController?.spawn) { throw new Error('runtime_unavailable') } if (!pty.connected) { throw new Error('terminal_exited') } const parsedPaneKey = parsePaneKey(pty.paneKey ?? '') const parentTabId = pty.tabId?.trim() if (!parentTabId || !parsedPaneKey) { throw new Error('terminal_handle_stale') } const direction = opts.direction ?? 'horizontal' const workspace = await this.resolveTerminalWorkspaceLaunchScope(`id:${pty.worktreeId}`) const leafId = randomUUID() const preAllocatedHandle = this.createPreAllocatedTerminalHandle() const paneKey = makePaneKey(parentTabId, leafId) const result = await this.ptyController.spawn({ cols: 120, rows: 40, cwd: workspace.path, command: opts.command, commandDelivery: 'provider', env: this.buildTerminalWorkspaceEnv(workspace, opts.env ?? {}, paneKey, parentTabId), envToDelete: opts.envToDelete, connectionId: workspace.connectionId, worktreeId: workspace.id, preAllocatedHandle }) this.registerPreAllocatedHandleForPty(result.id, preAllocatedHandle) this.registerPty(result.id, workspace.id, workspace.connectionId) const createdPty = this.getOrCreatePtyWorktreeRecord(result.id) if (createdPty) { createdPty.tabId = parentTabId createdPty.paneKey = paneKey } try { await this.notifier?.revealTerminalSession?.(workspace.id, { ptyId: result.id, title: null, activate: opts.activate !== false, tabId: parentTabId, leafId, splitFromLeafId: parsedPaneKey.leafId, splitDirection: direction, splitTelemetrySource: opts.telemetrySource }) } catch (error) { this.ptyController.kill?.(result.id) throw error } if (createdPty) { this.publishPtyBackedMobileSessionTerminal(workspace.id, createdPty, { tabId: parentTabId, leafId, title: null, activate: opts.activate !== false, split: { splitFromLeafId: parsedPaneKey.leafId, direction } }) // Why: persist the split into the workspace session so a later snapshot // rebuild keeps it instead of collapsing back to a single pane. this.persistHeadlessTerminalSplit({ tabId: parentTabId, leafId, ptyId: createdPty.ptyId, splitFromLeafId: parsedPaneKey.leafId, direction }) } return { handle: this.issuePtyHandle(createdPty ?? pty), tabId: parentTabId, paneRuntimeId: -1 } } async handleAgentTeamsTmuxCompat( request: AgentTeamsTmuxCompatRequest ): Promise { return await this.claudeAgentTeams.handleTmuxCompat(request, { splitTerminal: (handle, opts) => this.splitTerminal(handle, opts), readTerminal: (handle, opts) => this.readTerminal(handle, opts), sendTerminal: (handle, action) => this.sendTerminal(handle, action), focusTerminal: (handle) => this.focusTerminal(handle), closeTerminal: (handle) => this.closeTerminal(handle), showTerminal: (handle) => this.showTerminal(handle) }) } async prepareClaudeAgentTeamsLeader(args: { paneKey: string baseEnv?: Record }): Promise<{ env: Record }> { const handle = this.getTerminalHandleForPaneKey(args.paneKey) if (!handle) { throw new Error('claude_agent_teams_requires_orca_terminal') } return await this.prepareClaudeAgentTeamsLeaderForHandle({ handle, baseEnv: args.baseEnv }) } async prepareClaudeAgentTeamsLeaderForHandle(args: { handle: string baseEnv?: Record }): Promise<{ env: Record }> { const baseEnv = { ...process.env, ...args.baseEnv } const shimDir = await ensureClaudeAgentTeamsShimDir() const shimBin = resolveClaudeAgentTeamsShimBin(baseEnv) return this.claudeAgentTeams.createLaunchEnv({ leaderHandle: args.handle, baseEnv, shimDir, shimBin }) } private waitForNewLeafInTab( tabId: string, existingLeafKeys: Set, timeoutMs = 10_000 ): Promise { const tryResolve = (): string | null => { for (const [key, leaf] of this.leaves) { if (leaf.tabId === tabId && !existingLeafKeys.has(key) && leaf.ptyId !== null) { return this.issueHandle(leaf) } } return null } const existing = tryResolve() if (existing) { return Promise.resolve(existing) } return new Promise((resolve, reject) => { const timer = setTimeout(() => { const idx = this.graphSyncCallbacks.indexOf(check) if (idx !== -1) { this.graphSyncCallbacks.splice(idx, 1) } reject(new Error('Timed out waiting for split pane handle')) }, timeoutMs) const check = (): void => { const handle = tryResolve() if (handle) { clearTimeout(timer) const idx = this.graphSyncCallbacks.indexOf(check) if (idx !== -1) { this.graphSyncCallbacks.splice(idx, 1) } resolve(handle) } } this.graphSyncCallbacks.push(check) check() }) } async stopTerminalsForWorktree(worktreeSelector: string): Promise<{ stopped: number }> { // Why: this mutates live PTYs, so the runtime must reject it while the // renderer graph is reloading instead of acting on cached leaf ownership. const graphEpoch = this.captureReadyGraphEpoch() const worktree = await this.resolveWorktreeSelector(worktreeSelector) this.assertStableReadyGraph(graphEpoch) const ptyIds = new Set() for (const leaf of this.leaves.values()) { if (leaf.worktreeId === worktree.id && leaf.ptyId) { ptyIds.add(leaf.ptyId) } } for (const pty of this.ptysById.values()) { if (pty.worktreeId === worktree.id && pty.connected) { ptyIds.add(pty.ptyId) } } let stopped = 0 for (const ptyId of ptyIds) { if (this.ptyController?.kill(ptyId)) { stopped += 1 } } return { stopped } } async stopExactTerminalsForWorktree( worktreeSelector: string, expectedPtyIds: readonly string[], opts: { keepHistory?: boolean; targetOnly?: boolean } = {} ): Promise<{ stopped: number stoppedPtyIds: string[] livePtyIds: string[] postStopVerified: boolean postStopFailure?: string remainingLivePtyIds?: string[] }> { // Why: worktree sleep needs proof of the complete live set; pane hibernation // only needs proof that its target PTY was live and is now gone. const graphEpoch = this.captureReadyGraphEpoch() const worktree = await this.resolveWorktreeSelector(worktreeSelector) this.assertStableReadyGraph(graphEpoch) const expected = new Set(expectedPtyIds.filter((ptyId) => ptyId.length > 0)) if (expected.size !== 1) { throw new Error('terminal_exact_stop_requires_single_pty') } const resolvedWorktrees = [...(await this.getResolvedWorktreeMap()).values()] const refreshedPtyLiveness = await this.refreshPtyWorktreeRecordsFromController(resolvedWorktrees) if (!refreshedPtyLiveness) { throw new Error('terminal_liveness_unavailable') } const livePtyIds = this.getLivePtyIdsForWorktree(worktree.id, refreshedPtyLiveness) const targetOnly = opts.targetOnly === true const expectedIsLive = [...expected].every((ptyId) => livePtyIds.has(ptyId)) if (targetOnly ? !expectedIsLive : !setsEqual(livePtyIds, expected)) { const error = Object.assign(new Error('terminal_stop_pty_set_mismatch'), { livePtyIds: [...livePtyIds].sort(), expectedPtyIds: [...expected].sort() }) throw error } if (!this.ptyController?.stopAndWait) { throw new Error('terminal_exact_stop_unavailable') } const stoppedPtyIds: string[] = [] for (const ptyId of [...expected].sort()) { if (!(await this.ptyController.stopAndWait(ptyId, { keepHistory: opts.keepHistory }))) { throw Object.assign(new Error('terminal_exact_stop_failed'), { ptyId }) } stoppedPtyIds.push(ptyId) } const postStopLiveness = await this.refreshPtyWorktreeRecordsFromController(resolvedWorktrees) if (!postStopLiveness) { return { stopped: stoppedPtyIds.length, stoppedPtyIds, livePtyIds: [...livePtyIds].sort(), postStopVerified: false, postStopFailure: 'terminal_liveness_unavailable' } } const remainingLivePtyIds = this.getLivePtyIdsForWorktree(worktree.id, postStopLiveness) const stoppedTargetsStillLive = [...expected].filter((ptyId) => remainingLivePtyIds.has(ptyId)) if (targetOnly ? stoppedTargetsStillLive.length > 0 : remainingLivePtyIds.size > 0) { return { stopped: stoppedPtyIds.length, stoppedPtyIds, livePtyIds: [...livePtyIds].sort(), postStopVerified: false, postStopFailure: 'terminal_exact_stop_still_live', remainingLivePtyIds: [...remainingLivePtyIds].sort() } } return { stopped: stoppedPtyIds.length, stoppedPtyIds, livePtyIds: [...livePtyIds].sort(), postStopVerified: true, ...(targetOnly && remainingLivePtyIds.size > 0 ? { remainingLivePtyIds: [...remainingLivePtyIds].sort() } : {}) } } private getLivePtyIdsForWorktree( worktreeId: string, freshPtyIds?: ReadonlySet ): Set { const ptyIds = new Set() for (const leaf of this.leaves.values()) { if ( leaf.worktreeId === worktreeId && leaf.connected && leaf.ptyId && (!freshPtyIds || freshPtyIds.has(leaf.ptyId)) ) { ptyIds.add(leaf.ptyId) } } for (const pty of this.ptysById.values()) { if ( pty.worktreeId === worktreeId && pty.connected && (!freshPtyIds || freshPtyIds.has(pty.ptyId)) ) { ptyIds.add(pty.ptyId) } } return ptyIds } async hasTerminalsForWorktree(worktreeSelector: string): Promise { const graphEpoch = this.captureReadyGraphEpoch() const worktree = await this.resolveWorktreeSelector(worktreeSelector) this.assertStableReadyGraph(graphEpoch) for (const leaf of this.leaves.values()) { if (leaf.worktreeId === worktree.id && leaf.ptyId) { return true } } for (const pty of this.ptysById.values()) { if (pty.worktreeId === worktree.id && pty.connected) { return true } } return false } markRendererReloading(windowId: number): void { if (windowId !== this.authoritativeWindowId) { return } if (this.graphStatus !== 'ready') { return } // Why: any renderer reload tears down the published live graph, so live // terminal handles must become stale immediately instead of being reused // against whatever the renderer rebuilds next. this.rendererGraphEpoch += 1 this.graphStatus = 'reloading' this.rememberDetachedPreAllocatedLeaves() this.handles.clear() this.handleByLeafKey.clear() // Why: handleByPtyId maps ptyId → pre-allocated CLI handle (ORCA_TERMINAL_HANDLE). // These must survive renderer reloads so CLI agents can keep controlling the // same terminal across graph rebuilds — adoptPreAllocatedHandle re-links // them when the new graph arrives. this.rejectAllWaiters('terminal_handle_stale') this.refreshWritableFlags() } markGraphReady(windowId: number): void { if (windowId !== this.authoritativeWindowId) { return } this.graphStatus = 'ready' this.refreshWritableFlags() } markGraphUnavailable(windowId: number): void { if (windowId !== this.authoritativeWindowId) { return } // Why: once the authoritative renderer graph disappears, Orca must fail // closed for live-terminal operations instead of guessing from old state. if (this.graphStatus !== 'unavailable') { this.rendererGraphEpoch += 1 } this.graphStatus = 'unavailable' this.authoritativeWindowId = null this.rememberDetachedPreAllocatedLeaves() this.tabs.clear() this.leaves.clear() this.leavesByPtyId.clear() this.handles.clear() this.handleByLeafKey.clear() // Why: same as markRendererReloading — pre-allocated CLI handles must // survive graph unavailability so they can be re-adopted on reconnect. this.rejectAllWaiters('terminal_handle_stale') } private assertGraphReady(): void { if (this.graphStatus !== 'ready') { throw new Error('runtime_unavailable') } } private captureReadyGraphEpoch(): number { this.assertGraphReady() return this.rendererGraphEpoch } private assertStableReadyGraph(expectedGraphEpoch: number): void { if (this.graphStatus !== 'ready' || this.rendererGraphEpoch !== expectedGraphEpoch) { throw new Error('runtime_unavailable') } } private resolveFolderWorkspaceConnectionId(workspace: FolderWorkspace): string | null { const repos = this.store?.getRepos() ?? [] const projectGroups = this.store?.getProjectGroups?.() ?? [] const connection = inferFolderWorkspacePathConnection({ folderPath: workspace.folderPath, projectGroupId: workspace.projectGroupId, connectionId: workspace.connectionId ?? null, projectGroups, repos }) if (connection.kind === 'ambiguous') { // Why: a single PTY can only be spawned on one runtime target; mixed // child repo connections need an explicit V2 routing decision. throw new Error('folder_workspace_connection_ambiguous') } return connection.kind === 'ssh' ? connection.connectionId : null } private async resolveFolderWorkspaceLaunchScope( selector: string ): Promise { const workspaceSelector = selector.startsWith('id:') ? selector.slice(3) : selector const parsed = parseWorkspaceKey(workspaceSelector) if (parsed?.type !== 'folder') { return null } const workspace = this.store ?.getFolderWorkspaces?.() .find((entry) => entry.id === parsed.folderWorkspaceId) if (!workspace) { throw new Error('selector_not_found') } if (!this.store) { throw new Error('runtime_unavailable') } const status = await getFolderWorkspacePathStatus( this.store, { scope: 'folder-workspace', folderWorkspaceId: workspace.id }, { getSshFilesystemProvider } ) assertFolderWorkspacePathUsable(status) return { id: folderWorkspaceKey(workspace.id), path: workspace.folderPath, connectionId: this.resolveFolderWorkspaceConnectionId(workspace), repo: null, folderWorkspace: workspace } } private folderWorkspaceToResolvedWorktree(folderWorkspace: FolderWorkspace): ResolvedWorktree { const worktree = folderWorkspaceToWorktree(folderWorkspace) return { ...worktree, parentWorktreeId: null, childWorktreeIds: [], lineage: null, git: { path: worktree.path, head: worktree.head, branch: worktree.branch, isBare: worktree.isBare, isMainWorktree: worktree.isMainWorktree } } } private async resolveTerminalWorkspaceLaunchScope( selector: string ): Promise { const floatingTerminalSelector = selector === FLOATING_TERMINAL_WORKTREE_ID || selector === `id:${FLOATING_TERMINAL_WORKTREE_ID}` if (floatingTerminalSelector) { // Why: the floating sentinel is terminal-only; other workspace APIs must // keep rejecting it because there is no backing repo/worktree record. return { id: FLOATING_TERMINAL_WORKTREE_ID, path: homedir(), connectionId: null, repo: null, folderWorkspace: null } } const folderScope = await this.resolveFolderWorkspaceLaunchScope(selector) if (folderScope) { return folderScope } const workspaceSelector = selector.startsWith('id:') ? selector.slice(3) : selector const parsed = parseWorkspaceKey(workspaceSelector) const worktreeSelector = parsed?.type === 'worktree' ? `id:${parsed.worktreeId}` : selector const worktree = await this.resolveWorktreeSelector(worktreeSelector) const repo = this.store?.getRepo(worktree.repoId) ?? null return { id: worktree.id, path: worktree.path, connectionId: repo?.connectionId ?? null, repo, folderWorkspace: null } } private buildTerminalWorkspaceEnv( scope: TerminalWorkspaceLaunchScope, baseEnv: Record, paneKey: string, tabId: string, agentTeamsEnv?: Record ): Record { const cleanBaseEnv = { ...baseEnv } for (const key of AGENT_HOOK_RUNTIME_ENV_KEYS) { delete cleanBaseEnv[key] } const env = { ...cleanBaseEnv, ...agentTeamsEnv, ...this.buildAgentHookPtyEnv?.(), ORCA_PANE_KEY: paneKey, ORCA_TAB_ID: tabId, ORCA_WORKTREE_ID: scope.id } if (!scope.folderWorkspace) { return env } return { ...env, ORCA_WORKSPACE_ID: scope.id, ORCA_PROJECT_GROUP_ID: scope.folderWorkspace.projectGroupId, ORCA_WORKSPACE_ROOT: scope.folderWorkspace.folderPath } } private async resolveWorktreeSelector(selector: string): Promise { const worktrees = await this.listResolvedWorktrees() let candidates: ResolvedWorktree[] if (selector === 'active') { throw new Error('selector_not_found') } if (selector.startsWith('id:')) { const worktreeId = selector.slice(3) candidates = worktrees.filter((worktree) => worktree.id === worktreeId) if (candidates.length === 0) { const parsed = splitWorktreeIdForFilesystem(worktreeId) const repo = parsed ? this.store?.getRepo(parsed.repoId) : null const fallback = repo?.connectionId && this.store?.getWorktreeMeta(worktreeId) ? this.buildResolvedWorktreeFromId(worktreeId) : null if (fallback !== null) { candidates = [fallback] } } } else if (selector.startsWith('path:')) { candidates = worktrees.filter((worktree) => runtimePathsEqual(worktree.path, selector.slice(5)) ) if (candidates.length > 1) { // Why: registering another worktree from the same Git repo makes git // report the same physical worktree path under multiple repo IDs. // A path selector is already exact, so prefer the first resolved row // instead of surfacing a duplicate-registration ambiguity. candidates = [candidates[0]] } } else if (selector.startsWith('branch:')) { const branchSelector = selector.slice(7) candidates = worktrees.filter((worktree) => branchSelectorMatches(worktree.branch, branchSelector) ) } else if (selector.startsWith('name:')) { // Keep display-name matching exact so selector behavior stays deterministic // and duplicate names use the same ambiguity path as other selectors. candidates = worktrees.filter((worktree) => worktree.displayName === selector.slice(5)) } else if (selector.startsWith('issue:')) { candidates = worktrees.filter( (worktree) => worktree.linkedIssue !== null && String(worktree.linkedIssue) === selector.slice(6) ) } else { candidates = worktrees.filter( (worktree) => worktree.id === selector || runtimePathsEqual(worktree.path, selector) || branchSelectorMatches(worktree.branch, selector) ) } if (candidates.length === 1) { return candidates[0] } if (candidates.length > 1) { throw new Error('selector_ambiguous') } throw new Error('selector_not_found') } private async resolveWorkspaceParentSelector(selector: string): Promise { const rawSelector = selector.startsWith('id:') ? selector.slice('id:'.length) : selector const parsed = parseWorkspaceKey(rawSelector) if (parsed?.type === 'folder') { const folderWorkspace = this.store ?.getFolderWorkspaces?.() .find((workspace) => workspace.id === parsed.folderWorkspaceId) if (!folderWorkspace) { throw new Error('selector_not_found') } return { type: 'folder', workspaceKey: folderWorkspaceKey(folderWorkspace.id), folderWorkspace, instanceId: null } } const worktreeSelector = parsed?.type === 'worktree' ? `id:${parsed.worktreeId}` : selector const worktree = await this.resolveWorktreeSelector(worktreeSelector) return { type: 'worktree', workspaceKey: worktreeWorkspaceKey(worktree.id), worktree, instanceId: worktree.instanceId ?? null } } private validateLineageParent(child: ResolvedWorktree, parent: ResolvedWorktree): void { const childWorktreeId = child.id const parentWorktreeId = parent.id if (childWorktreeId === parentWorktreeId) { throw new RuntimeLineageError('LINEAGE_PARENT_CYCLE', 'A worktree cannot parent itself.') } const instanceByWorktreeId = new Map( this.resolvedWorktreeCache?.worktrees.map((worktree) => [ worktree.id, worktree.instanceId ]) ?? [ [child.id, child.instanceId], [parent.id, parent.instanceId] ] ) let cursor: string | undefined = parentWorktreeId const visited = new Set([childWorktreeId]) while (cursor) { if (visited.has(cursor)) { throw new RuntimeLineageError( 'LINEAGE_PARENT_CYCLE', 'Parent selector would create a lineage cycle.' ) } visited.add(cursor) const lineage = this.store?.getWorktreeLineage?.(cursor) if (!lineage) { break } const cursorInstanceId = instanceByWorktreeId.get(cursor) const parentInstanceId = instanceByWorktreeId.get(lineage.parentWorktreeId) if ( cursorInstanceId !== lineage.worktreeInstanceId || parentInstanceId !== lineage.parentWorktreeInstanceId ) { break } cursor = lineage.parentWorktreeId } } private async resolveLineageForWorktreeCreate( input?: WorktreeLineageInput ): Promise { if (!input) { return { kind: 'none', warnings: [] } } if (input.noParent === true && (input.parentWorkspace || input.parentWorktree)) { throw new RuntimeLineageError( 'LINEAGE_PARENT_CONTEXT_CONFLICT', 'Choose either one parent selector or --no-parent.' ) } if (input.parentWorkspace && input.parentWorktree) { throw new RuntimeLineageError( 'LINEAGE_PARENT_CONTEXT_CONFLICT', 'Choose either one parent selector or --no-parent.' ) } if (input.noParent === true) { return { kind: 'none', warnings: [] } } if (input.parentWorkspace) { try { return { kind: 'lineage', parent: await this.resolveWorkspaceParentSelector(input.parentWorkspace), origin: 'cli', capture: { source: 'explicit-cli-flag', confidence: 'explicit' } } } catch { throw new RuntimeLineageError( 'LINEAGE_PARENT_NOT_FOUND', 'Parent selector was not found.', { nextSteps: [ 'Pass a valid --parent-worktree selector such as folder:, worktree:, id:, branch:, issue:, path:, or active/current.', 'Retry with --no-parent to create without lineage.' ] } ) } } if (input.parentWorktree) { try { const parent = await this.resolveWorktreeSelector(input.parentWorktree) return { kind: 'lineage', parent: { type: 'worktree', workspaceKey: worktreeWorkspaceKey(parent.id), worktree: parent, instanceId: parent.instanceId ?? null }, origin: 'cli', capture: { source: 'explicit-cli-flag', confidence: 'explicit' } } } catch { throw new RuntimeLineageError( 'LINEAGE_PARENT_NOT_FOUND', 'Parent selector was not found.', { nextSteps: [ 'Pass a valid --parent-worktree selector such as folder:, worktree:, id:, branch:, issue:, path:, or active/current.', 'Retry with --no-parent to create without lineage.' ] } ) } } const warnings: WorktreeLineageWarning[] = [] const candidates: WorktreeLineageCandidate[] = [] let cwdCandidate: WorktreeLineageCandidate | null = null let terminalContextResolved = false if (input.envParentWorkspace) { try { candidates.push({ source: 'env-workspace', parent: await this.resolveWorkspaceParentSelector(input.envParentWorkspace) }) } catch { warnings.push({ code: 'LINEAGE_PARENT_CONTEXT_MISSING', message: 'Worktree created, but Orca could not validate the environment parent context.', details: { envParentWorkspace: input.envParentWorkspace } }) } } if (input.orchestrationContext?.parentWorktreeId) { try { const parent = await this.resolveWorktreeSelector( `id:${input.orchestrationContext.parentWorktreeId}` ) candidates.push({ source: 'orchestration-context', parent: { type: 'worktree', workspaceKey: worktreeWorkspaceKey(parent.id), worktree: parent, instanceId: parent.instanceId ?? null } }) } catch { // Keep creation recoverable; the warning below covers missing inferred context. } } const commentTaskId = extractOrchestrationTaskId(input.comment) if (commentTaskId) { const candidate = await this.resolveLineageCandidateForTaskId(commentTaskId) if (candidate) { candidates.push(candidate) } } if (input.callerTerminalHandle) { try { const terminal = await this.showTerminal(input.callerTerminalHandle) const terminalParent = await this.resolveWorkspaceParentSelector( `id:${terminal.worktreeId}` ) const activeDispatch = this._orchestrationDb?.getActiveDispatchForTerminal( input.callerTerminalHandle ) const activeRun = this._orchestrationDb?.getActiveCoordinatorRun() if (activeDispatch) { candidates.push({ source: 'orchestration-context', parent: terminalParent, taskId: activeDispatch.task_id, ...(activeRun ? { orchestrationRunId: activeRun.id, coordinatorHandle: activeRun.coordinator_handle } : {}) }) } else { candidates.push({ source: 'terminal-context', parent: terminalParent }) } terminalContextResolved = true } catch { // Why: terminal handles can go stale during reloads or SSH reconnects. // A valid orchestration parent is still authoritative, so keep resolving // other inferred candidates instead of dropping lineage completely. warnings.push({ code: 'LINEAGE_PARENT_CONTEXT_MISSING', message: 'Worktree created, but Orca could not validate the caller terminal as a parent context.', details: { callerTerminalHandle: input.callerTerminalHandle } }) } } if (input.cwdParentWorktree) { try { cwdCandidate = { source: 'cwd-context', parent: await this.resolveWorkspaceParentSelector(input.cwdParentWorktree) } } catch { warnings.push({ code: 'LINEAGE_PARENT_CONTEXT_MISSING', message: 'Worktree created, but Orca could not validate the current directory as a parent context.', details: { cwdParentWorktree: input.cwdParentWorktree } }) } } if (candidates.length === 0 && cwdCandidate) { candidates.push(cwdCandidate) } if (candidates.length === 0) { return { kind: 'none', warnings } } const [first] = candidates const conflict = candidates.find( (candidate) => candidate.parent.workspaceKey !== first.parent.workspaceKey ) if (conflict) { return { kind: 'none', warnings: [ { code: 'LINEAGE_PARENT_CONTEXT_CONFLICT', message: 'Worktree created, but Orca could not prove which parent context caused it.', details: { terminalParentWorkspaceKey: candidates.find((c) => c.source === 'terminal-context') ?.parent.workspaceKey, envParentWorkspaceKey: candidates.find((c) => c.source === 'env-workspace')?.parent .workspaceKey, orchestrationParentWorkspaceKey: candidates.find( (c) => c.source === 'orchestration-context' )?.parent.workspaceKey } } ] } } const preferred = candidates.find((candidate) => candidate.source === 'env-workspace') ?? candidates.find((candidate) => candidate.source === 'orchestration-context') ?? first return { kind: 'lineage', parent: preferred.parent, origin: preferred.source === 'orchestration-context' ? 'orchestration' : 'cli', capture: { source: preferred.source, confidence: 'inferred' }, ...((preferred.orchestrationRunId ?? input.orchestrationContext?.orchestrationRunId) ? { orchestrationRunId: preferred.orchestrationRunId ?? input.orchestrationContext?.orchestrationRunId } : {}), ...((preferred.taskId ?? input.orchestrationContext?.taskId) ? { taskId: preferred.taskId ?? input.orchestrationContext?.taskId } : {}), ...((preferred.coordinatorHandle ?? input.orchestrationContext?.coordinatorHandle) ? { coordinatorHandle: preferred.coordinatorHandle ?? input.orchestrationContext?.coordinatorHandle } : {}), ...(terminalContextResolved && input.callerTerminalHandle ? { createdByTerminalHandle: input.callerTerminalHandle } : {}) } } private async resolveLineageCandidateForTaskId( taskId: string ): Promise { const db = this.getOrchestrationDbIfAvailable() const dispatch = db?.getDispatchContext(taskId) // Why: agent-created task records may never be dispatched, but the // creating terminal still identifies the parent workspace for descendants. const parentHandle = dispatch?.assignee_handle ?? db?.getTask(taskId)?.created_by_terminal_handle if (!parentHandle) { return null } try { const terminal = await this.showTerminal(parentHandle) const parent = await this.resolveWorktreeSelector(`id:${terminal.worktreeId}`) return { source: 'orchestration-context', parent: { type: 'worktree', workspaceKey: worktreeWorkspaceKey(parent.id), worktree: parent, instanceId: parent.instanceId ?? null }, taskId } } catch { return null } } private getOrchestrationDbIfAvailable(): OrchestrationDb | null { try { return this._orchestrationDb ?? this.getOrchestrationDb() } catch { return this._orchestrationDb } } async hydrateInferredWorktreeLineage(): Promise { const store = this.store if ( !store || typeof store.getWorktreeLineage !== 'function' || typeof store.setWorktreeLineage !== 'function' ) { return } const worktrees = await this.listResolvedWorktrees() for (const worktree of worktrees) { if (store.getWorktreeLineage(worktree.id) || !worktree.instanceId) { continue } const taskId = extractOrchestrationTaskId(worktree.comment) if (!taskId) { continue } const candidate = await this.resolveLineageCandidateForTaskId(taskId) if ( !candidate?.parent.instanceId || candidate.parent.type !== 'worktree' || candidate.parent.worktree.id === worktree.id ) { continue } try { this.validateLineageParent(worktree, candidate.parent.worktree) } catch { continue } store.setWorktreeLineage(worktree.id, { worktreeId: worktree.id, worktreeInstanceId: worktree.instanceId, parentWorktreeId: candidate.parent.worktree.id, parentWorktreeInstanceId: candidate.parent.instanceId, origin: 'orchestration', capture: { source: 'orchestration-context', confidence: 'inferred' }, taskId, createdAt: Date.now() }) } } async listWorktreeLineage(): Promise> { await this.hydrateInferredWorktreeLineage() return this.store?.getAllWorktreeLineage?.() ?? {} } async listWorkspaceLineage(): Promise> { await this.hydrateInferredWorktreeLineage() return this.store?.getAllWorkspaceLineage?.() ?? {} } private async resolveRepoSelector(selector: string): Promise { if (!this.store) { throw new Error('repo_not_found') } const repos = this.store.getRepos() let candidates: Repo[] if (selector.startsWith('id:')) { candidates = repos.filter((repo) => repo.id === selector.slice(3)) } else if (selector.startsWith('path:')) { candidates = repos.filter((repo) => runtimePathsEqual(repo.path, selector.slice(5))) } else if (selector.startsWith('name:')) { candidates = repos.filter((repo) => repo.displayName === selector.slice(5)) } else { candidates = repos.filter( (repo) => repo.id === selector || runtimePathsEqual(repo.path, selector) || repo.displayName === selector ) } if (candidates.length === 1) { return candidates[0] } if (candidates.length > 1) { throw new Error('selector_ambiguous') } throw new Error('repo_not_found') } private requireStore(): Store { if (!this.store) { throw new Error('runtime_unavailable') } return this.store as unknown as Store } private buildResolvedWorktreeFromId(worktreeId: string): ResolvedWorktree | null { const parsed = splitWorktreeIdForFilesystem(worktreeId) if (!parsed?.repoId || !parsed.worktreePath) { return null } const repo = this.store?.getRepos().find((entry) => entry.id === parsed.repoId) const git = { path: parsed.worktreePath, head: '', branch: '', isBare: false, isMainWorktree: repo ? areWorktreePathsEqual(parsed.worktreePath, repo.path) : false } const meta = this.store?.getWorktreeMeta(worktreeId) const merged = mergeWorktree(parsed.repoId, git, meta, repo?.displayName) return { ...merged, id: worktreeId, parentWorktreeId: null, childWorktreeIds: [], lineage: null, git, displayName: merged.displayName, comment: merged.comment } } private listKnownResolvedWorktreesForExplicitTarget( targetWorktreeId: string, targetWorktree: ResolvedWorktree | null ): ResolvedWorktree[] { if (!this.store || !targetWorktree) { return [] } const target = splitWorktreeIdForFilesystem(targetWorktreeId) if (!target?.repoId || !target.worktreePath) { return [] } const worktreeIds = new Set( Object.keys(this.store.getAllWorktreeMeta()).filter((worktreeId) => { const parsed = splitWorktreeIdForFilesystem(worktreeId) return ( parsed?.repoId === target.repoId && Boolean(parsed.worktreePath) && (isPathInsideOrEqual(target.worktreePath, parsed.worktreePath) || isPathInsideOrEqual(parsed.worktreePath, target.worktreePath)) ) }) ) worktreeIds.add(targetWorktreeId) const resolved: ResolvedWorktree[] = [] for (const worktreeId of worktreeIds) { const worktree = worktreeId === targetWorktreeId ? targetWorktree : this.buildResolvedWorktreeFromId(worktreeId) if (worktree) { resolved.push(worktree) } } return resolved } private async listResolvedWorktrees(): Promise { if (!this.store) { return [] } const now = Date.now() if (this.resolvedWorktreeCache && this.resolvedWorktreeCache.expiresAt > now) { return this.resolvedWorktreeCache.worktrees } const generation = this.resolvedWorktreeGeneration if (this.resolvedWorktreeInFlight?.generation === generation) { return this.resolvedWorktreeInFlight.promise } const promise = this.computeResolvedWorktrees(generation) this.resolvedWorktreeInFlight = { generation, promise } try { return await promise } finally { if (this.resolvedWorktreeInFlight?.promise === promise) { this.resolvedWorktreeInFlight = null } } } private async computeResolvedWorktrees(generation: number): Promise { if (!this.store) { return [] } const now = Date.now() const metaById = this.store.getAllWorktreeMeta() ?? {} const perRepoWorktrees = await Promise.all( this.store.getRepos().map(async (repo) => { if (isFolderRepo(repo)) { return listRuntimeFolderWorkspaces(this.requireStore(), repo).map((worktree) => ({ ...worktree, parentWorktreeId: null, childWorktreeIds: [], lineage: null, git: { path: worktree.path, head: worktree.head, branch: worktree.branch, isBare: worktree.isBare, isMainWorktree: worktree.isMainWorktree }, displayName: worktree.displayName, comment: worktree.comment })) } // Why: mobile startup RPCs share this path. A slow repo scan should // degrade one repo's metadata, not block all terminal/session loading. const scan = await withTimeout( this.listRepoWorktreesForResolution(repo), RESOLVED_WORKTREE_REPO_TIMEOUT_MS, { ok: false, worktrees: [] } ) const gitWorktrees = scan.worktrees if (scan.ok) { this.pruneLineageForMissingRepoWorktrees(repo, gitWorktrees) } return gitWorktrees.map((gitWorktree) => { const worktreeId = `${repo.id}::${gitWorktree.path}` // Why: lineage validation needs a durable instance ID even when the // runtime sees a workspace before the renderer's discovery-stamp path. const existingMeta = metaById[worktreeId] const meta = existingMeta && existingMeta.instanceId ? existingMeta : this.store?.setWorktreeMeta(worktreeId, {}) const merged = mergeWorktree(repo.id, gitWorktree, meta, repo.displayName) return { ...merged, parentWorktreeId: null, childWorktreeIds: [], lineage: null, git: { path: gitWorktree.path, head: gitWorktree.head, branch: gitWorktree.branch, isBare: gitWorktree.isBare, isMainWorktree: gitWorktree.isMainWorktree }, displayName: merged.displayName, comment: merged.comment } }) }) ) const worktrees = this.attachLineageToResolvedWorktrees(perRepoWorktrees.flat()) // Why: terminal polling can be frequent, but git worktree state is still // allowed to change outside Orca. A short TTL avoids shelling out on every // read without pretending the cache is authoritative for long. if (generation === this.resolvedWorktreeGeneration) { this.resolvedWorktreeCache = { worktrees, expiresAt: now + RESOLVED_WORKTREE_CACHE_TTL_MS } } return worktrees } private attachLineageToResolvedWorktrees(worktrees: ResolvedWorktree[]): ResolvedWorktree[] { const lineageById = this.store?.getAllWorktreeLineage?.() ?? {} const worktreeById = new Map(worktrees.map((worktree) => [worktree.id, worktree])) const validLineageByChildId = new Map() const childIdsByParentId = new Map() for (const [childId, lineage] of Object.entries(lineageById)) { const child = worktreeById.get(childId) const parent = worktreeById.get(lineage.parentWorktreeId) if ( !child || !parent || child.instanceId !== lineage.worktreeInstanceId || parent.instanceId !== lineage.parentWorktreeInstanceId ) { // Why: worktree IDs are path-derived. Instance checks keep replacement // checkouts from appearing as children of stale same-path lineage. continue } validLineageByChildId.set(childId, lineage) const children = childIdsByParentId.get(lineage.parentWorktreeId) ?? [] children.push(childId) childIdsByParentId.set(lineage.parentWorktreeId, children) } return worktrees.map((worktree) => { const lineage = validLineageByChildId.get(worktree.id) ?? null return { ...worktree, parentWorktreeId: lineage?.parentWorktreeId ?? null, childWorktreeIds: childIdsByParentId.get(worktree.id) ?? [], lineage } }) } private pruneLineageForMissingRepoWorktrees(repo: Repo, gitWorktrees: GitWorktreeInfo[]): void { const store = this.store if ( !store || typeof store.getAllWorktreeLineage !== 'function' || typeof store.removeWorktreeLineage !== 'function' ) { return } const liveIds = new Set(gitWorktrees.map((worktree) => `${repo.id}::${worktree.path}`)) const repoPrefix = `${repo.id}::` for (const childWorkspaceKey of Object.keys(store.getAllWorkspaceLineage?.() ?? {})) { const childScope = parseWorkspaceKey(childWorkspaceKey) if ( childScope?.type === 'worktree' && childScope.worktreeId.startsWith(repoPrefix) && !liveIds.has(childScope.worktreeId) ) { if (isWorkspaceKey(childWorkspaceKey)) { store.removeWorkspaceLineage?.(childWorkspaceKey) } } } for (const [childId, lineage] of Object.entries(store.getAllWorktreeLineage())) { if (childId.startsWith(repoPrefix) && !liveIds.has(childId)) { // Why: runtime selector scans can be the only scan before a path is // reused. Once a successful scan proves the child is gone, stale // lineage must not survive into the replacement checkout. store.removeWorktreeLineage(childId) store.removeWorkspaceLineage?.(worktreeWorkspaceKey(childId)) } if ( lineage.parentWorktreeId.startsWith(repoPrefix) && !liveIds.has(lineage.parentWorktreeId) ) { const parentMeta = store.getWorktreeMeta(lineage.parentWorktreeId) if (!parentMeta || parentMeta.instanceId === lineage.parentWorktreeInstanceId) { // Why: preserving child lineage powers the repair UI, but a missing // parent path only needs one fresh identity to keep same-path // replacement checkouts from validating old lineage. store.setWorktreeMeta(lineage.parentWorktreeId, { instanceId: randomUUID() }) } } } } private async listRepoWorktreesForResolution(repo: Repo): Promise { if (!repo.connectionId) { return { ok: true, worktrees: await listRepoWorktrees( repo, getLocalProjectWorktreeGitOptions(this.requireStore(), repo) ) } } const provider = getSshGitProvider(repo.connectionId) if (!provider) { return { ok: false, worktrees: this.listStoredSshWorktreesForResolution(repo) } } try { return { ok: true, worktrees: await provider.listWorktrees(repo.path) } } catch { return { ok: false, worktrees: this.listStoredSshWorktreesForResolution(repo) } } } private listStoredSshWorktreesForResolution(repo: Repo): GitWorktreeInfo[] { const store = this.store if (!store) { return [] } const byWorktreeId = new Map() for (const [worktreeId, meta] of Object.entries(store.getAllWorktreeMeta())) { const parsed = splitWorktreeId(worktreeId) if (!parsed || parsed.repoId !== repo.id) { continue } // Why: this mirrors desktop worktrees:list's disconnected-SSH fallback. // Web clients should keep showing persisted SSH worktrees while the // provider is reconnecting instead of dropping the repo to zero rows. byWorktreeId.set(worktreeId, { path: parsed.worktreePath, head: '', branch: '', isBare: false, isMainWorktree: areWorktreePathsEqual(parsed.worktreePath, repo.path), ...(meta.sparseDirectories !== undefined || meta.sparseBaseRef !== undefined || meta.sparsePresetId !== undefined ? { isSparse: true } : {}) }) } return [...byWorktreeId.values()] } private async getResolvedWorktreeMap(): Promise> { return new Map((await this.listResolvedWorktrees()).map((worktree) => [worktree.id, worktree])) } private invalidateResolvedWorktreeCache(): void { this.resolvedWorktreeGeneration += 1 this.resolvedWorktreeCache = null } /** Invalidate the worktree cache and tell the renderer to re-list, after an * out-of-band branch change (e.g. auto-rename-from-work) so the new branch * name surfaces without waiting for the next ambient refresh. */ notifyBranchRenamed(repoId: string): void { this.invalidateResolvedWorktreeCache() this.notifyWorktreesChanged(repoId) } /** Like {@link notifyBranchRenamed}, but carries the old->new worktree id so the * renderer re-keys its worktree-scoped state instead of treating the id change * (from a folder rename) as a deletion. Same channel = guaranteed ordering. */ notifyWorktreeFolderRenamed(repoId: string, oldWorktreeId: string, newWorktreeId: string): void { this.invalidateResolvedWorktreeCache() this.notifier?.worktreesChanged(repoId, { oldWorktreeId, newWorktreeId }) // Mirror notifyBranchRenamed so in-process onClientEvent listeners also see the rename. this.emitClientEvent({ type: 'worktreesChanged', repoId }) } notifyFolderWorkspaceChanged(): void { this.invalidateResolvedWorktreeCache() this.notifyReposChanged() } private recordPtyWorktree( ptyId: string, worktreeId: string, state: Partial< Pick< RuntimePtyWorktreeRecord, 'connected' | 'lastOutputAt' | 'preview' | 'tabId' | 'paneKey' | 'title' | 'connectionId' > > = {} ): RuntimePtyWorktreeRecord { let pty = this.ptysById.get(ptyId) if (!pty) { const titleObservedAt = state.title ? this.nextTitleObservationSequence() : null pty = { ptyId, worktreeId, connectionId: state.connectionId ?? parseAppSshPtyId(ptyId)?.connectionId ?? null, tabId: state.tabId ?? null, paneKey: state.paneKey ?? null, launchConfig: null, launchToken: null, launchAgent: null, foregroundAgent: null, connected: state.connected ?? true, disconnectedAt: state.connected === false ? Date.now() : null, lastExitCode: null, lastAgentStatus: null, lastOscTitle: null, lastOscTitleAt: null, managementTitle: null, managementTitleAt: null, title: state.title ?? null, titleUpdatedAt: titleObservedAt, lastOutputAt: state.lastOutputAt ?? null, tailBuffer: [], tailPartialLine: '', tailPendingAnsi: '', tailRedrawCursor: null, tailTruncated: false, tailLinesTotal: 0, preview: state.preview ?? '', waitBlockedAt: null } if (state.title) { this.setPtyManagementTitleFromObservedTitle(pty, state.title, titleObservedAt ?? 0) } this.ptysById.set(ptyId, pty) // Why: restored/controller-discovered PTYs learn their worktree here // without registerPty(), so URL enrichment must bind at this source. advertisedUrlWatcher.bindPty(ptyId, worktreeId) serveSimStateWatcher.bindPty(ptyId, worktreeId) return pty } pty.worktreeId = worktreeId if (state.connectionId !== undefined) { pty.connectionId = state.connectionId } if (state.tabId !== undefined) { pty.tabId = state.tabId } if (state.paneKey !== undefined) { pty.paneKey = state.paneKey } if (state.connected !== undefined) { pty.connected = state.connected pty.disconnectedAt = state.connected ? null : (pty.disconnectedAt ?? Date.now()) } if (state.lastOutputAt !== undefined) { pty.lastOutputAt = maxTimestamp(pty.lastOutputAt, state.lastOutputAt) } if (state.preview !== undefined && state.preview.length > 0) { pty.preview = state.preview } if (state.title !== undefined && state.title !== null && state.title.length > 0) { const observedAt = this.nextTitleObservationSequence() pty.title = state.title pty.titleUpdatedAt = observedAt this.setPtyManagementTitleFromObservedTitle(pty, state.title, observedAt) } // Why: recordPtyWorktree is the common lifecycle point for every path that // resolves a PTY's worktree, including renderer restore and controller list. advertisedUrlWatcher.bindPty(ptyId, worktreeId) serveSimStateWatcher.bindPty(ptyId, worktreeId) return pty } private makeRuntimePaneKey( leaf: Pick ): string { return isTerminalLeafId(leaf.leafId) ? makePaneKey(leaf.tabId, leaf.leafId) : `${leaf.tabId}:${leaf.paneRuntimeId}` } private getOrCreatePtyWorktreeRecord(ptyId: string): RuntimePtyWorktreeRecord | null { const existing = this.ptysById.get(ptyId) if (existing) { return existing } const inferredWorktreeId = inferWorktreeIdFromPtyId(ptyId) if (!inferredWorktreeId) { return null } // Why: daemon-backed PTY session IDs are prefixed with the worktree ID so // mobile summaries survive renderer graph gaps and Electron reloads. return this.recordPtyWorktree(ptyId, inferredWorktreeId) } /** * Synchronizes PTY tracking records with the running daemon sessions, * querying their foreground agent states. */ private async refreshPtyWorktreeRecordsFromController( resolvedWorktrees: ResolvedWorktree[], targetWorktreeId: string | null = null ): Promise | null> { if (!this.ptyController?.listProcesses) { return null } const sessionsResult = await withTimeoutResult( this.ptyController.listProcesses(), PTY_CONTROLLER_LIST_TIMEOUT_MS ) if (!sessionsResult.ok) { // Why: a transient controller failure is not evidence that retained PTYs exited. return null } const sessions = sessionsResult.value const livePtyIds = new Set(sessions.map((session) => session.id)) for (const session of sessions) { const worktreeId = inferWorktreeIdFromPtyId(session.id) ?? findResolvedWorktreeIdForPath(resolvedWorktrees, session.cwd) if (targetWorktreeId && worktreeId !== targetWorktreeId) { continue } if (worktreeId) { this.recordPtyWorktree(session.id, worktreeId, { connected: true }) } // Why: fire-and-forget so this listing hot path (listTerminals/getWorktreePs) // does not serialize a relay round-trip per session — and a throwing snapshot // listener cannot abort the liveness sweep below. this.refreshPtyForegroundAgent(session.id) } for (const pty of this.ptysById.values()) { if (!livePtyIds.has(pty.ptyId) && !this.leafExistsForPty(pty.ptyId)) { pty.connected = false pty.disconnectedAt ??= Date.now() } } this.pruneDisconnectedPtyRecords() return livePtyIds } private pruneDisconnectedPtyTranscript(pty: RuntimePtyWorktreeRecord): void { if (pty.connected) { return } // Why: disconnected PTY records can stay addressable for status/exit reads, // but their retained transcripts must not accumulate after the process dies. pty.tailBuffer = [] pty.tailPartialLine = '' pty.tailPendingAnsi = '' pty.tailRedrawCursor = null pty.tailTruncated = false pty.tailLinesTotal = 0 pty.waitBlockedAt = null } private pruneDisconnectedPtyRecords(): void { const retained = [...this.ptysById.values()] .filter((pty) => !pty.connected && !this.leafExistsForPty(pty.ptyId)) .sort((a, b) => (a.disconnectedAt ?? 0) - (b.disconnectedAt ?? 0)) const staleCount = Math.max(0, retained.length - DISCONNECTED_PTY_RECORD_MAX) for (const stale of retained.slice(0, staleCount)) { // Why: exited runtime-owned PTYs stay readable after exit, but long-lived // runtimes can churn through many background sessions. Bound the archive. this.dropDisconnectedPtyRecord(stale.ptyId) } } private dropDisconnectedPtyRecord(ptyId: string): void { // Why: pruning can remove a PTY without the normal exit callback. serveSimStateWatcher.unbindPty(ptyId) this.ptysById.delete(ptyId) this.recentPtyOutputById.delete(ptyId) this.ptyOutputSequenceById.delete(ptyId) this.agentStatusOscProcessorsByPtyId.delete(ptyId) this.oscTitleScanTailByPtyId.delete(ptyId) this.clearAgentRowSnapshotsForPty(ptyId) const handle = this.handleByPtyId.get(ptyId) if (handle) { // Why: pruning can remove a PTY without onPtyExit firing; release any agent // team owned by this leader handle so it does not leak. this.claudeAgentTeams.removeTeamForLeaderHandle(handle) this.handleByPtyId.delete(ptyId) const record = this.handles.get(handle) if (record?.tabId.startsWith('pty:')) { this.handles.delete(handle) } } } private leafExistsForPty(ptyId: string): boolean { return (this.leavesByPtyId.get(ptyId)?.length ?? 0) > 0 } private rebuildLeafPtyIndex(): void { const next = new Map() for (const leaf of this.leaves.values()) { if (!leaf.ptyId) { continue } const leaves = next.get(leaf.ptyId) if (leaves) { leaves.push(leaf) } else { next.set(leaf.ptyId, [leaf]) } } this.leavesByPtyId = next } private getLeavesForPty(ptyId: string): RuntimeLeafRecord[] { return this.leavesByPtyId.get(ptyId) ?? [] } private getSummaryForRuntimeWorktreeId( summaries: Map, resolvedWorktrees: ResolvedWorktree[], runtimeWorktreeId: string ): RuntimeWorktreePsSummary | null { const exact = summaries.get(runtimeWorktreeId) if (exact) { return exact } const parsed = parseRuntimeWorktreeId(runtimeWorktreeId) if (!parsed) { return null } const resolved = resolvedWorktrees.find( (worktree) => worktree.repoId === parsed.repoId && areWorktreePathsEqual(worktree.path, parsed.worktreePath) ) return resolved ? (summaries.get(resolved.id) ?? null) : null } private buildTerminalSummary( leaf: RuntimeLeafRecord, worktreesById: Map ): RuntimeTerminalSummary { const worktree = worktreesById.get(leaf.worktreeId) const tab = this.tabs.get(leaf.tabId) ?? null return { handle: this.issueHandle(leaf), ptyId: leaf.ptyId, worktreeId: leaf.worktreeId, worktreePath: worktree?.path ?? '', branch: worktree?.branch ?? '', tabId: leaf.tabId, leafId: leaf.leafId, title: getLatestLeafTitle(leaf, tab?.title ?? null), connected: leaf.connected, writable: leaf.writable, lastOutputAt: leaf.lastOutputAt, preview: leaf.preview } } private syncMobileSessionTabs(snapshots: RuntimeMobileSessionTabsSnapshot[] | undefined): void { if (snapshots === undefined) { return } // Why: renderer graphs are authoritative for renderer tabs, but headless // serve terminals never enter that graph unless we preserve their bindings. this.hydrateHeadlessMobileSessionTabsFromWorkspaceSession(undefined, { allowAttachedWindow: true, onlyServeOwnedTerminals: true }) const nextWorktrees = new Set() for (const snapshot of snapshots) { nextWorktrees.add(snapshot.worktree) const existing = this.mobileSessionTabsByWorktree.get(snapshot.worktree) const nextSnapshot = this.mergePreservedHeadlessMobileSessionTabs(snapshot, existing) if ( !existing || nextSnapshot.publicationEpoch !== existing.publicationEpoch || nextSnapshot.snapshotVersion >= existing.snapshotVersion ) { this.mobileSessionTabsByWorktree.set(snapshot.worktree, nextSnapshot) } } for (const [worktreeId, existing] of [...this.mobileSessionTabsByWorktree.entries()]) { if (!nextWorktrees.has(worktreeId)) { const preserved = this.buildPreservedHeadlessMobileSessionSnapshot(existing) if (preserved) { this.mobileSessionTabsByWorktree.set(worktreeId, preserved) nextWorktrees.add(worktreeId) } else { this.mobileSessionTabsByWorktree.delete(worktreeId) this.notifyMobileSessionTabsRemoved(worktreeId) } } } } private mergePreservedHeadlessMobileSessionTabs( snapshot: RuntimeMobileSessionTabsSnapshot, existing: RuntimeMobileSessionTabsSnapshot | undefined ): RuntimeMobileSessionTabsSnapshot { if (!existing) { return snapshot } const preservedTabs = this.collectPreservedHeadlessMobileSessionTabs(existing, snapshot) if (preservedTabs.length === 0) { return snapshot } const hasIncomingActiveTab = snapshot.tabs.some((tab) => tab.isActive) const normalizedPreservedTabs = preservedTabs.map((tab) => hasIncomingActiveTab ? { ...tab, isActive: false } : tab ) const tabs = this.mergeMobileSessionSnapshotTabs(snapshot.tabs, normalizedPreservedTabs) if (tabs.length === snapshot.tabs.length) { return snapshot } const activeTab = snapshot.tabs.find((tab) => tab.id === snapshot.activeTabId) ?? tabs.find((tab) => tab.id === existing.activeTabId) ?? tabs.find((tab) => tab.isActive) ?? tabs[0] ?? null const terminalTabs = tabs.filter( (tab): tab is RuntimeMobileSessionTerminalTab => tab.type === 'terminal' ) return { ...snapshot, publicationEpoch: this.getMergedMobileSessionPublicationEpoch( snapshot, normalizedPreservedTabs ), snapshotVersion: Math.max(snapshot.snapshotVersion, existing.snapshotVersion), activeGroupId: snapshot.activeGroupId ?? existing.activeGroupId, activeTabId: activeTab?.id ?? null, activeTabType: activeTab?.type ?? null, tabGroups: this.mergeMobileSessionTabGroups( snapshot.worktree, snapshot.tabGroups ?? existing.tabGroups ?? [], terminalTabs, activeTab?.type === 'terminal' ? activeTab : null ), tabs } } private buildPreservedHeadlessMobileSessionSnapshot( existing: RuntimeMobileSessionTabsSnapshot ): RuntimeMobileSessionTabsSnapshot | null { const tabs = this.collectPreservedHeadlessMobileSessionTabs(existing) if (tabs.length === 0) { return null } const activeTab = tabs.find((tab) => tab.id === existing.activeTabId) ?? tabs.find((tab) => tab.isActive) ?? tabs[0] ?? null const terminalTabs = tabs.filter( (tab): tab is RuntimeMobileSessionTerminalTab => tab.type === 'terminal' ) return { ...existing, publicationEpoch: this.getMergedMobileSessionPublicationEpoch(existing, tabs), activeGroupId: existing.activeGroupId ?? this.getHeadlessMobileSessionGroupId(existing.worktree), activeTabId: activeTab?.id ?? null, activeTabType: activeTab?.type ?? null, tabGroups: this.mergeMobileSessionTabGroups( existing.worktree, existing.tabGroups ?? [], terminalTabs, activeTab?.type === 'terminal' ? activeTab : null ), tabs } } private collectPreservedHeadlessMobileSessionTabs( existing: RuntimeMobileSessionTabsSnapshot, incoming?: RuntimeMobileSessionTabsSnapshot ): RuntimeMobileSessionSnapshotTab[] { const incomingIds = new Set( incoming?.tabs.flatMap((tab) => this.getMobileSessionSnapshotTabIdentityKeys(tab)) ?? [] ) return existing.tabs.filter((tab) => { if (this.getMobileSessionSnapshotTabIdentityKeys(tab).some((id) => incomingIds.has(id))) { return false } return this.shouldPreserveHeadlessMobileSessionTab(existing, tab) }) } private shouldPreserveHeadlessMobileSessionTab( snapshot: RuntimeMobileSessionTabsSnapshot, tab: RuntimeMobileSessionSnapshotTab ): boolean { // Why: headless offscreen browser tabs live only on the server and are // re-derived from the live bridge on each hydrate, so a renderer-graph merge // must keep them rather than prune them as "not in the renderer graph". if (tab.type === 'browser') { return ( Boolean(this.offscreenBrowserBackend) && this.isHeadlessMobileSessionPublication(snapshot.publicationEpoch) ) } if (tab.type !== 'terminal') { return false } return ( this.isHeadlessMobileSessionPublication(snapshot.publicationEpoch) || this.hasServeOwnedPtyBinding(tab) ) } private isHeadlessMobileSessionPublication(publicationEpoch: string): boolean { return ( publicationEpoch.startsWith('headless:') || publicationEpoch.startsWith('headless-hydrated:') || publicationEpoch.includes(':headless-merge:') ) } private getMergedMobileSessionPublicationEpoch( snapshot: RuntimeMobileSessionTabsSnapshot, preservedTabs: readonly RuntimeMobileSessionSnapshotTab[] ): string { // Why: preserved snapshots can be merged repeatedly; normalize the prior // merge suffix before recomputing so the publication epoch is idempotent. const normalizedPublicationEpoch = snapshot.publicationEpoch.split(':headless-merge:')[0] const signature = createHash('sha1') .update( preservedTabs .map((tab) => tab.type === 'terminal' ? `${tab.id}:${tab.parentTabId}:${tab.ptyId ?? ''}:${tab.leafId}` : tab.id ) .join('|') ) .digest('hex') .slice(0, 12) return `${normalizedPublicationEpoch}:headless-merge:${signature}` } private notifyMobileSessionTabsRemoved(worktreeId: string): void { const removed: RuntimeMobileSessionTabsRemovedResult = { worktree: worktreeId, publicationEpoch: `removed:${Date.now().toString(36)}`, snapshotVersion: 0, removed: true, activeGroupId: null, activeTabId: null, activeTabType: null, tabs: [] } for (const listener of this.mobileSessionTabListeners) { listener(removed) } } notifyMobileSessionTabsChanged(worktreeId?: string): void { if (!worktreeId) { this.notifyMobileSessionTabSnapshots() return } if (this.mobileSessionTabListeners.size === 0) { return } const snapshot = this.mobileSessionTabsByWorktree.get(worktreeId) if (!snapshot) { return } // Why: browser bridge lifecycle events are already scoped by worktree; avoid // fanning out every active workspace snapshot during navigation/tab churn. const result = this.toMobileSessionTabsResult(snapshot) for (const listener of this.mobileSessionTabListeners) { listener(result) } } private notifyMobileSessionTabSnapshots(): void { if (this.mobileSessionTabListeners.size === 0) { return } for (const snapshot of this.mobileSessionTabsByWorktree.values()) { const result = this.toMobileSessionTabsResult(snapshot) for (const listener of this.mobileSessionTabListeners) { listener(result) } } } private getMobileSessionTabsForWorktree(worktreeId: string): RuntimeMobileSessionTabsResult { const snapshot = this.mobileSessionTabsByWorktree.get(worktreeId) if (!snapshot) { return { worktree: worktreeId, publicationEpoch: 'none', snapshotVersion: 0, activeGroupId: null, activeTabId: null, activeTabType: null, tabs: [] } } return this.toMobileSessionTabsResult(snapshot) } private async resolveMobileMarkdownWorktreeId( worktreeSelector: string, tabId: string ): Promise { const worktreeId = getExplicitWorktreeIdSelector(worktreeSelector) ?? (await this.resolveWorktreeSelector(worktreeSelector)).id const snapshot = this.mobileSessionTabsByWorktree.get(worktreeId) const tab = snapshot?.tabs.find( (candidate): candidate is RuntimeMobileSessionMarkdownTab => candidate.type === 'markdown' && candidate.id === tabId ) if (!tab) { throw new Error('tab_not_found') } return worktreeId } private getLiveBrowserTabsByPageId(worktreeId: string): Map { if (!this.agentBrowserBridge?.tabList) { return new Map() } const liveTabs = this.agentBrowserBridge.tabList(worktreeId).tabs return new Map(liveTabs.map((tab) => [tab.browserPageId, tab])) } private collectReturnedSessionTabIds( tabs: readonly RuntimeMobileSessionClientTab[] ): Set { const ids = new Set() for (const tab of tabs) { ids.add(tab.id) if (tab.type === 'terminal') { ids.add(tab.parentTabId) } else if (tab.type === 'browser') { ids.add(tab.browserWorkspaceId) } } return ids } private sanitizeMobileSessionTabGroups( groups: readonly RuntimeMobileSessionTabGroup[] | undefined, returnedTabs: readonly RuntimeMobileSessionClientTab[] ): RuntimeMobileSessionTabGroup[] | undefined { if (!groups || groups.length === 0) { return undefined } const returnedIds = this.collectReturnedSessionTabIds(returnedTabs) const sanitized = groups .map((group): RuntimeMobileSessionTabGroup | null => { const tabOrder = group.tabOrder.filter((tabId) => returnedIds.has(tabId)) if (tabOrder.length === 0) { return null } const activeTabId = group.activeTabId && tabOrder.includes(group.activeTabId) ? group.activeTabId : (tabOrder[0] ?? null) const recentTabIds = group.recentTabIds?.filter((tabId) => tabOrder.includes(tabId)) return { id: group.id, activeTabId, tabOrder, ...(recentTabIds && recentTabIds.length > 0 ? { recentTabIds } : {}) } }) .filter((group): group is RuntimeMobileSessionTabGroup => group !== null) return sanitized.length > 0 ? sanitized : undefined } private pruneMobileSessionTabGroupLayout( layout: TabGroupLayoutNode | null | undefined, validGroupIds: ReadonlySet ): TabGroupLayoutNode | null { if (!layout) { return null } if (layout.type === 'leaf') { return validGroupIds.has(layout.groupId) ? layout : null } const first = this.pruneMobileSessionTabGroupLayout(layout.first, validGroupIds) const second = this.pruneMobileSessionTabGroupLayout(layout.second, validGroupIds) if (first && second) { return { ...layout, first, second } } return first ?? second } /** * Transforms an internal mobile session tab snapshot into a sanitized client payload, * resolving launch agent ownership and normalizing titles. */ private toMobileSessionTabsResult( snapshot: RuntimeMobileSessionTabsSnapshot ): RuntimeMobileSessionTabsResult { const tabs: RuntimeMobileSessionClientTab[] = [] const liveBrowserTabsByPageId = this.getLiveBrowserTabsByPageId(snapshot.worktree) for (const tab of snapshot.tabs) { if (tab.type === 'browser') { const liveTab = tab.browserPageId ? liveBrowserTabsByPageId.get(tab.browserPageId) : undefined if (!liveTab) { continue } // Why: renderer session snapshots can lag behind BrowserView teardown or // process swaps. Pairing clients should only see browser pages the main // browser bridge can still route commands and screencasts to. tabs.push({ ...tab, title: liveTab.title || tab.title, url: liveTab.url || tab.url, // Why: bridge "active" means active BrowserView/webContents, not // active Orca tab. Preserve the renderer's app-level session focus. isActive: tab.isActive }) continue } if (tab.type === 'markdown' || tab.type === 'file') { tabs.push(tab) continue } const syncedTab = this.tabs.get(tab.parentTabId) const leaf = this.leaves.get(this.getLeafKey(tab.parentTabId, tab.leafId)) ?? null const liveLeaf = leaf?.ptyId && leaf.connected ? leaf : null const liveLeafPtyId = liveLeaf?.ptyId ?? null const liveLeafPty = liveLeafPtyId ? (this.ptysById.get(liveLeafPtyId) ?? null) : null const pty = liveLeaf ? null : this.findPtyForMobileTerminalTab(snapshot.worktree, tab, { allowWorktreeOnlyMatch: !snapshot.publicationEpoch.startsWith('headless') }) const livePty = pty?.connected ? pty : null const legacyPaneId = /^pane:(\d+)$/.exec(tab.leafId)?.[1] ?? null const paneKey = isTerminalLeafId(tab.leafId) ? makePaneKey(tab.parentTabId, tab.leafId) : `${tab.parentTabId}:${legacyPaneId ?? tab.leafId}` const leafTitle = leaf ? getLatestAgentCandidateTitle( { title: leaf.paneTitle, updatedAt: leaf.paneTitleUpdatedAt }, { title: leaf.lastOscTitle, updatedAt: leaf.lastOscTitleAt } ) : null const ptyTitle = pty ? getLatestAgentCandidateTitle( { title: pty.title, updatedAt: pty.titleUpdatedAt }, { title: pty.lastOscTitle, updatedAt: pty.lastOscTitleAt } ) : null const launchAgent = tab.launchAgent ?? liveLeafPty?.launchAgent ?? pty?.launchAgent ?? null const ownerAgent = launchAgent ?? liveLeafPty?.foregroundAgent ?? pty?.foregroundAgent ?? null const title = normalizeCompatibleAgentTitleForOwner( leafTitle ?? ptyTitle ?? syncedTab?.title ?? tab.title, ownerAgent ) const liveTitleEvidence = leafTitle ?? ptyTitle const liveTitleEvidenceClassification = classifyAgentTitle(liveTitleEvidence) const normalizedTabAgentStatus = tab.agentStatus ? normalizeCompatibleAgentStatusEntryForOwner(tab.agentStatus, ownerAgent) : null // Why: keep the rich hook-driven status when the agent has a live // interactive prompt or an active tool — those are authoritative agent // activity even if the terminal's title isn't agent-classified (e.g. it // shows a task/branch name). Otherwise the mobile/web client falls back to // the OSC-title-only status and never sees interactivePrompt (the question // card never renders). const hasLiveAgentSignal = normalizedTabAgentStatus?.interactivePrompt != null || normalizedTabAgentStatus?.toolName != null const keepFullAgentStatus = normalizedTabAgentStatus && (liveTitleEvidence === null || liveTitleEvidenceClassification === 'agent' || hasLiveAgentSignal) const agentStatus = keepFullAgentStatus ? { agentStatus: normalizedTabAgentStatus } : // Why: when live title evidence says the pane is idle (e.g. the Claude // agents picker or a neutral shell title), suppress the stale "working" // state so the client shows no spinner — but retain agent identity // (agentType + providerSession) so native chat can still address an // idle agent's transcript. Reset the transient state to 'done'. normalizedTabAgentStatus?.agentType != null ? { agentStatus: { state: 'done' as const, prompt: '', updatedAt: normalizedTabAgentStatus.updatedAt, stateStartedAt: normalizedTabAgentStatus.stateStartedAt, paneKey: normalizedTabAgentStatus.paneKey, stateHistory: [], agentType: normalizedTabAgentStatus.agentType, ...(normalizedTabAgentStatus.providerSession ? { providerSession: normalizedTabAgentStatus.providerSession } : {}) } } : null // Why: web/mobile clients hold these handles across renderer graph syncs; // leaf handles are graph-epoch-bound, but PTY handles remain streamable. const terminalHandle = liveLeafPtyId ? this.issuePtyHandle( this.recordPtyWorktree(liveLeafPtyId, snapshot.worktree, { tabId: tab.parentTabId, paneKey, connected: true }) ) : livePty ? this.issuePtyHandle(livePty) : null tabs.push({ type: 'terminal', id: tab.id, parentTabId: tab.parentTabId, leafId: tab.leafId, title, ...(tab.ptyId ? { ptyId: tab.ptyId } : {}), ...(tab.terminalTheme ? { terminalTheme: tab.terminalTheme } : {}), ...(launchAgent ? { launchAgent } : {}), ...(agentStatus ?? this.buildPtyMobileAgentStatus(livePty ?? pty, tab, terminalHandle)), ...(tab.parentLayout ? { parentLayout: tab.parentLayout } : {}), ...(tab.color != null ? { color: tab.color } : {}), ...(tab.isPinned ? { isPinned: true } : {}), ...(tab.viewMode ? { viewMode: tab.viewMode } : {}), isActive: tab.isActive, ...(terminalHandle ? { status: 'ready' as const, terminal: terminalHandle } : { status: 'pending-handle' as const, terminal: null }) }) } const active = tabs.find((tab) => tab.isActive && tab.id === snapshot.activeTabId) ?? tabs.find((tab) => tab.isActive) ?? (snapshot.activeTabId ? (tabs[0] ?? null) : null) const normalizedTabs = active && !tabs.some((tab) => tab.isActive) ? tabs.map((tab) => (tab.id === active.id ? { ...tab, isActive: true } : tab)) : tabs const tabGroups = this.sanitizeMobileSessionTabGroups(snapshot.tabGroups, normalizedTabs) const validGroupIds = new Set(tabGroups?.map((group) => group.id) ?? []) const tabGroupLayout = snapshot.tabGroupLayout === undefined ? undefined : this.pruneMobileSessionTabGroupLayout(snapshot.tabGroupLayout, validGroupIds) const activeGroupId = snapshot.activeGroupId && validGroupIds.has(snapshot.activeGroupId) ? snapshot.activeGroupId : (tabGroups?.find((group) => active ? group.tabOrder.some((tabId) => this.collectReturnedSessionTabIds([active]).has(tabId) ) : false )?.id ?? tabGroups?.[0]?.id ?? null) return { worktree: snapshot.worktree, publicationEpoch: snapshot.publicationEpoch, snapshotVersion: snapshot.snapshotVersion, activeGroupId, activeTabId: active?.id ?? null, activeTabType: active?.type ?? null, ...(tabGroups ? { tabGroups } : {}), ...(snapshot.tabGroupLayout !== undefined ? { tabGroupLayout } : {}), tabs: normalizedTabs } } /** * Generates a mobile-friendly status entry for a PTY, aligning agentType * and titles with the active owner. */ private buildPtyMobileAgentStatus( pty: RuntimePtyWorktreeRecord | null, tab: RuntimeMobileSessionTerminalTab, terminalHandle: string | null ): { agentStatus: AgentStatusEntry } | Record { if (!pty?.lastAgentStatus) { return {} } const ptyTitle = getLatestAgentCandidateTitle( { title: pty.title, updatedAt: pty.titleUpdatedAt }, { title: pty.lastOscTitle, updatedAt: pty.lastOscTitleAt } ) const ptyTitleClassification = classifyAgentTitle(ptyTitle) if (ptyTitle !== null && ptyTitleClassification !== 'agent') { return {} } const now = pty.lastOutputAt ?? Date.now() const ownerAgent = tab.launchAgent ?? pty.launchAgent ?? pty.foregroundAgent ?? null const agentType = ownerAgent ?? undefined return { agentStatus: { state: pty.lastAgentStatus === 'working' ? 'working' : pty.lastAgentStatus === 'permission' ? 'blocked' : 'done', prompt: '', updatedAt: now, stateStartedAt: now, paneKey: this.getMobileTerminalPaneKey(tab), ...(terminalHandle ? { terminalHandle } : {}), ...(agentType ? { agentType } : {}), worktreeId: pty.worktreeId, tabId: tab.parentTabId, terminalTitle: normalizeCompatibleAgentTitleForOwner( getLatestPtyTitle(pty) ?? tab.title, ownerAgent ), stateHistory: [] } } } private findPtyForMobileTerminalTab( worktreeId: string, tab: RuntimeMobileSessionTerminalTab, options: { allowWorktreeOnlyMatch?: boolean } = {} ): RuntimePtyWorktreeRecord | null { const snapshotPtyId = tab.ptyId ?? tab.parentLayout?.ptyIdsByLeafId?.[tab.leafId] ?? null const paneKey = this.getMobileTerminalPaneKey(tab) if (snapshotPtyId) { const pty = this.ptysById.get(snapshotPtyId) if (!pty) { return null } // Why: persisted PTY ids can collide with unrelated provider ids after a // restart. Only a matching spawn-time pane identity is safe to expose. if (this.mobileTerminalTabMatchesPty(worktreeId, tab, pty, paneKey)) { return pty } if ( options.allowWorktreeOnlyMatch === true && pty.worktreeId === worktreeId && pty.tabId === null && pty.paneKey === null ) { return pty } return null } const paneKeys = new Set([`${tab.parentTabId}:${tab.leafId}`]) if (tab.leafId === `pane:${FIRST_PANE_ID}`) { paneKeys.add(`${tab.parentTabId}:${FIRST_PANE_ID}`) } for (const pty of this.ptysById.values()) { if (pty.tabId === tab.parentTabId && pty.paneKey && paneKeys.has(pty.paneKey)) { return pty } } return null } private getPersistedSshPtyIdForMobileTerminalTab( tab: RuntimeMobileSessionTerminalTab ): string | null { const ptyId = tab.ptyId ?? tab.parentLayout?.ptyIdsByLeafId?.[tab.leafId] ?? null return ptyId && parseAppSshPtyId(ptyId) ? ptyId : null } private getMobileTerminalPaneKey(tab: RuntimeMobileSessionTerminalTab): string { if (isTerminalLeafId(tab.leafId)) { return makePaneKey(tab.parentTabId, tab.leafId) } const legacyPaneId = /^pane:(\d+)$/.exec(tab.leafId)?.[1] ?? null return `${tab.parentTabId}:${legacyPaneId ?? tab.leafId}` } private mobileTerminalTabMatchesPty( worktreeId: string, tab: RuntimeMobileSessionTerminalTab, pty: RuntimePtyWorktreeRecord, paneKey = this.getMobileTerminalPaneKey(tab) ): boolean { return pty.worktreeId === worktreeId && pty.tabId === tab.parentTabId && pty.paneKey === paneKey } // Why: group address resolution (Section 4.5) needs to query per-handle agent // status without throwing on stale handles, so this returns null on any error. getAgentStatusForHandle(handle: string): string | null { try { return this.getTerminalAgentStatusSnapshot(handle).titleStatus } catch { return null } } getAgentStatusOrchestrationContextForPaneKey( paneKey: string ): AgentStatusOrchestrationContext | undefined { const handle = this.getTerminalHandleForPaneKey(paneKey) if (!handle) { return undefined } return this.getAgentStatusOrchestrationContextForHandle(handle) } getAgentStatusTerminalHandleForPaneKey(paneKey: string): string | undefined { return this.getTerminalHandleForPaneKey(paneKey) ?? undefined } getAgentStatusLaunchConfigForPaneKey( paneKey: string, args?: { launchToken?: string } ): SleepingAgentLaunchConfig | undefined { const pty = this.getPtyRecordForPaneKey(paneKey) if (!pty?.launchConfig) { return undefined } if (pty.launchToken === null || pty.launchToken !== args?.launchToken) { return undefined } return copySleepingAgentLaunchConfig(pty.launchConfig) } private buildAgentOrchestrationByPaneKey(): | Record | undefined { const db = this.getOrchestrationDbIfAvailable() if (!db) { return undefined } const contexts: Record = {} for (const leaf of this.leaves.values()) { if (!leaf.ptyId) { continue } const handle = this.issueHandle(leaf) const context = this.getAgentStatusOrchestrationContextForHandle(handle, db) if (context) { contexts[this.makeRuntimePaneKey(leaf)] = context } } for (const pty of this.ptysById.values()) { if (!pty.paneKey || contexts[pty.paneKey]) { continue } const handle = this.issuePtyHandle(pty) const context = this.getAgentStatusOrchestrationContextForHandle(handle, db) if (context) { contexts[pty.paneKey] = context } } return Object.keys(contexts).length > 0 ? contexts : undefined } private getAgentStatusOrchestrationContextForHandle( handle: string, db = this.getOrchestrationDbIfAvailable() ): AgentStatusOrchestrationContext | undefined { // Why: active dispatches are authoritative for reused terminals. Completed // context is only useful while the corresponding done/recent row can still // be visible; after that it would stale-group unrelated future work. const dispatch = db?.getActiveDispatchForTerminal?.(handle) ?? this.getRecentCompletedDispatchForTerminal(handle, db) if (!dispatch) { return undefined } const task = db?.getTask?.(dispatch.task_id) const display = typeof task?.spec === 'string' ? buildOrchestrationTaskDisplayMetadata({ spec: task.spec, taskTitle: task.task_title, displayName: task.display_name }) : { taskTitle: '', displayName: '' } const activeRun = dispatch.status === 'completed' ? undefined : db?.getActiveCoordinatorRun?.() const parentTerminalHandle = task?.created_by_terminal_handle ?? (activeRun?.coordinator_handle && activeRun.coordinator_handle !== handle ? activeRun.coordinator_handle : undefined) const parentPaneKey = parentTerminalHandle ? this.getPaneKeyForTerminalHandle(parentTerminalHandle) : undefined return { taskId: dispatch.task_id, dispatchId: dispatch.id, ...(display.taskTitle ? { taskTitle: display.taskTitle } : {}), ...(display.displayName ? { displayName: display.displayName } : {}), ...(parentTerminalHandle ? { parentTerminalHandle } : {}), ...(parentPaneKey ? { parentPaneKey } : {}), ...(activeRun?.coordinator_handle ? { coordinatorHandle: activeRun.coordinator_handle } : {}), ...(activeRun?.id ? { orchestrationRunId: activeRun.id } : {}) } } private getRecentCompletedDispatchForTerminal( handle: string, db = this.getOrchestrationDbIfAvailable() ): ReturnType { const dispatch = db?.getLatestDispatchForTerminal?.(handle) if (dispatch?.status !== 'completed' || !dispatch.completed_at) { return undefined } const completedAtMs = Date.parse( dispatch.completed_at.includes('T') ? dispatch.completed_at : `${dispatch.completed_at.replace(' ', 'T')}Z` ) if (!Number.isFinite(completedAtMs)) { return undefined } return Date.now() - completedAtMs <= AGENT_STATUS_STALE_AFTER_MS ? dispatch : undefined } private getTerminalHandleForPaneKey(paneKey: string): string | null { const parsed = parsePaneKey(paneKey) if (parsed) { const leaf = this.leaves.get(this.getLeafKey(parsed.tabId, parsed.leafId)) if (leaf?.ptyId) { return this.issueHandle(leaf) } } for (const pty of this.ptysById.values()) { if (pty.paneKey === paneKey) { return this.issuePtyHandle(pty) } } return null } private getPtyRecordForPaneKey(paneKey: string): RuntimePtyWorktreeRecord | null { const parsed = parsePaneKey(paneKey) if (parsed) { const leaf = this.leaves.get(this.getLeafKey(parsed.tabId, parsed.leafId)) const pty = leaf?.ptyId ? this.ptysById.get(leaf.ptyId) : undefined if (pty) { return pty } } for (const pty of this.ptysById.values()) { if (pty.paneKey === paneKey) { return pty } } return null } private getPaneKeyForTerminalHandle(handle: string): string | null { const livePty = this.getLivePtyForHandle(handle) if (livePty?.pty.paneKey) { return livePty.pty.paneKey } const record = this.handles.get(handle) if (!record || record.runtimeId !== this.runtimeId) { return null } if (!isTerminalLeafId(record.leafId)) { return null } return makePaneKey(record.tabId, record.leafId) } private setPtyManagementTitleFromObservedTitle( pty: RuntimePtyWorktreeRecord, title: string | null | undefined, observedAt: number ): void { const trimmed = title?.trim() if (!trimmed) { return } if (isClaudeManagementTitle(trimmed)) { pty.managementTitle = trimmed pty.managementTitleAt = observedAt return } if ( detectAgentStatusFromTitle(trimmed) !== null && observedAt >= (pty.managementTitleAt ?? -1) ) { pty.managementTitle = null pty.managementTitleAt = null } } private nextTitleObservationSequence(): number { this.titleObservationSequence += 1 return this.titleObservationSequence } // Why: title detection is the tightest signal for agent presence, but a // Claude management title is negative evidence for task-capable activity. // Check pane-scoped titles before tab fallback, then retained ready-tail text, // stale title status, and foreground process. async isTerminalRunningAgent(handle: string): Promise { try { const pty = this.getLivePtyForHandle(handle) if (pty) { const leaf = this.getPrimaryLeafForPty(pty.pty.ptyId) return await this.isPtyRunningAgent(pty.pty, leaf) } const { leaf } = this.getLiveLeafForHandle(handle) // Why: check both the leaf-level pane title (synced from the renderer's // runtimePaneTitlesByTabId) and the tab-level title. The tab title already // includes OSC-enriched agent indicators (e.g. ✳ prefix) synced from the // renderer's xterm instance. const paneTitle = getLatestLeafTitle(leaf, null) const paneTitleClassification = classifyAgentTitle(paneTitle) if (paneTitleClassification === 'agent') { return true } const tabTitle = this.tabs.get(leaf.tabId)?.title?.trim() || null const tabTitleClassification = paneTitle === null ? classifyAgentTitle(tabTitle) : 'neutral' if (tabTitleClassification === 'agent') { return true } const waitText = buildTerminalWaitText(leaf.tailBuffer, leaf.tailPartialLine, leaf.preview) if (isKnownReadyPromptPreview(waitText)) { return true } const hasCurrentTitleEvidence = paneTitle !== null || tabTitle !== null if (leaf.lastAgentStatus !== null && !hasCurrentTitleEvidence) { return true } if (!leaf.ptyId || !this.ptyController) { return false } const fg = await this.ptyController.getForegroundProcess(leaf.ptyId) if (!fg) { return false } // Why: Claude's management UI runs under the Claude process but is not a // task-capable agent session. Suppress that process only; another foreground // agent can take over before titles update. const shouldSuppressClaudeForeground = paneTitleClassification === 'management' || tabTitleClassification === 'management' if (shouldSuppressClaudeForeground && isExpectedAgentProcess(fg, 'claude')) { return false } // Why: review-note delivery auto-submits with Enter. A generic non-shell // TUI can be focused in a terminal, but only known agent processes are safe. return await this.isRecognizedForegroundAgentProcess(leaf.ptyId, fg, { suppressClaude: shouldSuppressClaudeForeground }) } catch { return false } } private async isPtyRunningAgent( pty: RuntimePtyWorktreeRecord, leaf: RuntimeLeafRecord | null = null ): Promise { const leafTitle = leaf ? getLatestAgentCandidateTitle( { title: leaf.paneTitle, updatedAt: leaf.paneTitleUpdatedAt }, { title: leaf.lastOscTitle, updatedAt: leaf.lastOscTitleAt } ) : null const leafTitleClassification = classifyAgentTitle(leafTitle) if (leafTitleClassification === 'agent') { return true } const ptyTitle = getLatestAgentCandidateTitle( { title: pty.title, updatedAt: pty.titleUpdatedAt }, { title: pty.lastOscTitle, updatedAt: pty.lastOscTitleAt } ) const ptyTitleClassification = classifyAgentTitle(ptyTitle) if (leafTitle === null && ptyTitleClassification === 'agent') { return true } const managementTitleClassification = classifyLatestAgentTitle({ title: pty.managementTitle, updatedAt: pty.managementTitleAt }) const waitText = buildTerminalWaitText(pty.tailBuffer, pty.tailPartialLine, pty.preview) if (isKnownReadyPromptPreview(waitText)) { return true } // Why: stale status is only a fallback when no current title evidence // exists; neutral titles such as shells should clear it. if ( pty.lastAgentStatus !== null && leafTitle === null && ptyTitle === null && managementTitleClassification !== 'management' ) { return true } if (!this.ptyController) { return false } const fg = await this.ptyController.getForegroundProcess(pty.ptyId) if (!fg) { return false } const shouldSuppressClaudeForeground = leafTitle !== null ? leafTitleClassification === 'management' : managementTitleClassification === 'management' if (shouldSuppressClaudeForeground && isExpectedAgentProcess(fg, 'claude')) { return false } // Why: review-note delivery auto-submits with Enter. A generic non-shell // TUI can be focused in a terminal, but only known agent processes are safe. return await this.isRecognizedForegroundAgentProcess(pty.ptyId, fg, { suppressClaude: shouldSuppressClaudeForeground }) } private async isRecognizedForegroundAgentProcess( ptyId: string, foregroundProcess: string, options: { suppressClaude?: boolean } = {} ): Promise { const initialRecognition = recognizeAgentProcess(foregroundProcess) if (initialRecognition !== null) { return !( options.suppressClaude === true && isExpectedAgentProcess(initialRecognition.processName, 'claude') ) } if (!this.isAgentWrapperForegroundProcess(foregroundProcess) || !this.ptyController) { return false } const startedAt = Date.now() while (Date.now() - startedAt < FOREGROUND_AGENT_WRAPPER_RETRY_TIMEOUT_MS) { await new Promise((resolve) => setTimeout(resolve, FOREGROUND_AGENT_WRAPPER_RETRY_INTERVAL_MS) ) const refreshedProcess = await this.ptyController.getForegroundProcess(ptyId) const refreshedRecognition = recognizeAgentProcess(refreshedProcess) if (refreshedRecognition !== null) { return !( options.suppressClaude === true && isExpectedAgentProcess(refreshedRecognition.processName, 'claude') ) } if (!refreshedProcess || !this.isAgentWrapperForegroundProcess(refreshedProcess)) { return false } } return false } private isAgentWrapperForegroundProcess(processName: string): boolean { // Why: daemon/SSH PTYs can report the interpreter before their async // command-line cache resolves to the actual agent binary. Retry only // known wrappers, never arbitrary non-shell TUIs. return isAgentForegroundWrapperProcess(processName) } private getPrimaryLeafForPty(ptyId: string): RuntimeLeafRecord | null { return this.getLeavesForPty(ptyId)[0] ?? null } deliverPendingMessagesForHandle(handle: string): void { try { const { leaf } = this.getLiveLeafForHandle(handle) if (leaf.lastAgentStatus === 'idle') { this.deliverPendingMessages(leaf) } } catch { // Unknown or stale handles cannot be pushed immediately; the persisted // message remains available via explicit check or future idle delivery. } } // Why: after a message is inserted for a recipient, any blocking // orchestration.check --wait calls watching that handle must be woken // so they can return the new message immediately instead of polling. notifyMessageArrived(handle: string, messageType?: string): void { const waiters = this.messageWaitersByHandle.get(handle) if (!waiters || waiters.size === 0) { return } for (const waiter of [...waiters]) { // Why: a coordinator waiting for worker_done/escalation should not be // woken by worker heartbeat noise and mistake that empty read for idleness. if (messageType && waiter.typeFilter && !waiter.typeFilter.includes(messageType)) { continue } this.resolveMessageWaiter(waiter) } } waitForMessage( handle: string, options?: { typeFilter?: string[]; timeoutMs?: number; signal?: AbortSignal } ): Promise { return new Promise((resolve) => { const timeoutMs = options?.timeoutMs ?? MESSAGE_WAIT_DEFAULT_TIMEOUT_MS const waiter: MessageWaiter = { handle, typeFilter: options?.typeFilter, resolve, timeout: null, abortCleanup: null } // Why: if the caller aborts (socket closed on the RPC side — see design // doc §3.1 counter-lifecycle), resolve immediately so the long-poll slot // is released instead of counting down the full timeoutMs with a dead // client on the other end. const signal = options?.signal const onAbort = (): void => { this.removeMessageWaiter(waiter) resolve() } if (signal) { if (signal.aborted) { resolve() return } waiter.abortCleanup = () => signal.removeEventListener('abort', onAbort) signal.addEventListener('abort', onAbort, { once: true }) } waiter.timeout = setTimeout(() => { this.removeMessageWaiter(waiter) resolve() }, timeoutMs) let waiters = this.messageWaitersByHandle.get(handle) if (!waiters) { waiters = new Set() this.messageWaitersByHandle.set(handle, waiters) } waiters.add(waiter) }) } private resolveMessageWaiter(waiter: MessageWaiter): void { this.removeMessageWaiter(waiter) waiter.resolve() } private removeMessageWaiter(waiter: MessageWaiter): void { if (waiter.timeout) { clearTimeout(waiter.timeout) waiter.timeout = null } if (waiter.abortCleanup) { waiter.abortCleanup() waiter.abortCleanup = null } const waiters = this.messageWaitersByHandle.get(waiter.handle) if (waiters) { waiters.delete(waiter) if (waiters.size === 0) { this.messageWaitersByHandle.delete(waiter.handle) } } } private buildPtyTerminalSummary( pty: RuntimePtyWorktreeRecord, worktreesById: Map ): RuntimeTerminalSummary { const worktree = worktreesById.get(pty.worktreeId) return { handle: this.issuePtyHandle(pty), ptyId: pty.ptyId, worktreeId: pty.worktreeId, worktreePath: worktree?.path ?? '', branch: worktree?.branch ?? '', tabId: `pty:${pty.ptyId}`, leafId: `pty:${pty.ptyId}`, title: getLatestPtyTitle(pty), connected: pty.connected, writable: pty.connected, lastOutputAt: pty.lastOutputAt, preview: pty.preview } } private getLiveLeafForHandle(handle: string): { record: TerminalHandleRecord leaf: RuntimeLeafRecord } { this.assertGraphReady() const record = this.handles.get(handle) if (!record || record.runtimeId !== this.runtimeId) { throw new Error('terminal_handle_stale') } if (record.rendererGraphEpoch !== this.rendererGraphEpoch) { throw new Error('terminal_handle_stale') } const leaf = this.leaves.get(this.getLeafKey(record.tabId, record.leafId)) if (!leaf || leaf.ptyId !== record.ptyId || leaf.ptyGeneration !== record.ptyGeneration) { throw new Error('terminal_handle_stale') } return { record, leaf } } private getLivePtyForHandle(handle: string): { record: TerminalHandleRecord pty: RuntimePtyWorktreeRecord } | null { let record = this.handles.get(handle) if (!record) { const ptyId = [...this.handleByPtyId.entries()].find( ([, mappedHandle]) => mappedHandle === handle )?.[0] const pty = ptyId ? this.ptysById.get(ptyId) : null if (pty) { // Why: graph reload/unavailability clears renderer handle records, but // runtime-owned PTY handles remain the caller's control identity. this.issuePtyHandle(pty) record = this.handles.get(handle) } } if (!record || record.runtimeId !== this.runtimeId || !record.tabId.startsWith('pty:')) { return null } if (!record.ptyId) { return null } const pty = this.ptysById.get(record.ptyId) if (!pty || pty.ptyId !== record.ptyId) { return null } // Why: renderer adoption can race with CLI reads. If this synthetic PTY // handle is valid, keep ptyId -> handle populated so summaries do not mint // a second handle for the same terminal. this.handleByPtyId.set(record.ptyId, handle) return { record, pty } } private readPtyTerminal( handle: string, pty: RuntimePtyWorktreeRecord, opts: { cursor?: number; limit?: number } = {} ): RuntimeTerminalRead { return readTerminalTail({ handle, status: pty.connected ? 'running' : pty.lastExitCode !== null ? 'exited' : 'unknown', completedLines: pty.tailBuffer, partialLine: pty.tailPartialLine, completedLineCount: pty.tailLinesTotal, bufferTruncated: pty.tailTruncated, cursor: opts.cursor, limit: opts.limit }) } private issueHandle(leaf: RuntimeLeafRecord): string { const leafKey = this.getLeafKey(leaf.tabId, leaf.leafId) const existingHandle = this.handleByLeafKey.get(leafKey) if (existingHandle) { const existingRecord = this.handles.get(existingHandle) if ( existingRecord && existingRecord.rendererGraphEpoch === this.rendererGraphEpoch && existingRecord.ptyId === leaf.ptyId && existingRecord.ptyGeneration === leaf.ptyGeneration ) { return existingHandle } } const handle = this.adoptPreAllocatedHandle(leaf) ?? `term_${randomUUID()}` if (this.handles.has(handle)) { return handle } this.handles.set(handle, { handle, runtimeId: this.runtimeId, rendererGraphEpoch: this.rendererGraphEpoch, worktreeId: leaf.worktreeId, tabId: leaf.tabId, leafId: leaf.leafId, ptyId: leaf.ptyId, ptyGeneration: leaf.ptyGeneration }) this.handleByLeafKey.set(leafKey, handle) return handle } private adoptPreAllocatedHandle(leaf: RuntimeLeafRecord): string | null { if (!leaf.ptyId) { return null } const preAllocated = this.handleByPtyId.get(leaf.ptyId) if (!preAllocated) { return null } const leafKey = this.getLeafKey(leaf.tabId, leaf.leafId) this.handles.set(preAllocated, { handle: preAllocated, runtimeId: this.runtimeId, rendererGraphEpoch: this.rendererGraphEpoch, worktreeId: leaf.worktreeId, tabId: leaf.tabId, leafId: leaf.leafId, ptyId: leaf.ptyId, ptyGeneration: leaf.ptyGeneration }) this.handleByLeafKey.set(leafKey, preAllocated) return preAllocated } private issuePtyHandle(pty: RuntimePtyWorktreeRecord): string { const existingHandle = this.handleByPtyId.get(pty.ptyId) ?? this.findHandleForPtyRecord(pty.ptyId) if (existingHandle) { const existingRecord = this.handles.get(existingHandle) if ( existingRecord && existingRecord.runtimeId === this.runtimeId && existingRecord.ptyId === pty.ptyId ) { this.handleByPtyId.set(pty.ptyId, existingHandle) return existingHandle } } const handle = existingHandle ?? `term_${randomUUID()}` const syntheticId = `pty:${pty.ptyId}` this.handles.set(handle, { handle, runtimeId: this.runtimeId, rendererGraphEpoch: this.rendererGraphEpoch, worktreeId: pty.worktreeId, tabId: syntheticId, leafId: syntheticId, ptyId: pty.ptyId, ptyGeneration: 0 }) this.handleByPtyId.set(pty.ptyId, handle) return handle } private findHandleForPtyRecord(ptyId: string): string | null { for (const [handle, record] of this.handles) { if ( record.runtimeId === this.runtimeId && record.ptyId === ptyId && record.tabId.startsWith('pty:') ) { return handle } } return null } private refreshWritableFlags(): void { for (const leaf of this.leaves.values()) { leaf.writable = this.graphStatus === 'ready' && leaf.connected && leaf.ptyId !== null } } private invalidateLeafHandle(leafKey: string): void { const handle = this.handleByLeafKey.get(leafKey) if (!handle) { return } this.handleByLeafKey.delete(leafKey) this.handles.delete(handle) this.rejectWaitersForHandle(handle, 'terminal_handle_stale') } private rememberDetachedPreAllocatedLeaves(): void { for (const leaf of this.leaves.values()) { if (leaf.ptyId && this.handleByPtyId.has(leaf.ptyId)) { // Why: ORCA_TERMINAL_HANDLE is an agent identity, so CLI control should // survive renderer graph loss as long as the underlying PTY is alive. this.detachedPreAllocatedLeaves.set(leaf.ptyId, leaf) } } } private resolveExitWaiters(leaf: RuntimeLeafRecord): void { const handle = this.issueHandle(leaf) if (!handle) { return } const waiters = this.waitersByHandle.get(handle) if (!waiters || waiters.size === 0) { return } for (const waiter of [...waiters]) { if (waiter.condition === 'exit') { this.resolveWaiter(waiter, buildTerminalWaitResult(handle, 'exit', leaf)) } else { // Why: if the terminal exited, conditions like tui-idle can never be // satisfied. Reject immediately instead of letting the poll interval // spin until timeout on a dead process. this.removeWaiter(waiter) waiter.reject(new Error('terminal_exited')) } } } private resolveTuiIdleWaiters(leaf: RuntimeLeafRecord): void { const handle = this.handleByLeafKey.get(this.getLeafKey(leaf.tabId, leaf.leafId)) if (!handle) { return } const waiters = this.waitersByHandle.get(handle) if (!waiters || waiters.size === 0) { return } for (const waiter of [...waiters]) { if (waiter.condition === 'tui-idle') { this.resolveWaiter(waiter, buildTerminalWaitResult(handle, 'tui-idle', leaf)) } } } private resolvePtyExitWaiters(pty: RuntimePtyWorktreeRecord, ptyId: string): void { const handle = this.handleByPtyId.get(ptyId) if (!handle) { return } const waiters = this.waitersByHandle.get(handle) if (!waiters || waiters.size === 0) { return } for (const waiter of [...waiters]) { if (waiter.condition === 'exit') { this.resolveWaiter(waiter, buildPtyTerminalWaitResult(handle, 'exit', pty)) } else { this.removeWaiter(waiter) waiter.reject(new Error('terminal_exited')) } } } private resolvePtyTuiIdleWaiters(pty: RuntimePtyWorktreeRecord, ptyId: string): void { const handle = this.handleByPtyId.get(ptyId) if (!handle) { return } const waiters = this.waitersByHandle.get(handle) if (!waiters || waiters.size === 0) { return } for (const waiter of [...waiters]) { if (waiter.condition === 'tui-idle') { this.resolveWaiter(waiter, buildPtyTerminalWaitResult(handle, 'tui-idle', pty)) } } } // Why: OSC title detection via onPtyData is the primary signal for tui-idle, // but daemon-hosted terminals don't flow PTY data through the runtime, and // some agents don't emit recognized titles on startup. This fallback polls // two signals: (1) the renderer-synced tab title (reflects xterm's OSC title // handler, works even for daemon terminals), and (2) the PTY foreground process // + output quiescence. The poll self-cancels when the primary OSC path fires. private startTuiIdleFallbackPoll(waiter: TerminalWaiter, leaf: RuntimeLeafRecord): void { let foregroundPollInFlight = false waiter.pollInterval = setInterval(async () => { if (!waiter.pollInterval) { return } let startedForegroundPoll = false try { if (leaf.lastAgentStatus === 'idle') { if (waiter.pollInterval) { clearInterval(waiter.pollInterval) waiter.pollInterval = null } this.resolveWaiter(waiter, buildTerminalWaitResult(waiter.handle, 'tui-idle', leaf)) return } // Why: check the renderer-synced title. For daemon-hosted terminals, // this is the only path where OSC titles are visible to the runtime. const pollTitle = leaf.paneTitle ?? this.tabs.get(leaf.tabId)?.title if (pollTitle) { const titleStatus = detectExplicitIdleStatusFromTitle(pollTitle) if (titleStatus === 'idle') { if (waiter.pollInterval) { clearInterval(waiter.pollInterval) waiter.pollInterval = null } this.resolveWaiter(waiter, buildTerminalWaitResult(waiter.handle, 'tui-idle', leaf)) return } } const leafWaitText = buildTerminalWaitText( leaf.tailBuffer, leaf.tailPartialLine, leaf.preview ) const blockedReason = detectTerminalWaitBlockedReason(leafWaitText) if (blockedReason) { if (waiter.pollInterval) { clearInterval(waiter.pollInterval) waiter.pollInterval = null } this.resolveWaiter( waiter, buildTerminalWaitBlockedResult(waiter.handle, 'tui-idle', leaf, blockedReason) ) return } if (isKnownReadyPromptPreview(leafWaitText)) { if (waiter.pollInterval) { clearInterval(waiter.pollInterval) waiter.pollInterval = null } this.resolveWaiter(waiter, buildTerminalWaitResult(waiter.handle, 'tui-idle', leaf)) return } // Foreground process fallback: if the daemon/local provider can report // the process and it's a non-shell with quiet output, treat as idle. if ( leaf.lastAgentStatus === null && leaf.ptyId && this.ptyController && !foregroundPollInFlight ) { foregroundPollInFlight = true startedForegroundPoll = true const fg = await this.ptyController.getForegroundProcess(leaf.ptyId) if (fg && !isShellProcess(fg)) { const quietMs = leaf.lastOutputAt ? Date.now() - leaf.lastOutputAt : 0 if (quietMs >= TUI_IDLE_QUIESCENCE_MS) { if (waiter.pollInterval) { clearInterval(waiter.pollInterval) waiter.pollInterval = null } this.resolveWaiter(waiter, buildTerminalWaitResult(waiter.handle, 'tui-idle', leaf)) } } } } catch { // Swallow transient PTY inspection errors and keep polling. } finally { if (startedForegroundPoll) { foregroundPollInFlight = false } } }, TUI_IDLE_POLL_INTERVAL_MS) } private startPtyTuiIdleFallbackPoll(waiter: TerminalWaiter, pty: RuntimePtyWorktreeRecord): void { let foregroundPollInFlight = false waiter.pollInterval = setInterval(async () => { if (!waiter.pollInterval) { return } let startedForegroundPoll = false try { if (pty.lastAgentStatus === 'idle') { if (waiter.pollInterval) { clearInterval(waiter.pollInterval) waiter.pollInterval = null } this.resolveWaiter(waiter, buildPtyTerminalWaitResult(waiter.handle, 'tui-idle', pty)) return } const ptyWaitText = buildTerminalWaitText(pty.tailBuffer, pty.tailPartialLine, pty.preview) const blockedReason = detectTerminalWaitBlockedReason(ptyWaitText) if (blockedReason) { if (waiter.pollInterval) { clearInterval(waiter.pollInterval) waiter.pollInterval = null } this.resolveWaiter( waiter, buildPtyTerminalWaitBlockedResult(waiter.handle, 'tui-idle', pty, blockedReason) ) return } // Why: background PTY handles can later be adopted by the renderer. // Use that live xterm title as the same readiness signal as leaf handles. if ( this.getAdoptedPtyExplicitIdleStatus(pty) === 'idle' || isKnownReadyPromptPreview(ptyWaitText) ) { if (waiter.pollInterval) { clearInterval(waiter.pollInterval) waiter.pollInterval = null } this.resolveWaiter(waiter, buildPtyTerminalWaitResult(waiter.handle, 'tui-idle', pty)) return } if (pty.lastAgentStatus === null && this.ptyController && !foregroundPollInFlight) { foregroundPollInFlight = true startedForegroundPoll = true const fg = await this.ptyController.getForegroundProcess(pty.ptyId) if (fg && !isShellProcess(fg)) { const quietMs = pty.lastOutputAt ? Date.now() - pty.lastOutputAt : 0 if (quietMs >= TUI_IDLE_QUIESCENCE_MS) { if (waiter.pollInterval) { clearInterval(waiter.pollInterval) waiter.pollInterval = null } this.resolveWaiter(waiter, buildPtyTerminalWaitResult(waiter.handle, 'tui-idle', pty)) } } } } catch { // Swallow transient PTY inspection errors and keep polling. } finally { if (startedForegroundPoll) { foregroundPollInFlight = false } } }, TUI_IDLE_POLL_INTERVAL_MS) } private getAdoptedPtyExplicitIdleStatus(pty: RuntimePtyWorktreeRecord): AgentStatus | null { for (const leaf of this.leaves.values()) { if (leaf.ptyId !== pty.ptyId) { continue } const title = leaf.paneTitle ?? this.tabs.get(leaf.tabId)?.title if (!title) { continue } const status = detectExplicitIdleStatusFromTitle(title) if (status !== null) { return status } } return null } // Why: push-on-idle delivery — when an agent transitions working→idle, check // for unread orchestration messages addressed to that terminal and inject them // into the PTY. This is event-driven (no polling) because the runtime owns // both the message store and terminal status detection. private deliverPendingMessages(leaf: RuntimeLeafRecord): void { if (!this._orchestrationDb) { return } const handle = this.handleByLeafKey.get(this.getLeafKey(leaf.tabId, leaf.leafId)) if (!handle) { return } const unread = this._orchestrationDb.getUndeliveredUnreadMessages(handle) if (unread.length === 0) { return } if (!leaf.writable || !leaf.ptyId) { return } const payload = formatMessagesForInjection(unread) const wrote = this.ptyController?.write(leaf.ptyId, payload) ?? false if (!wrote) { return } const tabTitle = this.tabs.get(leaf.tabId)?.title if (isCursorAgentOrchestrationTarget(leaf, tabTitle)) { // Why: Cursor Agent treats injected PTY text as editable prompt input. // Push-on-idle may surface the message, but submitting it must stay // under user control. this._orchestrationDb.markAsDelivered(unread.map((m) => m.id)) return } // Why: Claude Code treats large single PTY writes as paste events and // swallows a \r included in the same write. Send Enter separately after // a delay so the agent processes the pasted message first. Stamp // `delivered_at` only after \r is confirmed, so failed deliveries stay // queued. // // Important (design doc §3.2, feedback #2): we stamp `delivered_at` here // instead of flipping `read`. `read` is reserved for "a check-caller // consumed this message." Flipping `read` on push-on-idle would hide the // message from the coordinator's next `check --unread`, which is the // exact bug feedback #2 reported. The two bits must stay independent. const ptyId = leaf.ptyId setTimeout(() => { try { if (!leaf.writable) { return } const submitted = this.ptyController?.write(ptyId, '\r') ?? false if (submitted) { this._orchestrationDb?.markAsDelivered(unread.map((m) => m.id)) } } catch { // Terminal may have closed during the delay — messages stay queued // (delivered_at still NULL) and will be re-delivered on the next // idle transition. } }, 500) } private resolveWaiter(waiter: TerminalWaiter, result: RuntimeTerminalWait): void { this.removeWaiter(waiter) waiter.resolve(result) } private bindTerminalWaiterAbort( waiter: TerminalWaiter, signal: AbortSignal | undefined ): boolean { if (!signal) { return true } if (signal.aborted) { return false } const onAbort = (): void => { this.removeWaiter(waiter) waiter.reject(new Error('request_aborted')) } waiter.abortCleanup = () => signal.removeEventListener('abort', onAbort) signal.addEventListener('abort', onAbort, { once: true }) return true } private rejectWaitersForHandle(handle: string, code: string): void { const waiters = this.waitersByHandle.get(handle) if (!waiters || waiters.size === 0) { return } for (const waiter of [...waiters]) { this.removeWaiter(waiter) waiter.reject(new Error(code)) } } private rejectAllWaiters(code: string): void { for (const handle of [...this.waitersByHandle.keys()]) { this.rejectWaitersForHandle(handle, code) } } private removeWaiter(waiter: TerminalWaiter): void { if (waiter.timeout) { clearTimeout(waiter.timeout) } if (waiter.pollInterval) { clearInterval(waiter.pollInterval) } if (waiter.abortCleanup) { waiter.abortCleanup() waiter.abortCleanup = null } const waiters = this.waitersByHandle.get(waiter.handle) if (!waiters) { return } waiters.delete(waiter) if (waiters.size === 0) { this.waitersByHandle.delete(waiter.handle) } } private getLeafKey(tabId: string, leafId: string): string { return `${tabId}::${leafId}` } // ── Linear integration ── linearConnect(apiKey: string): ReturnType { return connectLinear(apiKey) } linearDisconnect(workspaceId?: string): { ok: true } { disconnectLinear(workspaceId) return { ok: true } } linearSelectWorkspace(workspaceId: LinearWorkspaceSelection): ReturnType { return selectLinearWorkspace(workspaceId) } linearStatus(): ReturnType { return getLinearStatus() } linearTestConnection(workspaceId?: string): ReturnType { return testLinearConnection(workspaceId) } linearSearchIssues( query: string, limit = 20, workspaceId?: LinearWorkspaceSelection ): ReturnType { return searchLinearIssues(query, Math.min(Math.max(1, limit), 50), workspaceId) } linearSearchForAgents(args: { query: string limit?: number workspaceId?: string | 'all' }): ReturnType { return searchLinearIssuesForAgents(args) } linearIssueContext(request: LinearIssueRequest): ReturnType { return readLinearIssueContext(request, (context) => this.linearResolveCurrentIssue(context)) } async linearTeamListForAgents(params: { workspaceId?: string | 'all' }): Promise { try { const result = await listLinearTeamsForAgent(params.workspaceId) const workspaceErrors = result.errors.map((error) => ({ workspace: { id: error.workspaceId, name: error.workspaceName ?? error.workspaceId }, code: this.linearWorkspaceErrorCode(error.type), message: sanitizeLinearErrorMessage(error.message) })) return { teams: result.teams.map((team) => this.linearTeamSummary(team)), meta: { workspaceId: params.workspaceId, returned: result.teams.length, partial: workspaceErrors.length > 0, workspaceErrors } } } catch (error) { throw this.mapLinearReadFailure(error) } } async linearTeamMembersForAgents(params: { teamInput: string workspaceId?: string }): Promise { const team = await this.resolveLinearTeamInput(params.teamInput, params.workspaceId) try { const members = await getLinearTeamMembersOrThrow(team.id, team.workspaceId) return { team: this.linearTeamSummary(team), members: members.map((member) => ({ id: member.id, displayName: member.displayName, avatarUrl: member.avatarUrl })), meta: { workspaceId: team.workspaceId, returned: members.length } } } catch (error) { throw this.mapLinearReadFailure(error) } } async linearTeamStatesForAgents(params: { teamInput: string workspaceId?: string }): Promise { const team = await this.resolveLinearTeamInput(params.teamInput, params.workspaceId) const states = await this.getLinearTeamStatesForWrite(team.id, team.workspaceId) return { team: this.linearTeamSummary(team), states: states.map((state) => ({ id: state.id, name: state.name, type: state.type, color: state.color, position: state.position })), meta: { workspaceId: team.workspaceId, returned: states.length } } } async linearTeamLabelsForAgents(params: { teamInput: string workspaceId?: string }): Promise { const team = await this.resolveLinearTeamInput(params.teamInput, params.workspaceId) const labels = await this.getLinearTeamLabelsForWrite(team.id, team.workspaceId) return { team: this.linearTeamSummary(team), labels: labels.map((label) => ({ id: label.id, name: label.name, color: label.color })), meta: { workspaceId: team.workspaceId, returned: labels.length } } } async linearProjectListForAgents(params: { query?: string limit?: number workspaceId?: string | 'all' }): Promise { const limit = clampLinearSearchLimit(params.limit) try { const result = await this.linearListProjects(params.query, limit, params.workspaceId, true) const projects = result.items.slice(0, limit).map((project) => ({ id: project.id, name: project.name, ...(project.url ? { url: project.url } : {}), ...(project.workspaceId ? { workspaceId: project.workspaceId } : {}), ...(project.workspaceName ? { workspaceName: project.workspaceName } : {}), ...(project.teams ? { teams: project.teams } : {}) })) const workspaceErrors = (result.errors ?? []).map((error) => ({ workspace: { id: error.workspaceId, name: error.workspaceName ?? error.workspaceId }, code: this.linearWorkspaceErrorCode(error.type), message: sanitizeLinearErrorMessage(error.message) })) return { projects, meta: { query: params.query, workspaceId: params.workspaceId, limit, returned: projects.length, hasMore: result.hasMore === true || result.items.length > limit, partial: workspaceErrors.length > 0, workspaceErrors } } } catch (error) { throw this.mapLinearReadFailure(error) } } async linearIssueListForAgents(params: { filter?: LinearIssueListFilter teamInput?: string limit?: number workspaceId?: string | 'all' }): Promise { const filter = params.filter ?? 'assigned' const limit = clampLinearIssueListLimit(params.limit) const team = params.teamInput ? await this.resolveLinearTeamInput(params.teamInput, params.workspaceId) : null const workspaceId = team?.workspaceId ?? params.workspaceId try { const result = await listLinearIssues(filter, limit, workspaceId, team?.id) return { issues: result.items.map((issue) => ({ id: issue.id, identifier: issue.identifier, title: issue.title, url: issue.url, state: issue.state, team: issue.team, project: issue.project ?? null, assignee: issue.assignee ?? null, priority: issue.priority, estimate: issue.estimate, dueDate: issue.dueDate, updatedAt: issue.updatedAt, workspace: { id: issue.workspaceId ?? workspaceId ?? '', name: issue.workspaceName ?? issue.workspaceId ?? workspaceId ?? '' } })), meta: { filter, workspaceId, ...(team ? { team: this.linearTeamSummary(team) } : {}), limit, returned: result.items.length, hasMore: result.hasMore === true, partial: (result.errors?.length ?? 0) > 0, workspaceErrors: (result.errors ?? []).map((error) => ({ workspace: { id: error.workspaceId, name: error.workspaceName ?? error.workspaceId }, code: this.linearWorkspaceErrorCode(error.type), message: sanitizeLinearErrorMessage(error.message) })) } } } catch (error) { throw this.mapLinearReadFailure(error) } } async linearResolveCurrentIssue( context?: LinearCurrentIssueContextHints ): Promise> { if (!this.store) { throw new Error('runtime_unavailable') } let worktree: ResolvedWorktree | null = null if (context?.terminalHandle) { try { const terminal = await this.showTerminal(context.terminalHandle) if (context.worktreeId && context.worktreeId !== terminal.worktreeId) { throw new LinearAgentAccessError( 'linear_permission_denied', 'The provided Linear worktree context does not match the caller terminal.' ) } worktree = await this.resolveWorktreeSelector(`id:${terminal.worktreeId}`) } catch (error) { if (error instanceof LinearAgentAccessError) { throw error } if (context.remote === true || context.worktreeId) { throw new LinearAgentAccessError( 'linear_issue_required', 'Could not verify the current Linear-linked worktree.' ) } } } if (!worktree && context?.remote !== true && context?.cwd) { worktree = await this.resolveWorktreeForContainedPath(context.cwd) if (!worktree) { throw new LinearAgentAccessError( 'linear_issue_required', 'Run --current from inside an Orca-managed worktree or pass an issue id.' ) } } if (!worktree) { throw new LinearAgentAccessError( 'linear_issue_required', 'Run --current from inside an Orca-managed worktree or pass an issue id.' ) } const link = getLinearCurrentIssueFromWorktree(worktree) if (!link.workspaceId) { const backfill = resolveLegacyLinearLinkWorkspace( worktree.linkedLinearIssue ?? '', worktree.linkedLinearIssueOrganizationUrlKey ) if (backfill?.workspaceId) { this.store.setWorktreeMeta(worktree.id, { linkedLinearIssueWorkspaceId: backfill.workspaceId, linkedLinearIssueOrganizationUrlKey: backfill.organizationUrlKey ?? null }) return { ...link, workspaceId: backfill.workspaceId, organizationUrlKey: backfill.organizationUrlKey ?? link.organizationUrlKey, backfill } } } return link } private async resolveWorktreeForContainedPath(cwd: string): Promise { const currentPath = resolve(cwd) let best: ResolvedWorktree | null = null for (const candidate of await this.listResolvedWorktrees()) { if (!isPathInsideOrEqual(candidate.path, currentPath)) { continue } if (!best || candidate.path.length > best.path.length) { best = candidate } } return best } linearListIssues( filter?: LinearListFilter, limit = 20, workspaceId?: LinearWorkspaceSelection, teamId?: string ): ReturnType { return listLinearIssues(filter, clampLinearIssueListLimit(limit), workspaceId, teamId) } linearCreateIssue( teamId: string, title: string, description?: string, workspaceId?: string, parentIssueId?: string, projectId?: string | null, options?: { stateId?: string priority?: number estimate?: number | null dueDate?: string | null assigneeId?: string | null labelIds?: string[] } ): ReturnType { return createLinearIssue(teamId, title, description, workspaceId, { parentId: parentIssueId, projectId, ...options }) } linearGetIssue(id: string, workspaceId?: string): ReturnType { return getLinearIssue(id, workspaceId) } linearUpdateIssue( id: string, updates: LinearIssueUpdate, workspaceId?: string ): ReturnType { return updateLinearIssue(id, updates, workspaceId) } linearAddIssueComment( issueId: string, body: string, workspaceId?: string ): ReturnType { return addLinearIssueComment(issueId, body, workspaceId) } async linearIssueSetState(params: { input?: string current?: boolean workspaceId?: string to: string context?: LinearCurrentIssueContextHints }): Promise { const target = await this.resolveLinearAgentWriteTarget(params) const teamId = target.issue.team?.id if (!teamId) { throw linearError('linear_invalid_state', 'The Linear issue does not have a team.') } const states = await this.getLinearTeamStatesForWrite(teamId, target.workspaceId) const state = this.resolveLinearAgentState(params.to, states) if (!state) { throw linearError( 'linear_invalid_state', `No workflow state exactly matched "${params.to}".`, { states: states.map(({ id, name, type }) => ({ id, name, type })), nextSteps: [`Retry with one of the exact state names for ${target.issue.identifier}.`] } ) } const previousState = target.issue.state?.id && target.issue.state.name ? { id: target.issue.state.id, name: target.issue.state.name } : null const alreadyInState = target.issue.state?.id === state.id if (!alreadyInState) { await this.runLinearAgentWrite( async (signal) => { const updated = await updateLinearIssueForAgent( target.issue.id, { stateId: state.id }, target.workspaceId, { signal } ) if (updated.state?.id !== state.id) { throw new LinearWriteFailure( 'unconfirmed', 'Linear state update could not be confirmed.' ) } return updated }, (cause) => linearError( 'linear_write_unconfirmed', 'Linear may have applied the state change, but Orca could not confirm it.', { nextSteps: [ `Run \`orca linear issue ${target.issue.identifier} --workspace ${target.workspaceId} --json\` and check the current state before retrying.` ], ...(cause ? { cause } : {}) } ) ) } await this.notifyLinearLinkedIssueUpdated(target.workspaceId, target.issue.identifier) return { issue: this.linearWriteIssueRef(target.issue), state: { id: state.id, name: state.name, type: state.type }, previousState, meta: { workspaceId: target.workspaceId, alreadyInState } } } async linearIssueUpdateTask( params: LinearIssueTaskUpdateRequest ): Promise { const target = await this.resolveLinearAgentWriteTarget(params) const current = await this.readLinearAgentIssueWriteRecord(target.issue.id, target.workspaceId) const update = await this.buildLinearTaskUpdate(params, current, target.workspaceId) if (!update) { throw linearError('linear_write_failed', 'No Linear task field update was requested.') } const alreadySet = this.linearTaskFieldAlreadySet(params.operation, current, update) if (!alreadySet) { await this.runLinearAgentWrite( async (signal) => { const updated = await updateLinearIssueForAgent( target.issue.id, update.fields, target.workspaceId, { signal } ) if (!this.linearTaskFieldAlreadySet(params.operation, updated, update)) { throw new LinearWriteFailure( 'unconfirmed', 'Linear task field update could not be confirmed.' ) } return updated }, (cause) => linearError( 'linear_write_unconfirmed', 'Linear may have applied the task update, but Orca could not confirm it.', { nextSteps: [ `Run \`orca linear issue ${target.issue.identifier} --workspace ${target.workspaceId} --json\` and check the updated field before retrying.` ], ...(cause ? { cause } : {}) } ) ) } await this.notifyLinearLinkedIssueUpdated(target.workspaceId, target.issue.identifier) const finalRecord = alreadySet ? current : await this.readLinearAgentIssueWriteRecord(target.issue.id, target.workspaceId) return this.linearTaskUpdateResult( params.operation, target.issue, target.workspaceId, current, finalRecord, alreadySet ) } async linearIssueAddComment(params: { input?: string current?: boolean workspaceId?: string body: string replyTo?: string writeId?: string context?: LinearCurrentIssueContextHints }): Promise { if (params.body.length > LINEAR_WRITE_BODY_CAP) { throw linearError('linear_body_too_large', 'Linear comment body is too large.') } const target = await this.resolveLinearAgentWriteTarget(params) const parentId = params.replyTo ? await this.resolveLinearCommentParentId(target.issue.id, params.replyTo, target.workspaceId) : null const writeId = params.writeId ?? randomUUID() const existing = params.writeId !== undefined ? await this.getMatchingLinearCommentWrite( writeId, target.issue.id, parentId, target.workspaceId, true ) : null if (existing) { await this.notifyLinearLinkedIssueUpdated(target.workspaceId, target.issue.identifier) return this.linearCommentResult(existing, target, params.body.length, writeId, true) } try { const comment = await this.runLinearAgentWrite( (signal) => addLinearIssueCommentForAgent(target.issue.id, params.body, target.workspaceId, { id: writeId, parentId, signal }), (cause) => this.linearCreateStyleUnconfirmed('comment', writeId, target, { parentId, bodyRequired: true, cause }) ) await this.notifyLinearLinkedIssueUpdated(target.workspaceId, target.issue.identifier) return this.linearCommentResult(comment, target, params.body.length, writeId, false) } catch (error) { if (error instanceof LinearWriteFailure && error.kind === 'duplicate_id') { const comment = await this.refetchLinearCommentAfterDuplicate( writeId, target.issue.id, parentId, target.workspaceId, () => this.linearCreateStyleUnconfirmed('comment', writeId, target, { parentId, bodyRequired: true }) ) await this.notifyLinearLinkedIssueUpdated(target.workspaceId, target.issue.identifier) return this.linearCommentResult(comment, target, params.body.length, writeId, true) } throw error } } async linearIssueAttachLink(params: { input?: string current?: boolean workspaceId?: string url: string title?: string writeId?: string context?: LinearCurrentIssueContextHints }): Promise { const url = this.parseLinearAttachmentUrl(params.url) const target = await this.resolveLinearAgentWriteTarget(params) const writeId = params.writeId ?? randomUUID() const title = params.title?.trim() || this.defaultLinearAttachmentTitle(url) const existing = params.writeId !== undefined ? await this.getMatchingLinearAttachmentWrite( writeId, target.issue.id, target.workspaceId, true ) : null if (existing) { await this.notifyLinearLinkedIssueUpdated(target.workspaceId, target.issue.identifier) return this.linearAttachResult(existing, target, writeId, true) } try { const attachment = await this.runLinearAgentWrite( (signal) => createLinearIssueAttachment( target.issue.id, { id: writeId, title, url: url.toString() }, target.workspaceId, { signal } ), (cause) => this.linearCreateStyleUnconfirmed('attach', writeId, target, { title, url: url.toString(), cause }) ) await this.notifyLinearLinkedIssueUpdated(target.workspaceId, target.issue.identifier) return this.linearAttachResult(attachment, target, writeId, false) } catch (error) { if (error instanceof LinearWriteFailure && error.kind === 'duplicate_id') { const attachment = await this.refetchLinearAttachmentAfterDuplicate( writeId, target.issue.id, target.workspaceId, () => this.linearCreateStyleUnconfirmed('attach', writeId, target, { title, url: url.toString() }) ) await this.notifyLinearLinkedIssueUpdated(target.workspaceId, target.issue.identifier) return this.linearAttachResult(attachment, target, writeId, true) } throw error } } async linearIssueCreate(params: { title: string body?: string teamInput?: string teamKey?: string state?: string assignee?: string priority?: number estimate?: number dueDate?: string labels?: string[] projectInput?: string parentInput?: string parentCurrent?: boolean workspaceId?: string writeId?: string context?: LinearCurrentIssueContextHints }): Promise { if ((params.body?.length ?? 0) > LINEAR_WRITE_BODY_CAP) { throw linearError('linear_body_too_large', 'Linear issue body is too large.') } const parent = params.parentInput || params.parentCurrent ? await this.resolveLinearAgentWriteTarget({ input: params.parentInput, current: params.parentCurrent, workspaceId: params.workspaceId, context: params.context }) : null if (parent && params.workspaceId && params.workspaceId !== parent.workspaceId) { throw linearError( 'linear_invalid_workspace', 'The parent issue belongs to a different workspace.' ) } const team = await this.resolveLinearCreateTeam( params.teamInput ?? params.teamKey, params.workspaceId, parent ) const createFields = await this.resolveLinearCreateFields(params, team) const parentId = parent?.issue.id ?? null const writeId = params.writeId ?? randomUUID() const existing = params.writeId !== undefined ? await this.getMatchingLinearCreatedIssue( writeId, team.id, parentId, team.workspaceId, true, createFields ) : null if (existing) { if (parent) { await this.notifyLinearLinkedIssueUpdated(parent.workspaceId, parent.issue.identifier) } return this.linearCreateResult(existing, team.workspaceId, writeId, true) } try { const issue = await this.runLinearAgentWrite( async (signal) => { const created = await createLinearIssueForAgent( team.id, params.title, params.body, team.workspaceId, { id: writeId, parentId, ...createFields, signal } ) if (!this.linearCreatedIssueMatchesIntent(created, createFields)) { throw new LinearWriteFailure( 'unconfirmed', 'Linear issue create could not be confirmed with the requested task fields.' ) } return created }, (cause) => this.linearCreateStyleUnconfirmed('create', writeId, null, { team, parent, title: params.title, bodyRequired: params.body !== undefined, createFields, cause }) ) if (parent) { await this.notifyLinearLinkedIssueUpdated(parent.workspaceId, parent.issue.identifier) } return this.linearCreateResult(issue, team.workspaceId, writeId, false) } catch (error) { if (error instanceof LinearWriteFailure && error.kind === 'duplicate_id') { const issue = await this.refetchLinearIssueAfterDuplicate( writeId, team.id, parentId, team.workspaceId, createFields, () => this.linearCreateStyleUnconfirmed('create', writeId, null, { team, parent, title: params.title, bodyRequired: params.body !== undefined, createFields }) ) if (parent) { await this.notifyLinearLinkedIssueUpdated(parent.workspaceId, parent.issue.identifier) } return this.linearCreateResult(issue, team.workspaceId, writeId, true) } throw error } } private async resolveLinearAgentWriteTarget(params: { input?: string current?: boolean workspaceId?: string context?: LinearCurrentIssueContextHints }): Promise { const result = await readLinearIssueContext( { input: params.input, current: params.current, workspaceId: params.workspaceId, include: { comments: false, children: false, attachments: false, relations: false }, depth: 0, context: params.context }, (context) => this.linearResolveCurrentIssue(context) ) return { issue: result.issue, workspaceId: result.meta.resolved.workspaceId } } private async getLinearTeamStatesForWrite( teamId: string, workspaceId: string ): Promise>> { try { return await getLinearTeamStatesOrThrow(teamId, workspaceId) } catch (error) { throw this.mapLinearReadFailure(error) } } private resolveLinearAgentState( input: string, states: Awaited> ): Awaited>[number] | null { const normalized = input.toLocaleLowerCase() return ( states.find( (state) => state.id.toLocaleLowerCase() === normalized || state.name.toLocaleLowerCase() === normalized ) ?? null ) } private async getLinearTeamLabelsForWrite( teamId: string, workspaceId: string ): Promise>> { try { return await getLinearTeamLabelsOrThrow(teamId, workspaceId) } catch (error) { throw this.mapLinearReadFailure(error) } } private async readLinearAgentIssueWriteRecord( issueId: string, workspaceId: string ): Promise>>> { const issue = await this.readLinearWriteLookup(() => getLinearIssueByUuidForAgent(issueId, workspaceId) ) if (!issue) { throw linearError('linear_issue_not_found', 'Linear issue was not found.') } return issue } private async buildLinearTaskUpdate( params: LinearIssueTaskUpdateRequest, current: NonNullable>>, workspaceId: string ): Promise<{ fields: { assigneeId?: string | null priority?: number estimate?: number | null dueDate?: string | null labelIds?: string[] } labels?: { id: string; name: string }[] } | null> { if (params.operation === 'assignee') { const assigneeId = params.assigneeMe ? (await this.getLinearViewerForWrite(workspaceId)).id : params.assigneeId if (assigneeId === undefined) { throw linearError('linear_invalid_assignee', 'Pass --me, --to-id, or clear assignee.') } return { fields: { assigneeId } } } if (params.operation === 'priority') { if (params.priority === undefined) { throw linearError('linear_write_failed', 'Missing priority value.') } return { fields: { priority: params.priority } } } if (params.operation === 'estimate') { if (params.estimate === undefined) { throw linearError('linear_write_failed', 'Missing estimate value.') } return { fields: { estimate: params.estimate } } } if (params.operation === 'dueDate') { if (params.dueDate === undefined) { throw linearError('linear_write_failed', 'Missing due date value.') } return { fields: { dueDate: params.dueDate } } } if (params.operation === 'labels') { const mode = params.labelMode const inputs = params.labels ?? [] if (!mode || inputs.length === 0) { throw linearError('linear_invalid_label', 'Pass at least one --label.') } const labels = await this.resolveLinearLabelsForIssue(current, inputs, workspaceId) const requestedIds = labels.map((label) => label.id) const existingIds = current.labelIds ?? current.labels?.map((label) => label.id) ?? [] const nextIds = mode === 'set' ? requestedIds : mode === 'add' ? Array.from(new Set([...existingIds, ...requestedIds])) : existingIds.filter((id) => !requestedIds.includes(id)) return { fields: { labelIds: nextIds }, labels: labelsForIds(nextIds, [...(current.labels ?? []), ...labels]) } } return null } private async resolveLinearCreateFields( params: { state?: string assignee?: string priority?: number estimate?: number dueDate?: string labels?: string[] projectInput?: string }, team: { id: string; workspaceId: string } ): Promise { const fields: LinearCreateFieldIntent = {} if (params.state) { const states = await this.getLinearTeamStatesForWrite(team.id, team.workspaceId) const state = this.resolveLinearAgentState(params.state, states) if (!state) { throw linearError( 'linear_invalid_state', `No workflow state exactly matched "${params.state}".`, { states: states.map(({ id, name, type }) => ({ id, name, type })) } ) } fields.stateId = state.id } if (params.assignee) { fields.assigneeId = params.assignee.toLocaleLowerCase() === 'me' ? (await this.getLinearViewerForWrite(team.workspaceId)).id : params.assignee } if (params.priority !== undefined) { fields.priority = params.priority } if (params.estimate !== undefined) { fields.estimate = params.estimate } if (params.dueDate !== undefined) { fields.dueDate = params.dueDate } if (params.labels && params.labels.length > 0) { const labels = await this.resolveLinearLabelsForTeam(team.id, params.labels, team.workspaceId) fields.labelIds = labels.map((label) => label.id) } if (params.projectInput) { const project = await this.resolveLinearCreateProject(params.projectInput, team) fields.projectId = project.id } return fields } private async resolveLinearCreateProject( input: string, team: { id: string; workspaceId: string } ): Promise { const trimmed = input.trim() if (!trimmed) { throw linearError('linear_invalid_project', 'Pass a non-empty Linear project id or name.') } const byId = isLinearUuid(trimmed) ? await this.readLinearProjectByIdForCreate(trimmed, team.workspaceId) : null if (byId) { await this.assertLinearProjectIncludesTeam(byId, team.id, team.workspaceId, trimmed) return byId } const searchCandidates = await this.readLinearProjectsForCreate(trimmed, team.workspaceId) const normalized = trimmed.toLowerCase() const idMatch = searchCandidates.find((project) => project.id.toLowerCase() === normalized) if (idMatch) { await this.assertLinearProjectIncludesTeam(idMatch, team.id, team.workspaceId, trimmed) return idMatch } const nameMatches = await this.readLinearProjectsByExactNameForCreate(trimmed, team.workspaceId) const compatibleNameMatches = await this.filterLinearProjectsForTeam( nameMatches, team.id, team.workspaceId ) if (compatibleNameMatches.length === 1) { return compatibleNameMatches[0] } if (compatibleNameMatches.length > 1) { throw linearError( 'linear_invalid_project', `Multiple Linear projects exactly matched "${trimmed}".`, { projects: compatibleNameMatches.map((project) => ({ id: project.id, name: project.name, teams: project.teams })), nextSteps: ['Run `orca linear project list --query --json` and retry by id.'] } ) } if (nameMatches.length > 0) { await this.assertLinearProjectIncludesTeam(nameMatches[0], team.id, team.workspaceId, trimmed) } throw linearError('linear_invalid_project', `No Linear project exactly matched "${trimmed}".`, { projects: searchCandidates.map((project) => ({ id: project.id, name: project.name, teams: project.teams })), nextSteps: ['Run `orca linear project list --query --json` and retry by id.'] }) } private async readLinearProjectByIdForCreate( id: string, workspaceId: string ): Promise { try { return await getLinearProject(id, workspaceId, true) } catch (error) { throw this.mapLinearReadFailure(error) } } private async readLinearProjectsForCreate( query: string, workspaceId: string ): Promise { try { return (await listLinearProjects(query, LINEAR_SEARCH_MAX_LIMIT, workspaceId, true)).items } catch (error) { throw this.mapLinearReadFailure(error) } } private async readLinearProjectsByExactNameForCreate( name: string, workspaceId: string ): Promise { try { return await listLinearProjectsByExactName(name, workspaceId, true) } catch (error) { throw this.mapLinearReadFailure(error) } } private async assertLinearProjectIncludesTeam( project: LinearProjectSummary, teamId: string, workspaceId: string, input: string ): Promise { if (this.linearProjectIncludesTeam(project, teamId)) { return } let teams: NonNullable = [] try { // Why: summary reads cap project teams, so large cross-team projects need // a paged membership check before we reject an otherwise valid create. teams = await listLinearProjectTeams(project.id, workspaceId, true) } catch (error) { throw this.mapLinearReadFailure(error) } if (teams.some((team) => team.id === teamId)) { return } throw linearError( 'linear_invalid_project', `Linear project "${input}" is not available to the target team.`, { project: { id: project.id, name: project.name, teams }, nextSteps: ['Choose a project that includes the create target team, then retry by id.'] } ) } private async filterLinearProjectsForTeam( projects: LinearProjectSummary[], teamId: string, workspaceId: string ): Promise { const compatible: LinearProjectSummary[] = [] for (const project of projects) { if (this.linearProjectIncludesTeam(project, teamId)) { compatible.push(project) continue } try { const teams = await listLinearProjectTeams(project.id, workspaceId, true) if (teams.some((team) => team.id === teamId)) { compatible.push({ ...project, teams }) } } catch (error) { throw this.mapLinearReadFailure(error) } } return compatible } private linearProjectIncludesTeam(project: LinearProjectSummary, teamId: string): boolean { return project.teams?.some((team) => team.id === teamId) === true } private async getLinearViewerForWrite( workspaceId: string ): Promise<{ id: string; displayName?: string | null; avatarUrl?: string | null }> { try { return await getLinearViewerForWorkspaceOrThrow(workspaceId) } catch (error) { throw this.mapLinearReadFailure(error) } } private async resolveLinearLabelsForIssue( issue: NonNullable>>, inputs: string[], workspaceId: string ): Promise<{ id: string; name: string }[]> { const labels = await this.getLinearTeamLabelsForWrite(issue.team.id, workspaceId) const resolved = inputs.map((input) => { const normalized = input.toLocaleLowerCase() const idMatch = labels.find((label) => label.id.toLocaleLowerCase() === normalized) if (idMatch) { return { id: idMatch.id, name: idMatch.name } } const nameMatches = labels.filter((label) => label.name.toLocaleLowerCase() === normalized) if (nameMatches.length === 1) { return { id: nameMatches[0].id, name: nameMatches[0].name } } throw linearError( 'linear_invalid_label', nameMatches.length === 0 ? `No label exactly matched "${input}".` : `Multiple labels exactly matched "${input}".`, { labels: labels.map((label) => ({ id: label.id, name: label.name })), nextSteps: ['Run `orca linear team labels --team --json` and retry by id.'] } ) }) return Array.from(new Map(resolved.map((label) => [label.id, label])).values()) } private async resolveLinearLabelsForTeam( teamId: string, inputs: string[], workspaceId: string ): Promise<{ id: string; name: string }[]> { const labels = await this.getLinearTeamLabelsForWrite(teamId, workspaceId) const resolved = inputs.map((input) => { const normalized = input.toLocaleLowerCase() const idMatch = labels.find((label) => label.id.toLocaleLowerCase() === normalized) if (idMatch) { return { id: idMatch.id, name: idMatch.name } } const nameMatches = labels.filter((label) => label.name.toLocaleLowerCase() === normalized) if (nameMatches.length === 1) { return { id: nameMatches[0].id, name: nameMatches[0].name } } throw linearError( 'linear_invalid_label', nameMatches.length === 0 ? `No label exactly matched "${input}".` : `Multiple labels exactly matched "${input}".`, { labels: labels.map((label) => ({ id: label.id, name: label.name })) } ) }) return Array.from(new Map(resolved.map((label) => [label.id, label])).values()) } private linearCreatedIssueMatchesIntent( issue: NonNullable>>, intent: LinearCreateFieldIntent ): boolean { if (intent.stateId !== undefined && issue.state?.id !== intent.stateId) { return false } if (intent.assigneeId !== undefined && (issue.assignee?.id ?? null) !== intent.assigneeId) { return false } if (intent.priority !== undefined && issue.priority !== intent.priority) { return false } if (intent.estimate !== undefined && (issue.estimate ?? null) !== intent.estimate) { return false } if (intent.dueDate !== undefined && (issue.dueDate ?? null) !== intent.dueDate) { return false } if (intent.projectId !== undefined && (issue.project?.id ?? null) !== intent.projectId) { return false } const issueLabelIds = issue.labelIds ?? issue.labels?.map((label) => label.id) ?? [] if (intent.labelIds !== undefined && !sameStringSet(issueLabelIds, intent.labelIds)) { return false } return true } private linearTaskFieldAlreadySet( operation: LinearIssueTaskUpdateRequest['operation'], record: NonNullable>>, update: { fields: { assigneeId?: string | null priority?: number estimate?: number | null dueDate?: string | null labelIds?: string[] } } ): boolean { if (operation === 'assignee') { return (record.assignee?.id ?? null) === update.fields.assigneeId } if (operation === 'priority') { return record.priority === update.fields.priority } if (operation === 'estimate') { return (record.estimate ?? null) === update.fields.estimate } if (operation === 'dueDate') { return (record.dueDate ?? null) === update.fields.dueDate } if (operation === 'labels') { const recordLabelIds = record.labelIds ?? record.labels?.map((label) => label.id) ?? [] return sameStringSet(recordLabelIds, update.fields.labelIds ?? []) } return false } private linearTaskUpdateResult( operation: LinearIssueTaskUpdateRequest['operation'], issue: LinearIssueSummary, workspaceId: string, previous: NonNullable>>, current: NonNullable>>, alreadySet: boolean ): LinearIssueTaskUpdateResult { return { issue: this.linearWriteIssueRef(issue), operation, previous: this.linearTaskResultFields(previous), current: this.linearTaskResultFields(current), meta: { workspaceId, alreadySet } } } private linearTaskResultFields( record: NonNullable>> ): LinearIssueTaskUpdateResult['current'] { return { assignee: record.assignee ?? null, priority: record.priority ?? null, estimate: record.estimate ?? null, dueDate: record.dueDate ?? null, labels: record.labels ?? [] } } private async resolveLinearCommentParentId( issueId: string, commentId: string, workspaceId: string ): Promise { try { const root = await getLinearIssueCommentThreadRoot(issueId, commentId, workspaceId) if (!root) { throw linearError( 'linear_invalid_parent', 'The reply target is not a comment on this issue.', { nextSteps: ['Run `orca linear issue --comments --json` to list valid comment ids.'] } ) } return root.id } catch (error) { if (error instanceof LinearAgentAccessError) { throw error } throw this.mapLinearReadFailure(error) } } private async runLinearAgentWrite( write: (signal: AbortSignal) => Promise, unconfirmed: (cause?: string) => LinearAgentAccessError ): Promise { const controller = new AbortController() const writePromise = write(controller.signal) writePromise.catch(() => undefined) let timer: ReturnType | null = null try { return await Promise.race([ writePromise, new Promise((_resolve, reject) => { timer = setTimeout(() => { controller.abort() reject( new LinearWriteFailure( 'unconfirmed', 'Linear write deadline elapsed before confirmation.' ) ) }, 25_000) }) ]) } catch (error) { if (error instanceof LinearWriteFailure && error.kind === 'duplicate_id') { throw error } if (error instanceof LinearWriteFailure && error.kind === 'unconfirmed') { throw unconfirmed(this.linearWriteFailureCauseMessage(error)) } if (error instanceof LinearWriteFailure && error.kind === 'network') { throw linearError('linear_network_error', sanitizeLinearErrorMessage(error.message)) } if (error instanceof LinearWriteFailure) { throw linearError('linear_write_failed', sanitizeLinearErrorMessage(error.message)) } throw this.mapLinearReadFailure(error) } finally { if (timer) { clearTimeout(timer) } } } private linearWriteFailureCauseMessage(error: LinearWriteFailure): string { if (error.cause instanceof Error) { return sanitizeLinearErrorMessage(error.cause.message) } if (error.cause !== undefined) { return sanitizeLinearErrorMessage(String(error.cause)) } return sanitizeLinearErrorMessage(error.message) } private mapLinearReadFailure(error: unknown): LinearAgentAccessError { if (error instanceof LinearAgentAccessError) { return error } if (isLinearAuthError(error)) { return linearError('linear_auth_expired', 'Linear authentication expired.', { nextSteps: ['Reconnect Linear from Orca settings.'] }) } return linearError(classifyLinearError(error), linearMessage(error)) } private async getMatchingLinearCommentWrite( writeId: string, issueId: string, parentId: string | null, workspaceId: string, required: boolean ): Promise> | null> { const comment = await this.readLinearWriteLookup(() => getLinearCommentByUuidForAgent(writeId, workspaceId) ) if (!comment) { return null } if (comment.issue.id === issueId && comment.parentId === parentId) { return comment } if (required) { throw linearError( 'linear_invalid_write_id', 'The write id belongs to a different comment target.' ) } return null } private async getMatchingLinearAttachmentWrite( writeId: string, issueId: string, workspaceId: string, required: boolean ): Promise> | null> { const attachment = await this.readLinearWriteLookup(() => getLinearAttachmentByUuidForAgent(writeId, workspaceId) ) if (!attachment) { return null } if (attachment.issue.id === issueId) { return attachment } if (required) { throw linearError( 'linear_invalid_write_id', 'The write id belongs to a different attachment target.' ) } return null } private async getMatchingLinearCreatedIssue( writeId: string, teamId: string, parentId: string | null, workspaceId: string, required: boolean, intent: LinearCreateFieldIntent = {} ): Promise> | null> { const issue = await this.readLinearWriteLookup(() => getLinearIssueByUuidForAgent(writeId, workspaceId) ) if (!issue) { return null } if ( issue.team.id === teamId && (issue.parent?.id ?? null) === parentId && this.linearCreatedIssueMatchesIntent(issue, intent) ) { return issue } if (required) { throw linearError( 'linear_invalid_write_id', 'The write id belongs to a different issue target.' ) } return null } private async refetchLinearCommentAfterDuplicate( writeId: string, issueId: string, parentId: string | null, workspaceId: string, unconfirmed: (cause?: string) => LinearAgentAccessError ): Promise>>> { try { // Why: a duplicate-id response can mean the original write landed; only // the exact target relationship proves this pinned retry. const comment = await this.getMatchingLinearCommentWrite( writeId, issueId, parentId, workspaceId, true ) if (comment) { return comment } } catch (error) { if (error instanceof LinearAgentAccessError && error.code === 'linear_invalid_write_id') { throw error } throw unconfirmed( error instanceof Error ? sanitizeLinearErrorMessage(error.message) : sanitizeLinearErrorMessage(String(error)) ) } throw unconfirmed() } private async refetchLinearAttachmentAfterDuplicate( writeId: string, issueId: string, workspaceId: string, unconfirmed: (cause?: string) => LinearAgentAccessError ): Promise>>> { try { // Why: a duplicate-id response can mean the original write landed; only // the exact target relationship proves this pinned retry. const attachment = await this.getMatchingLinearAttachmentWrite( writeId, issueId, workspaceId, true ) if (attachment) { return attachment } } catch (error) { if (error instanceof LinearAgentAccessError && error.code === 'linear_invalid_write_id') { throw error } throw unconfirmed( error instanceof Error ? sanitizeLinearErrorMessage(error.message) : sanitizeLinearErrorMessage(String(error)) ) } throw unconfirmed() } private async refetchLinearIssueAfterDuplicate( writeId: string, teamId: string, parentId: string | null, workspaceId: string, intent: LinearCreateFieldIntent, unconfirmed: (cause?: string) => LinearAgentAccessError ): Promise>>> { try { // Why: a duplicate-id response can mean the original write landed; only // the exact target relationship proves this pinned retry. const issue = await this.getMatchingLinearCreatedIssue( writeId, teamId, parentId, workspaceId, true, intent ) if (issue) { return issue } } catch (error) { if (error instanceof LinearAgentAccessError && error.code === 'linear_invalid_write_id') { throw error } throw unconfirmed( error instanceof Error ? sanitizeLinearErrorMessage(error.message) : sanitizeLinearErrorMessage(String(error)) ) } throw unconfirmed() } private async readLinearWriteLookup(lookup: () => Promise): Promise { try { return await lookup() } catch (error) { throw this.mapLinearReadFailure(error) } } private parseLinearAttachmentUrl(value: string): URL { try { const url = new URL(value) if (url.protocol === 'http:' || url.protocol === 'https:') { return url } } catch { // Fall through to the stable agent-facing error below. } throw linearError('linear_invalid_url', 'Attachment URL must be an absolute http(s) URL.') } private defaultLinearAttachmentTitle(url: URL): string { const tail = url.pathname.split('/').filter(Boolean).at(-1) return tail ? `${url.host}/${tail}` : url.host } private linearWorkspaceErrorCode(type: string): LinearErrorCode { if (type === 'auth') { return 'linear_auth_expired' } if (type === 'network') { return 'linear_network_error' } if (type === 'rate_limited') { return 'linear_rate_limited' } return 'linear_write_failed' } private linearTeamSummary(team: { id: string name: string key: string url?: string workspaceId?: string workspaceName?: string }): { id: string name: string key: string url?: string workspace?: { id: string; name: string } } { return { id: team.id, name: team.name, key: team.key, ...(team.url ? { url: team.url } : {}), ...(team.workspaceId ? { workspace: { id: team.workspaceId, name: team.workspaceName ?? team.workspaceId } } : {}) } } private async resolveLinearTeamInput( teamInput: string, workspaceId?: string | 'all' ): Promise<{ id: string key: string name: string workspaceId: string workspaceName?: string }> { this.validateLinearCreateWorkspaceScope(workspaceId === 'all' ? undefined : workspaceId) let teams: Awaited> try { teams = await listLinearTeamsOrThrow(workspaceId ?? 'all') } catch (error) { throw this.mapLinearReadFailure(error) } const normalized = teamInput.toLocaleLowerCase() const idMatches = teams.filter((team) => team.id.toLocaleLowerCase() === normalized) const matches = idMatches.length > 0 ? idMatches : teams.filter((team) => team.key.toLocaleLowerCase() === normalized) if (matches.length === 1 && matches[0].workspaceId) { return { id: matches[0].id, key: matches[0].key, name: matches[0].name, workspaceId: matches[0].workspaceId, workspaceName: matches[0].workspaceName } } if (matches.length > 1) { throw linearError( 'linear_workspace_ambiguous', `Team ${teamInput} exists in multiple workspaces.`, { candidates: matches.map((team) => ({ workspaceId: team.workspaceId, workspaceName: team.workspaceName, teamId: team.id, teamKey: team.key })) } ) } throw linearError('linear_team_required', `No connected Linear team matched ${teamInput}.`) } private async resolveLinearCreateTeam( teamInput: string | undefined, workspaceId: string | undefined, parent: LinearAgentWriteTarget | null ): Promise<{ id: string; key: string; name: string; workspaceId: string }> { if (!teamInput && parent?.issue.team?.id && parent.issue.team.key && parent.issue.team.name) { return { id: parent.issue.team.id, key: parent.issue.team.key, name: parent.issue.team.name, workspaceId: parent.workspaceId } } if (!teamInput) { throw linearError('linear_team_required', 'Pass --team or create under a parent issue.', { nextSteps: ['Run `orca linear create --team ...` or use --parent-current.'] }) } const scope = parent?.workspaceId ?? workspaceId this.validateLinearCreateWorkspaceScope(scope) let teams: Awaited> try { teams = await listLinearTeamsOrThrow(scope ?? 'all') } catch (error) { throw this.mapLinearReadFailure(error) } if (teams.length === 0 && (getLinearStatus().workspaces?.length ?? 0) === 0) { throw linearError('linear_not_connected', 'Linear is not connected.', { nextSteps: ['Connect Linear from Orca settings, then retry the issue create.'] }) } const matches = teams.filter( (team) => team.id.toLocaleLowerCase() === teamInput.toLocaleLowerCase() || team.key.toLocaleLowerCase() === teamInput.toLocaleLowerCase() ) if (matches.length === 1 && matches[0].workspaceId) { return { id: matches[0].id, key: matches[0].key, name: matches[0].name, workspaceId: matches[0].workspaceId } } if (matches.length > 1) { throw linearError( 'linear_workspace_ambiguous', `Team ${teamInput} exists in multiple workspaces.`, { candidates: matches.map((team) => ({ workspaceId: team.workspaceId, workspaceName: team.workspaceName, teamKey: team.key })) } ) } if (parent) { let globalTeams: Awaited> try { globalTeams = await listLinearTeamsOrThrow('all') } catch (error) { throw this.mapLinearReadFailure(error) } const globalMatch = globalTeams.find( (team) => team.id.toLocaleLowerCase() === teamInput.toLocaleLowerCase() || team.key.toLocaleLowerCase() === teamInput.toLocaleLowerCase() ) if (globalMatch) { throw linearError( 'linear_invalid_workspace', `Team ${teamInput} is not in the parent issue workspace.` ) } } throw linearError('linear_team_required', `No connected Linear team matched ${teamInput}.`) } private validateLinearCreateWorkspaceScope(workspaceId: string | undefined): void { if (!workspaceId) { return } const workspaces = getLinearStatus().workspaces ?? [] if (workspaces.length > 0 && !workspaces.some((workspace) => workspace.id === workspaceId)) { throw linearError( 'linear_invalid_workspace', `No connected Linear workspace matched ${workspaceId}.` ) } } private linearWriteIssueRef(issue: { id: string; identifier: string; url: string }): { id: string identifier: string url: string } { return { id: issue.id, identifier: issue.identifier, url: issue.url } } private linearCommentResult( comment: NonNullable>>, target: LinearAgentWriteTarget, bodyChars: number, writeId: string, deduplicated: boolean ): LinearCommentAddResult { return { comment: { id: comment.id, url: comment.url, parentId: comment.parentId }, issue: this.linearWriteIssueRef(target.issue), meta: { workspaceId: target.workspaceId, bodyChars, writeId, deduplicated } } } private linearAttachResult( attachment: NonNullable>>, target: LinearAgentWriteTarget, writeId: string, deduplicated: boolean ): LinearAttachResult { return { attachment: { id: attachment.id, title: attachment.title, url: attachment.url }, issue: this.linearWriteIssueRef(target.issue), meta: { workspaceId: target.workspaceId, writeId, deduplicated } } } private linearCreateResult( issue: NonNullable>>, workspaceId: string, writeId: string, deduplicated: boolean ): LinearCreateResult { return { issue, meta: { workspaceId, writeId, deduplicated } } } private linearCreateFieldRetryTokens(fields: LinearCreateFieldIntent | undefined): string[] { if (!fields) { return [] } return [ ...(fields.stateId ? [`--state=${this.commandToken(fields.stateId, 'STATE_ID')}`] : []), ...(fields.assigneeId ? [`--assignee=${this.commandToken(fields.assigneeId, 'ASSIGNEE_ID')}`] : []), ...(fields.priority !== undefined ? [`--priority=${this.linearPriorityRetryToken(fields.priority)}`] : []), ...(fields.estimate !== undefined && fields.estimate !== null ? [`--estimate=${fields.estimate}`] : []), ...(fields.dueDate ? [`--due-date=${fields.dueDate}`] : []), ...(fields.projectId ? [`--project=${this.commandToken(fields.projectId, 'PROJECT_ID')}`] : []), ...(fields.labelIds ?? []).map( (labelId) => `--label=${this.commandToken(labelId, 'LABEL_ID')}` ) ] } private linearPriorityRetryToken(priority: number): string { if (priority === 1) { return 'urgent' } if (priority === 2) { return 'high' } if (priority === 3) { return 'medium' } if (priority === 4) { return 'low' } return 'none' } private linearCreateStyleUnconfirmed( verb: 'comment' | 'attach' | 'create', writeId: string, target: LinearAgentWriteTarget | null, extra: { parentId?: string | null team?: { id: string; key: string; name: string; workspaceId: string } parent?: LinearAgentWriteTarget | null title?: string url?: string bodyRequired?: boolean createFields?: LinearCreateFieldIntent cause?: string } = {} ): LinearAgentAccessError { const workspaceId = target?.workspaceId ?? extra.team?.workspaceId ?? '' // Why: unconfirmed writes need a retry that preserves id and target so // duplicate recovery can prove intent without matching mutable content. const pinned = verb === 'create' ? [ 'orca linear create', `--workspace=${this.commandToken(workspaceId, 'WORKSPACE_ID')}`, `--write-id=${this.commandToken(writeId, 'WRITE_ID')}`, '--title TITLE_HERE', ...(extra.bodyRequired ? ['--body-file -'] : []), ...(extra.parent ? [`--parent=${this.commandToken(extra.parent.issue.identifier, 'PARENT_ISSUE')}`] : []), ...(extra.team ? [`--team=${this.commandToken(extra.team.key, 'TEAM_KEY')}`] : [] ).concat(this.linearCreateFieldRetryTokens(extra.createFields)) ].join(' ') : [ `orca linear ${verb === 'attach' ? 'attach' : 'comment add'}`, this.commandToken(target?.issue.identifier ?? '', 'ISSUE_ID'), `--workspace=${this.commandToken(workspaceId, 'WORKSPACE_ID')}`, `--write-id=${this.commandToken(writeId, 'WRITE_ID')}`, ...(verb === 'comment' ? ['--body-file -'] : []), ...(verb === 'comment' && extra.parentId ? [`--reply-to=${this.commandToken(extra.parentId, 'COMMENT_ID')}`] : []), ...(verb === 'attach' ? ['--url URL_HERE', '--title TITLE_HERE'] : []) ].join(' ') const retryPrefix = extra.bodyRequired || verb === 'comment' ? 'Pipe the same body and r' : 'R' const payloadNote = verb === 'attach' ? ' Replace TITLE_HERE/URL_HERE with the exact original payload values before running.' : verb === 'create' ? ' Replace TITLE_HERE with the exact original title before running.' : '' return linearError( 'linear_write_unconfirmed', 'Linear may have applied the write, but Orca could not confirm it.', { writeId, workspaceId, issueIdentifier: target?.issue.identifier, parentId: extra.parentId, team: extra.team ? { id: extra.team.id, key: extra.team.key } : undefined, parentIdentifier: extra.parent?.issue.identifier, createFields: extra.createFields, nextSteps: [ `${retryPrefix}etry once with the pinned command: \`${pinned}\`.${payloadNote}` ], ...(extra.cause ? { cause: sanitizeLinearErrorMessage(extra.cause) } : {}) } ) } private commandToken(value: string, placeholder: string): string { return /^[A-Za-z0-9._:@%+=,/-]+$/.test(value) ? value : placeholder } private async notifyLinearLinkedIssueUpdated( workspaceId: string, identifier: string ): Promise { const normalized = identifier.toLocaleUpperCase() for (const worktree of await this.listResolvedWorktrees()) { if ((worktree.linkedLinearIssue ?? '').toLocaleUpperCase() !== normalized) { continue } const linkedWorkspaceId = worktree.linkedLinearIssueWorkspaceId ?? workspaceId if (linkedWorkspaceId !== workspaceId) { continue } this.emitClientEvent({ type: 'linearLinkedIssueUpdated', worktreeId: worktree.id, identifier, workspaceId }) } } linearIssueComments( issueId: string, workspaceId?: string ): ReturnType { return getLinearIssueComments(issueId, workspaceId) } linearListTeams(workspaceId?: LinearWorkspaceSelection): ReturnType { return listLinearTeams(workspaceId) } linearListProjects( query?: string, limit = 20, workspaceId?: LinearWorkspaceSelection, force?: boolean ): ReturnType { return listLinearProjects(query, Math.min(Math.max(1, limit), 50), workspaceId, force) } linearCreateProject( input: LinearProjectCreateInput, workspaceId?: string ): ReturnType { return createLinearProject(input, workspaceId) } linearGetProject( id: string, workspaceId: string, force?: boolean ): ReturnType { return getLinearProject(id, workspaceId, force) } linearListProjectIssues( projectId: string, limit = 20, workspaceId: string, force?: boolean ): ReturnType { return listLinearProjectIssues(projectId, clampLinearIssueListLimit(limit), workspaceId, force) } linearListCustomViews( model: LinearCustomViewModel, limit = 20, workspaceId?: LinearWorkspaceSelection, force?: boolean ): ReturnType { return listLinearCustomViews(model, Math.min(Math.max(1, limit), 50), workspaceId, force) } linearGetCustomView( viewId: string, model: LinearCustomViewModel, workspaceId: string, force?: boolean ): ReturnType { return getLinearCustomView(viewId, model, workspaceId, force) } linearListCustomViewIssues( viewId: string, limit = 20, workspaceId: string, force?: boolean ): ReturnType { return listLinearCustomViewIssues(viewId, clampLinearIssueListLimit(limit), workspaceId, force) } linearListCustomViewProjects( viewId: string, limit = 20, workspaceId: string, force?: boolean ): ReturnType { return listLinearCustomViewProjects( viewId, Math.min(Math.max(1, limit), 50), workspaceId, force ) } linearTeamStates(teamId: string, workspaceId?: string): ReturnType { return getLinearTeamStates(teamId, workspaceId) } linearTeamLabels(teamId: string, workspaceId?: string): ReturnType { return getLinearTeamLabels(teamId, workspaceId) } linearTeamMembers(teamId: string, workspaceId?: string): ReturnType { return getLinearTeamMembers(teamId, workspaceId) } // ── Jira integration ── jiraConnect(args: JiraConnectArgs): ReturnType { return connectJira(args) } jiraDisconnect(siteId?: string): { ok: true } { disconnectJira(siteId) return { ok: true } } jiraSelectSite(siteId: JiraSiteSelection): ReturnType { return selectJiraSite(siteId) } jiraStatus(): ReturnType { return getJiraStatus() } jiraTestConnection(siteId?: string): ReturnType { return testJiraConnection(siteId) } jiraSearchIssues( jql: string, limit = 30, siteId?: JiraSiteSelection ): ReturnType { return searchJiraIssues(jql, Math.min(Math.max(1, limit), 100), siteId) } jiraListIssues( filter?: JiraIssueFilter, limit = 30, siteId?: JiraSiteSelection ): ReturnType { return listJiraIssues(filter, Math.min(Math.max(1, limit), 100), siteId) } jiraCreateIssue(args: JiraCreateIssueArgs): ReturnType { return createJiraIssue(args) } jiraGetIssue(key: string, siteId?: string): ReturnType { return getJiraIssue(key, siteId) } jiraUpdateIssue( key: string, updates: JiraIssueUpdate, siteId?: string ): ReturnType { return updateJiraIssue(key, updates, siteId) } jiraAddIssueComment( key: string, body: string, siteId?: string ): ReturnType { return addJiraIssueComment(key, body, siteId) } jiraIssueComments(key: string, siteId?: string): ReturnType { return getJiraIssueComments(key, siteId) } jiraListProjects(siteId?: JiraSiteSelection): ReturnType { return listJiraProjects(siteId) } jiraListIssueTypes( projectIdOrKey: string, siteId?: string ): ReturnType { return listJiraIssueTypes(projectIdOrKey, siteId) } jiraListCreateFields( projectIdOrKey: string, issueTypeId: string, siteId?: string ): ReturnType { return listJiraCreateFields(projectIdOrKey, issueTypeId, siteId) } jiraListPriorities(siteId?: string): ReturnType { return listJiraPriorities(siteId) } jiraListAssignableUsers( key: string, query?: string, siteId?: string ): ReturnType { return listJiraAssignableUsers(key, query, siteId) } jiraListTransitions(key: string, siteId?: string): ReturnType { return listJiraTransitions(key, siteId) } // ── Browser automation ── private readonly browserCommands = new RuntimeBrowserCommands({ getAgentBrowserBridge: () => this.agentBrowserBridge, resolveWorktreeSelector: (selector) => this.resolveWorktreeSelector(selector), getAuthoritativeWindow: () => this.getAuthoritativeWindow(), getAvailableAuthoritativeWindow: () => this.getAvailableAuthoritativeWindow(), getOffscreenBrowserBackend: () => this.offscreenBrowserBackend, // Why: bind the method directly rather than re-listing params in a wrapper // arrow — a hand-listed wrapper silently dropped targetGroupId before, so a // new browser opened in the right split group landed in the left. markHeadlessBrowserSessionTabActive: this.markHeadlessBrowserSessionTabActive.bind(this) }) private readonly emulatorCommands = new RuntimeEmulatorCommands({ getEmulatorBridge: () => this.emulatorBridge, resolveWorktreeSelector: (selector) => this.resolveWorktreeSelector(selector), getAuthoritativeWindow: () => this.getAuthoritativeWindow(), getSettings: () => this.requireStore().getSettings() }) browserSnapshot: RuntimeBrowserCommands['browserSnapshot'] = this.browserCommands.browserSnapshot.bind(this.browserCommands) browserClick: RuntimeBrowserCommands['browserClick'] = this.browserCommands.browserClick.bind( this.browserCommands ) browserGoto: RuntimeBrowserCommands['browserGoto'] = this.browserCommands.browserGoto.bind( this.browserCommands ) browserFill: RuntimeBrowserCommands['browserFill'] = this.browserCommands.browserFill.bind( this.browserCommands ) browserType: RuntimeBrowserCommands['browserType'] = this.browserCommands.browserType.bind( this.browserCommands ) browserSelect: RuntimeBrowserCommands['browserSelect'] = this.browserCommands.browserSelect.bind( this.browserCommands ) browserScroll: RuntimeBrowserCommands['browserScroll'] = this.browserCommands.browserScroll.bind( this.browserCommands ) browserBack: RuntimeBrowserCommands['browserBack'] = this.browserCommands.browserBack.bind( this.browserCommands ) browserReload: RuntimeBrowserCommands['browserReload'] = this.browserCommands.browserReload.bind( this.browserCommands ) browserScreenshot: RuntimeBrowserCommands['browserScreenshot'] = this.browserCommands.browserScreenshot.bind(this.browserCommands) async browserScreencast( params: Parameters[0], options: { connectionId?: string sendBinary?: (bytes: Uint8Array) => boolean | void signal?: AbortSignal emit: (result: BrowserScreencastResult) => void } ): Promise { if (!options.sendBinary) { throw new BrowserError( 'browser_error', 'Browser screencast requires a binary streaming transport.' ) } const connectionKey = options.connectionId ?? 'local' const requestedPageId = typeof params.page === 'string' ? params.page : null let existingPageStream = requestedPageId ? this.activeBrowserScreencastsByPage.get(requestedPageId) : undefined while (existingPageStream) { // Why: CDP only supports one screencast per browser page. A stale paired // web/mobile stream should not leave the next tab activation stuck on an // already-active error or old viewport dimensions. existingPageStream.cancel(existingPageStream.connectionKey !== connectionKey) await existingPageStream.done existingPageStream = requestedPageId ? this.activeBrowserScreencastsByPage.get(requestedPageId) : undefined } let existingStream = this.activeBrowserScreencastsByConnection.get(connectionKey) while (existingStream) { existingStream.cancel() await existingStream.done existingStream = this.activeBrowserScreencastsByConnection.get(connectionKey) } if (options.signal?.aborted) { throw new BrowserError('browser_error', 'Browser screencast was cancelled.') } let screencast: Awaited> | null = null let registeredSubscriptionId: string | null = null let activeBrowserPageId: string | null = null let ended = false let cancelledBeforeStart = false let readyEmitted = false let resolveActiveDone!: () => void const activeDone = new Promise((resolve) => { resolveActiveDone = resolve }) const end = (emitEnd: boolean): void => { if (ended) { return } ended = true screencast?.session.stop() if (emitEnd && screencast) { options.emit({ type: 'end', subscriptionId: screencast.subscriptionId }) } } const cancel = (emitEnd = false): void => { if (!screencast) { cancelledBeforeStart = true return } end(emitEnd) } const abortScreencast = (): void => cancel() const sendBinaryAfterReady = (bytes: Uint8Array): boolean | void => { if (!readyEmitted) { // Why: binary screencast frames are connection-scoped; clients learn the // owning subscription from `ready`, so CDP frames must remain unacked // until the stream's JSON ready event has been delivered. return false } return options.sendBinary?.(bytes) } // Why: a phone can rotate before the first stream reaches `ready`, so it // has no subscriptionId to unsubscribe. A same-socket replacement cancels // and waits here instead of racing the active connection/page gates. this.activeBrowserScreencastsByConnection.set(connectionKey, { cancel, done: activeDone, connectionKey }) options.signal?.addEventListener('abort', abortScreencast, { once: true }) try { screencast = await this.browserCommands.browserScreencast(params, { sendBinary: sendBinaryAfterReady, emit: options.emit }) if (cancelledBeforeStart || options.signal?.aborted) { end(false) await screencast.session.done return } activeBrowserPageId = screencast.ready.browserPageId this.activeBrowserScreencastsByPage.set(activeBrowserPageId, { cancel, done: activeDone, connectionKey }) this.setBrowserDriver(activeBrowserPageId, { kind: 'mobile', clientId: connectionKey }) // Why: browser screencast frames are connection-scoped media. Registering // cleanup ties Page.stopScreencast to the exact remote socket so hidden // client panes and dropped connections do not leave Chromium streaming. this.registerSubscriptionCleanup( screencast.subscriptionId, () => end(true), options.connectionId ) registeredSubscriptionId = screencast.subscriptionId options.emit(screencast.ready) readyEmitted = true await screencast.session.done end(true) this.cleanupSubscription(screencast.subscriptionId) } finally { options.signal?.removeEventListener('abort', abortScreencast) if (!ended) { end(false) } if (registeredSubscriptionId) { this.cleanupSubscription(registeredSubscriptionId) } const active = this.activeBrowserScreencastsByConnection.get(connectionKey) if (active?.done === activeDone) { this.activeBrowserScreencastsByConnection.delete(connectionKey) } if (activeBrowserPageId) { const activePageStream = this.activeBrowserScreencastsByPage.get(activeBrowserPageId) if (activePageStream?.done === activeDone) { this.activeBrowserScreencastsByPage.delete(activeBrowserPageId) } const driver = this.getBrowserDriver(activeBrowserPageId) if (driver.kind === 'mobile' && driver.clientId === connectionKey) { this.setBrowserDriver(activeBrowserPageId, { kind: 'idle' }) } } resolveActiveDone() } } browserEval: RuntimeBrowserCommands['browserEval'] = this.browserCommands.browserEval.bind( this.browserCommands ) browserTabList: RuntimeBrowserCommands['browserTabList'] = this.browserCommands.browserTabList.bind(this.browserCommands) browserTabShow: RuntimeBrowserCommands['browserTabShow'] = this.browserCommands.browserTabShow.bind(this.browserCommands) browserTabCurrent: RuntimeBrowserCommands['browserTabCurrent'] = this.browserCommands.browserTabCurrent.bind(this.browserCommands) browserTabSwitch: RuntimeBrowserCommands['browserTabSwitch'] = this.browserCommands.browserTabSwitch.bind(this.browserCommands) browserHover: RuntimeBrowserCommands['browserHover'] = this.browserCommands.browserHover.bind( this.browserCommands ) browserDrag: RuntimeBrowserCommands['browserDrag'] = this.browserCommands.browserDrag.bind( this.browserCommands ) browserUpload: RuntimeBrowserCommands['browserUpload'] = this.browserCommands.browserUpload.bind( this.browserCommands ) browserWait: RuntimeBrowserCommands['browserWait'] = this.browserCommands.browserWait.bind( this.browserCommands ) browserCheck: RuntimeBrowserCommands['browserCheck'] = this.browserCommands.browserCheck.bind( this.browserCommands ) browserFocus: RuntimeBrowserCommands['browserFocus'] = this.browserCommands.browserFocus.bind( this.browserCommands ) browserClear: RuntimeBrowserCommands['browserClear'] = this.browserCommands.browserClear.bind( this.browserCommands ) browserSelectAll: RuntimeBrowserCommands['browserSelectAll'] = this.browserCommands.browserSelectAll.bind(this.browserCommands) browserKeypress: RuntimeBrowserCommands['browserKeypress'] = this.browserCommands.browserKeypress.bind(this.browserCommands) browserPdf: RuntimeBrowserCommands['browserPdf'] = this.browserCommands.browserPdf.bind( this.browserCommands ) browserFullScreenshot: RuntimeBrowserCommands['browserFullScreenshot'] = this.browserCommands.browserFullScreenshot.bind(this.browserCommands) browserCookieGet: RuntimeBrowserCommands['browserCookieGet'] = this.browserCommands.browserCookieGet.bind(this.browserCommands) browserCookieSet: RuntimeBrowserCommands['browserCookieSet'] = this.browserCommands.browserCookieSet.bind(this.browserCommands) browserCookieDelete: RuntimeBrowserCommands['browserCookieDelete'] = this.browserCommands.browserCookieDelete.bind(this.browserCommands) browserSetViewport: RuntimeBrowserCommands['browserSetViewport'] = this.browserCommands.browserSetViewport.bind(this.browserCommands) browserSetGeolocation: RuntimeBrowserCommands['browserSetGeolocation'] = this.browserCommands.browserSetGeolocation.bind(this.browserCommands) browserInterceptEnable: RuntimeBrowserCommands['browserInterceptEnable'] = this.browserCommands.browserInterceptEnable.bind(this.browserCommands) browserInterceptDisable: RuntimeBrowserCommands['browserInterceptDisable'] = this.browserCommands.browserInterceptDisable.bind(this.browserCommands) browserInterceptList: RuntimeBrowserCommands['browserInterceptList'] = this.browserCommands.browserInterceptList.bind(this.browserCommands) browserCaptureStart: RuntimeBrowserCommands['browserCaptureStart'] = this.browserCommands.browserCaptureStart.bind(this.browserCommands) browserCaptureStop: RuntimeBrowserCommands['browserCaptureStop'] = this.browserCommands.browserCaptureStop.bind(this.browserCommands) browserConsoleLog: RuntimeBrowserCommands['browserConsoleLog'] = this.browserCommands.browserConsoleLog.bind(this.browserCommands) browserNetworkLog: RuntimeBrowserCommands['browserNetworkLog'] = this.browserCommands.browserNetworkLog.bind(this.browserCommands) browserDblclick: RuntimeBrowserCommands['browserDblclick'] = this.browserCommands.browserDblclick.bind(this.browserCommands) browserForward: RuntimeBrowserCommands['browserForward'] = this.browserCommands.browserForward.bind(this.browserCommands) browserScrollIntoView: RuntimeBrowserCommands['browserScrollIntoView'] = this.browserCommands.browserScrollIntoView.bind(this.browserCommands) browserGet: RuntimeBrowserCommands['browserGet'] = this.browserCommands.browserGet.bind( this.browserCommands ) browserIs: RuntimeBrowserCommands['browserIs'] = this.browserCommands.browserIs.bind( this.browserCommands ) browserKeyboardInsertText: RuntimeBrowserCommands['browserKeyboardInsertText'] = this.browserCommands.browserKeyboardInsertText.bind(this.browserCommands) browserMouseMove: RuntimeBrowserCommands['browserMouseMove'] = this.browserCommands.browserMouseMove.bind(this.browserCommands) browserMouseDown: RuntimeBrowserCommands['browserMouseDown'] = this.browserCommands.browserMouseDown.bind(this.browserCommands) browserMouseClick: RuntimeBrowserCommands['browserMouseClick'] = this.browserCommands.browserMouseClick.bind(this.browserCommands) browserMouseUp: RuntimeBrowserCommands['browserMouseUp'] = this.browserCommands.browserMouseUp.bind(this.browserCommands) browserMouseWheel: RuntimeBrowserCommands['browserMouseWheel'] = this.browserCommands.browserMouseWheel.bind(this.browserCommands) browserFind: RuntimeBrowserCommands['browserFind'] = this.browserCommands.browserFind.bind( this.browserCommands ) browserSetDevice: RuntimeBrowserCommands['browserSetDevice'] = this.browserCommands.browserSetDevice.bind(this.browserCommands) browserSetOffline: RuntimeBrowserCommands['browserSetOffline'] = this.browserCommands.browserSetOffline.bind(this.browserCommands) browserSetHeaders: RuntimeBrowserCommands['browserSetHeaders'] = this.browserCommands.browserSetHeaders.bind(this.browserCommands) browserSetCredentials: RuntimeBrowserCommands['browserSetCredentials'] = this.browserCommands.browserSetCredentials.bind(this.browserCommands) browserSetMedia: RuntimeBrowserCommands['browserSetMedia'] = this.browserCommands.browserSetMedia.bind(this.browserCommands) browserClipboardRead: RuntimeBrowserCommands['browserClipboardRead'] = this.browserCommands.browserClipboardRead.bind(this.browserCommands) browserClipboardWrite: RuntimeBrowserCommands['browserClipboardWrite'] = this.browserCommands.browserClipboardWrite.bind(this.browserCommands) browserDialogAccept: RuntimeBrowserCommands['browserDialogAccept'] = this.browserCommands.browserDialogAccept.bind(this.browserCommands) browserDialogDismiss: RuntimeBrowserCommands['browserDialogDismiss'] = this.browserCommands.browserDialogDismiss.bind(this.browserCommands) browserStorageLocalGet: RuntimeBrowserCommands['browserStorageLocalGet'] = this.browserCommands.browserStorageLocalGet.bind(this.browserCommands) browserStorageLocalSet: RuntimeBrowserCommands['browserStorageLocalSet'] = this.browserCommands.browserStorageLocalSet.bind(this.browserCommands) browserStorageLocalClear: RuntimeBrowserCommands['browserStorageLocalClear'] = this.browserCommands.browserStorageLocalClear.bind(this.browserCommands) browserStorageSessionGet: RuntimeBrowserCommands['browserStorageSessionGet'] = this.browserCommands.browserStorageSessionGet.bind(this.browserCommands) browserStorageSessionSet: RuntimeBrowserCommands['browserStorageSessionSet'] = this.browserCommands.browserStorageSessionSet.bind(this.browserCommands) browserStorageSessionClear: RuntimeBrowserCommands['browserStorageSessionClear'] = this.browserCommands.browserStorageSessionClear.bind(this.browserCommands) browserDownload: RuntimeBrowserCommands['browserDownload'] = this.browserCommands.browserDownload.bind(this.browserCommands) browserHighlight: RuntimeBrowserCommands['browserHighlight'] = this.browserCommands.browserHighlight.bind(this.browserCommands) browserExec: RuntimeBrowserCommands['browserExec'] = this.browserCommands.browserExec.bind( this.browserCommands ) browserTabCreate: RuntimeBrowserCommands['browserTabCreate'] = this.browserCommands.browserTabCreate.bind(this.browserCommands) browserTabSetProfile: RuntimeBrowserCommands['browserTabSetProfile'] = this.browserCommands.browserTabSetProfile.bind(this.browserCommands) browserTabProfileShow: RuntimeBrowserCommands['browserTabProfileShow'] = this.browserCommands.browserTabProfileShow.bind(this.browserCommands) browserTabProfileClone: RuntimeBrowserCommands['browserTabProfileClone'] = this.browserCommands.browserTabProfileClone.bind(this.browserCommands) browserProfileList: RuntimeBrowserCommands['browserProfileList'] = this.browserCommands.browserProfileList.bind(this.browserCommands) browserProfileCreate: RuntimeBrowserCommands['browserProfileCreate'] = this.browserCommands.browserProfileCreate.bind(this.browserCommands) browserProfileDelete: RuntimeBrowserCommands['browserProfileDelete'] = this.browserCommands.browserProfileDelete.bind(this.browserCommands) browserProfileDetectBrowsers: RuntimeBrowserCommands['browserProfileDetectBrowsers'] = this.browserCommands.browserProfileDetectBrowsers.bind(this.browserCommands) browserProfileImportFromBrowser: RuntimeBrowserCommands['browserProfileImportFromBrowser'] = this.browserCommands.browserProfileImportFromBrowser.bind(this.browserCommands) browserProfileClearDefaultCookies: RuntimeBrowserCommands['browserProfileClearDefaultCookies'] = this.browserCommands.browserProfileClearDefaultCookies.bind(this.browserCommands) browserTabClose: RuntimeBrowserCommands['browserTabClose'] = this.browserCommands.browserTabClose.bind(this.browserCommands) // Emulator bindings (delegated to dedicated commands for surface separation). emulatorTap: RuntimeEmulatorCommands['emulatorTap'] = this.emulatorCommands.emulatorTap.bind( this.emulatorCommands ) emulatorGesture: RuntimeEmulatorCommands['emulatorGesture'] = this.emulatorCommands.emulatorGesture.bind(this.emulatorCommands) emulatorType: RuntimeEmulatorCommands['emulatorType'] = this.emulatorCommands.emulatorType.bind( this.emulatorCommands ) emulatorButton: RuntimeEmulatorCommands['emulatorButton'] = this.emulatorCommands.emulatorButton.bind(this.emulatorCommands) emulatorRotate: RuntimeEmulatorCommands['emulatorRotate'] = this.emulatorCommands.emulatorRotate.bind(this.emulatorCommands) emulatorExec: RuntimeEmulatorCommands['emulatorExec'] = this.emulatorCommands.emulatorExec.bind( this.emulatorCommands ) emulatorAttach: RuntimeEmulatorCommands['emulatorAttach'] = this.emulatorCommands.emulatorAttach.bind(this.emulatorCommands) emulatorList: RuntimeEmulatorCommands['emulatorList'] = this.emulatorCommands.emulatorList.bind( this.emulatorCommands ) emulatorKill: RuntimeEmulatorCommands['emulatorKill'] = this.emulatorCommands.emulatorKill.bind( this.emulatorCommands ) emulatorShutdown: RuntimeEmulatorCommands['emulatorShutdown'] = this.emulatorCommands.emulatorShutdown.bind(this.emulatorCommands) emulatorListSimulators: RuntimeEmulatorCommands['emulatorListSimulators'] = this.emulatorCommands.emulatorListSimulators.bind(this.emulatorCommands) emulatorAvailability: RuntimeEmulatorCommands['emulatorAvailability'] = this.emulatorCommands.emulatorAvailability.bind(this.emulatorCommands) emulatorListDevices: RuntimeEmulatorCommands['emulatorListDevices'] = this.emulatorCommands.emulatorListDevices.bind(this.emulatorCommands) emulatorInstall: RuntimeEmulatorCommands['emulatorInstall'] = this.emulatorCommands.emulatorInstall.bind(this.emulatorCommands) emulatorLaunch: RuntimeEmulatorCommands['emulatorLaunch'] = this.emulatorCommands.emulatorLaunch.bind(this.emulatorCommands) emulatorPermissions: RuntimeEmulatorCommands['emulatorPermissions'] = this.emulatorCommands.emulatorPermissions.bind(this.emulatorCommands) emulatorAx: RuntimeEmulatorCommands['emulatorAx'] = this.emulatorCommands.emulatorAx.bind( this.emulatorCommands ) emulatorLogcat: RuntimeEmulatorCommands['emulatorLogcat'] = this.emulatorCommands.emulatorLogcat.bind(this.emulatorCommands) emulatorUnregisterActive: RuntimeEmulatorCommands['emulatorUnregisterActive'] = this.emulatorCommands.emulatorUnregisterActive.bind(this.emulatorCommands) // Why: serve-sim-state-watcher runs from main/index.ts startup; keep window IPC behind runtime (getAuthoritativeWindow is private). notifyEmulatorAutoAttachFromWatcher( worktreeId: string, info: { deviceUdid: string; streamUrl: string; wsUrl: string; axUrl?: string } ): void { try { this.getAuthoritativeWindow().webContents.send('ui:emulatorAutoAttach', { worktreeId, info }) } catch { // Window may not exist during shutdown } } private getAuthoritativeWindow(): BrowserWindow { const win = this.getAvailableAuthoritativeWindow() if (!win || win.isDestroyed()) { throw new Error('No renderer window available') } return win } private getAvailableAuthoritativeWindow(): BrowserWindow | null { if (this.authoritativeWindowId === null) { return null } if (!BrowserWindow?.fromId) { return null } const win = BrowserWindow.fromId(this.authoritativeWindowId) return win && !win.isDestroyed() ? win : null } } const MAX_TAIL_LINES = 2000 const MAX_TAIL_CHARS = 256 * 1024 const MAX_TAIL_PARTIAL_CHARS = 4000 const MAX_TAIL_PENDING_ANSI_CHARS = 4096 const DEFAULT_TERMINAL_READ_LIMIT = 120 const MAX_TERMINAL_READ_LIMIT = 2000 const MAX_TERMINAL_PREVIEW_CHARS = 32 * 1024 const MAX_PREVIEW_LINES = 6 const MAX_PREVIEW_CHARS = 300 const WORKTREE_STATUS_PRIORITY: Record = { inactive: 0, active: 1, done: 2, working: 3, permission: 4 } const DEFAULT_REPO_SEARCH_REFS_LIMIT = 25 const DEFAULT_TERMINAL_LIST_LIMIT = 200 const DEFAULT_WORKTREE_LIST_LIMIT = 200 const DEFAULT_WORKTREE_PS_LIMIT = 200 const DISCONNECTED_PTY_RECORD_MAX = 128 const RESOLVED_WORKTREE_CACHE_TTL_MS = 1000 const RESOLVED_WORKTREE_REPO_TIMEOUT_MS = 5000 const PTY_CONTROLLER_LIST_TIMEOUT_MS = 3000 // Why (§3.3): 30s freshness window. A second worktree-create or dispatch-probe // against the same repo+remote within this window reuses the previous successful // fetch instead of repeating the round-trip. Chosen so rapid "new worktree" // clicks and successive coordinator dispatches feel snappy, while still being // short enough that a genuinely-changed remote is observed on the next action. const FETCH_FRESHNESS_MS = 30_000 const REMOTE_FETCH_CACHE_MAX = 512 const DRIFT_PROBE_SUBJECT_LIMIT = 5 function setBoundedMapEntry(map: Map, key: K, value: V, maxEntries: number): void { if (map.has(key)) { map.delete(key) } map.set(key, value) while (map.size > maxEntries) { const oldest = map.keys().next() if (oldest.done) { return } map.delete(oldest.value) } } function getExplicitWorktreeIdSelector(selector: string | undefined): string | null { if (!selector?.startsWith('id:')) { return null } const id = selector.slice(3) return id.length > 0 ? id : null } function withTimeout(promise: Promise, timeoutMs: number, fallback: T): Promise { let timeout: ReturnType | null = null return new Promise((resolve) => { timeout = setTimeout(() => resolve(fallback), timeoutMs) promise.then( (value) => resolve(value), () => resolve(fallback) ) }).finally(() => { if (timeout) { clearTimeout(timeout) } }) } function withTimeoutResult( promise: Promise, timeoutMs: number ): Promise<{ ok: true; value: T } | { ok: false }> { return withTimeout( promise.then((value) => ({ ok: true, value }) as const), timeoutMs, { ok: false } ) } export function appendRecentPtyOutput(previous: string | undefined, data: string): string { if (data.length >= RECENT_PTY_OUTPUT_LIMIT) { return data.slice(-RECENT_PTY_OUTPUT_LIMIT) } return `${previous ?? ''}${data}`.slice(-RECENT_PTY_OUTPUT_LIMIT) } export function buildPreview(lines: string[], partialLine: string): string { const previewLines: string[] = [] const collectVisibleLine = (line: string): void => { const trimmed = line.trim() if (trimmed.length > 0) { previewLines.push(trimmed) } } if (partialLine.length > 0) { collectVisibleLine(partialLine) } for ( let index = lines.length - 1; index >= 0 && previewLines.length < MAX_PREVIEW_LINES; index-- ) { collectVisibleLine(lines[index]) } previewLines.reverse() const preview = previewLines.join('\n') return preview.length > MAX_PREVIEW_CHARS ? preview.slice(preview.length - MAX_PREVIEW_CHARS) : preview } function buildTerminalWaitText(lines: string[], partialLine: string, preview: string): string { const waitText = buildTailLines(lines, partialLine) .map((line) => line.trim()) .filter(Boolean) .join('\n') // Why: the user-facing preview is intentionally short, but wait readiness // needs the retained terminal tail so known ready headers are not truncated away. return waitText.length > 0 ? waitText : preview } export function appendNormalizedToTailBuffer( previousLines: string[], previousPartialLine: string, normalizedChunk: string, previousRedrawCursor: RetainedTailRedrawCursor | null = null ): { lines: string[] partialLine: string redrawCursor: RetainedTailRedrawCursor | null truncated: boolean newCompleteLines: number } { if (normalizedChunk.length === 0) { return { lines: previousLines, partialLine: previousPartialLine, redrawCursor: previousRedrawCursor, truncated: false, newCompleteLines: 0 } } // Why: fullscreen TUIs often emit long, newline-free redraw streams. Keep the // larger line transcript for pagination, but keep partial-line work bounded. const previousPartialWasCapped = previousPartialLine.length > MAX_TAIL_PARTIAL_CHARS const boundedPreviousPartialLine = previousPartialLine.slice(-MAX_TAIL_PARTIAL_CHARS) const combinedChunk = `${boundedPreviousPartialLine}${normalizedChunk}` if (previousRedrawCursor || containsTerminalVerticalLineControl(combinedChunk)) { return appendNormalizedToMultilineTailBuffer( previousLines, boundedPreviousPartialLine, normalizedChunk, previousPartialWasCapped, previousRedrawCursor ) } // Why: status UIs redraw a single line with CR/backspace/ANSI erase controls. // Terminal previews are text, not a full screen model, so retain the latest // visible redraw segment instead of appending every spinner frame. const segments = splitRetainedTerminalTailSegments(combinedChunk) const pieces = processTerminalTailCompleteSegments(segments.completeSegments) const partialResult = applyTerminalLineControls(segments.partialSegment) const nextPartialLine = trimTerminalLineRight(partialResult.text) const retainedPartialLine = nextPartialLine.slice(-MAX_TAIL_PARTIAL_CHARS) const newCompleteLines = segments.completeLineCount const omittedNewCompleteLines = newCompleteLines - pieces.length let nextLines = newCompleteLines > 0 ? [ ...(omittedNewCompleteLines > 0 ? [] : previousLines), ...pieces.map((line) => line.replace(/[ \t]+$/g, '')) ] : previousLines let truncated = previousPartialWasCapped || omittedNewCompleteLines > 0 || nextPartialLine.length > MAX_TAIL_PARTIAL_CHARS if (nextLines.length > MAX_TAIL_LINES) { nextLines = nextLines.slice(nextLines.length - MAX_TAIL_LINES) truncated = true } if (newCompleteLines > 0 || retainedPartialLine.length > previousPartialLine.length) { if (nextLines === previousLines) { nextLines = [...previousLines] } let totalChars = nextLines.reduce((sum, line) => sum + line.length, 0) + retainedPartialLine.length let trimStartIndex = 0 while (trimStartIndex < nextLines.length && totalChars > MAX_TAIL_CHARS) { totalChars -= nextLines[trimStartIndex].length trimStartIndex += 1 } if (trimStartIndex > 0) { nextLines = nextLines.slice(trimStartIndex) truncated = true } } const redrawCursor = !partialResult.hadControl || partialResult.cursorColumn === nextPartialLine.length ? null : { rowFromEnd: 0, column: partialResult.cursorColumn } return { lines: nextLines, partialLine: retainedPartialLine, redrawCursor, truncated, newCompleteLines } } function trimTerminalLineRight(line: string): string { let end = line.length while (end > 0) { const code = line.charCodeAt(end - 1) if (code !== 0x20 && code !== 0x09) { break } end -= 1 } return end === line.length ? line : line.slice(0, end) } function appendNormalizedToMultilineTailBuffer( previousLines: string[], boundedPreviousPartialLine: string, normalizedChunk: string, previousPartialWasCapped: boolean, previousRedrawCursor: RetainedTailRedrawCursor | null ): { lines: string[] partialLine: string redrawCursor: RetainedTailRedrawCursor | null truncated: boolean newCompleteLines: number } { const rows: RetainedTerminalRow[] = [ ...previousLines.map((line) => ({ text: line, completed: true })), { text: boundedPreviousPartialLine, completed: false } ] let cursorRow = previousRedrawCursor ? Math.max(0, rows.length - 1 - previousRedrawCursor.rowFromEnd) : rows.length - 1 let cursorColumn = previousRedrawCursor?.column ?? boundedPreviousPartialLine.length let newCompleteLines = 0 let truncated = previousPartialWasCapped const ensureCursorRow = (): void => { while (cursorRow >= rows.length) { rows.push({ text: '', completed: false }) } } const trimRows = (): void => { const maxRows = MAX_TAIL_LINES + 1 if (rows.length <= maxRows) { return } const removeCount = rows.length - maxRows rows.splice(0, removeCount) cursorRow = Math.max(0, cursorRow - removeCount) truncated = true } const moveCursorToColumn = (nextColumn: number): void => { cursorColumn = clampTerminalPreviewCursor(nextColumn) } const markCursorRowRewritten = (): void => { ensureCursorRow() rows[cursorRow]!.completed = false } const writeChar = (char: string): void => { ensureCursorRow() markCursorRowRewritten() const row = rows[cursorRow]! if (cursorColumn > row.text.length) { row.text = `${row.text}${' '.repeat(cursorColumn - row.text.length)}` } row.text = cursorColumn >= row.text.length ? `${row.text}${char}` : `${row.text.slice(0, cursorColumn)}${char}${row.text.slice(cursorColumn + 1)}` cursorColumn += 1 } const eraseLine = (mode: number): void => { ensureCursorRow() markCursorRowRewritten() const row = rows[cursorRow]! if (mode === 0) { row.text = row.text.slice(0, cursorColumn) } else if (mode === 1) { const deleteCount = Math.min(cursorColumn + 1, row.text.length) row.text = `${' '.repeat(deleteCount)}${row.text.slice(deleteCount)}` } else if (mode === 2) { row.text = '' } } for (let index = 0; index < normalizedChunk.length; index += 1) { const char = normalizedChunk[index] if (char === '\n') { ensureCursorRow() rows[cursorRow]!.completed = true newCompleteLines += 1 cursorRow += 1 cursorColumn = 0 ensureCursorRow() trimRows() continue } if (char === '\r') { cursorColumn = 0 continue } if (char === '\u0008') { cursorColumn = Math.max(0, cursorColumn - 1) continue } if (char === '\u001b') { const parsed = parseAnsiControlSequence(normalizedChunk, index) if (!parsed) { continue } index = parsed.endIndex if (parsed.kind !== 'csi' || !hasCanonicalNumericCsiParams(parsed.params)) { continue } const firstParam = parsed.firstParam ?? 1 if (parsed.final === 'A') { cursorRow = Math.max(0, cursorRow - firstParam) rows.splice(cursorRow + 1) } else if (parsed.final === 'K') { eraseLine(parsed.firstParam ?? 0) } else if (parsed.final === 'G' || parsed.final === '`') { moveCursorToColumn(firstParam - 1) } else if (parsed.final === 'D') { cursorColumn = Math.max(0, cursorColumn - firstParam) } else if (parsed.final === 'C') { moveCursorToColumn(cursorColumn + firstParam) } continue } writeChar(char) } return finalizeRetainedTerminalRows(rows, cursorRow, cursorColumn, truncated, newCompleteLines) } type RetainedTailRedrawCursor = { rowFromEnd: number column: number } type RetainedTerminalRow = { text: string completed: boolean } function finalizeRetainedTerminalRows( rows: RetainedTerminalRow[], cursorRow: number, cursorColumn: number, initialTruncated: boolean, newCompleteLines: number ): { lines: string[] partialLine: string redrawCursor: RetainedTailRedrawCursor | null truncated: boolean newCompleteLines: number } { let truncated = initialTruncated let retainedRows = rows.map((row) => ({ ...row, text: row.text.replace(/[ \t]+$/g, '') })) if (retainedRows.length > MAX_TAIL_LINES + 1) { const removeCount = retainedRows.length - (MAX_TAIL_LINES + 1) retainedRows = retainedRows.slice(removeCount) cursorRow = Math.max(0, cursorRow - removeCount) truncated = true } let totalChars = retainedRows.reduce((sum, row) => sum + row.text.length, 0) let trimStartIndex = 0 while (trimStartIndex < retainedRows.length - 1 && totalChars > MAX_TAIL_CHARS) { totalChars -= retainedRows[trimStartIndex]!.text.length trimStartIndex += 1 } if (trimStartIndex > 0) { retainedRows = retainedRows.slice(trimStartIndex) cursorRow = Math.max(0, cursorRow - trimStartIndex) truncated = true } while ( retainedRows.length > 1 && cursorRow < retainedRows.length - 1 && retainedRows.at(-1)?.completed === false && retainedRows.at(-1)?.text.length === 0 ) { retainedRows.pop() } const lastRow = retainedRows.at(-1) let partialLine = lastRow && !lastRow.completed ? lastRow.text : '' let lines = (lastRow && !lastRow.completed ? retainedRows.slice(0, -1) : retainedRows).map( (row) => row.text ) if (partialLine.length > MAX_TAIL_PARTIAL_CHARS) { partialLine = partialLine.slice(-MAX_TAIL_PARTIAL_CHARS) truncated = true } if (lines.length > MAX_TAIL_LINES) { lines = lines.slice(lines.length - MAX_TAIL_LINES) truncated = true } const outputRowCount = lines.length + 1 const defaultCursorRow = outputRowCount - 1 const defaultCursorColumn = partialLine.length const redrawCursor = cursorRow === defaultCursorRow && cursorColumn === defaultCursorColumn ? null : { rowFromEnd: Math.max(0, outputRowCount - 1 - cursorRow), column: clampTerminalPreviewCursor(cursorColumn) } return { lines, partialLine, redrawCursor, truncated, newCompleteLines } } function splitRetainedTerminalTailSegments(value: string): { completeSegments: string[] partialSegment: string completeLineCount: number } { let completeLineCount = 0 for (let index = 0; index < value.length; index += 1) { if (value[index] === '\n') { completeLineCount += 1 } } const retainedCompleteCount = Math.min(completeLineCount, MAX_TAIL_LINES) const omittedCompleteCount = completeLineCount - retainedCompleteCount let startIndex = 0 if (omittedCompleteCount > 0) { let seen = 0 for (let index = 0; index < value.length; index += 1) { if (value[index] !== '\n') { continue } seen += 1 if (seen === omittedCompleteCount) { startIndex = index + 1 break } } } const completeSegments: string[] = [] let segmentStart = startIndex for (let index = startIndex; index < value.length; index += 1) { if (value[index] !== '\n') { continue } completeSegments.push(value.slice(segmentStart, index)) segmentStart = index + 1 } return { completeSegments, partialSegment: value.slice(segmentStart), completeLineCount } } function processTerminalTailCompleteSegments(segments: string[]): string[] { const processed: string[] = [] let totalChars = 0 for (let index = segments.length - 1; index >= 0; index -= 1) { const line = applyTerminalLineControls(segments[index]!).text processed.push(line) totalChars += line.length if (totalChars > MAX_TAIL_CHARS) { break } } processed.reverse() return processed } function applyTerminalLineControls(line: string): { text: string cursorColumn: number hadControl: boolean } { const carriageIndex = line.lastIndexOf('\r') const latestRedraw = carriageIndex >= 0 ? line.slice(carriageIndex + 1) : line if (!latestRedraw.includes('\u0008') && !latestRedraw.includes('\u001b')) { return { text: latestRedraw, cursorColumn: latestRedraw.length, hadControl: carriageIndex >= 0 } } const chars: string[] = [] let cursor = 0 const moveCursorTo = (nextCursor: number): void => { cursor = clampTerminalPreviewCursor(nextCursor) } const writeChar = (char: string): void => { if (cursor > chars.length) { const oldLength = chars.length chars.length = cursor chars.fill(' ', oldLength, cursor) } if (cursor >= chars.length) { chars.push(char) } else { chars[cursor] = char } cursor += 1 } for (let index = 0; index < latestRedraw.length; index += 1) { const char = latestRedraw[index] if (char === '\u0008') { if (cursor > 0) { cursor -= 1 } } else if (char === '\u001b') { const parsed = parseAnsiControlSequence(latestRedraw, index) if (!parsed) { continue } index = parsed.endIndex if (parsed.kind !== 'csi') { continue } if (!hasCanonicalNumericCsiParams(parsed.params)) { continue } if (parsed.final === 'K') { const mode = parsed.firstParam ?? 0 if (mode === 0) { chars.length = cursor } else if (mode === 1) { const deleteCount = Math.min(cursor + 1, chars.length) chars.fill(' ', 0, deleteCount) } else if (mode === 2) { chars.length = 0 } } else if (parsed.final === 'G' || parsed.final === '`') { moveCursorTo((parsed.firstParam ?? 1) - 1) } else if (parsed.final === 'D') { cursor = Math.max(0, cursor - (parsed.firstParam ?? 1)) } else if (parsed.final === 'C') { moveCursorTo(cursor + (parsed.firstParam ?? 1)) } } else { writeChar(char) } } return { text: chars.join(''), cursorColumn: cursor, hadControl: true } } function clampTerminalPreviewCursor(nextCursor: number): number { if (!Number.isFinite(nextCursor)) { return MAX_TAIL_PARTIAL_CHARS } return Math.min(MAX_TAIL_PARTIAL_CHARS, Math.max(0, Math.floor(nextCursor))) } function parseAnsiControlSequence( value: string, escapeIndex: number ): | { kind: 'csi'; final: string; params: string; firstParam: number | null; endIndex: number } | { kind: 'other' endIndex: number } | null { const introducer = value[escapeIndex + 1] if (introducer === '[') { for (let index = escapeIndex + 2; index < value.length; index += 1) { const code = value.charCodeAt(index) if (code < 0x40 || code > 0x7e) { continue } const params = value.slice(escapeIndex + 2, index) const firstParamMatch = /^(\d+)/.exec(params) return { kind: 'csi', final: value[index] ?? '', params, firstParam: firstParamMatch ? Number(firstParamMatch[1]) : null, endIndex: index } } return null } if (introducer === ']') { for (let index = escapeIndex + 2; index < value.length; index += 1) { if (value[index] === '\u0007') { return { kind: 'other', endIndex: index } } if (value[index] === '\u001b' && value[index + 1] === '\\') { return { kind: 'other', endIndex: index + 1 } } } return null } if (isStTerminatedStringControlIntroducer(introducer)) { for (let index = escapeIndex + 2; index < value.length; index += 1) { if (value[index] === '\u001b' && value[index + 1] === '\\') { return { kind: 'other', endIndex: index + 1 } } } return null } return { kind: 'other', endIndex: escapeIndex + 1 } } function isStTerminatedStringControlIntroducer(introducer: string | undefined): boolean { return introducer === 'P' || introducer === 'X' || introducer === '^' || introducer === '_' } function hasCanonicalNumericCsiParams(params: string): boolean { return /^[0-9;]*$/.test(params) } function containsTerminalVerticalLineControl(value: string): boolean { for (let index = 0; index < value.length; index += 1) { if (value[index] !== '\u001b') { continue } const parsed = parseAnsiControlSequence(value, index) if (!parsed) { return false } index = parsed.endIndex if ( parsed.kind === 'csi' && parsed.final === 'A' && hasCanonicalNumericCsiParams(parsed.params) ) { return true } } return false } function tailStateMatches( lines: string[], partialLine: string, pendingAnsi: string, redrawCursor: RetainedTailRedrawCursor | null, truncated: boolean, linesTotal: number, snapshot: { lines: string[] partialLine: string pendingAnsi: string redrawCursor: RetainedTailRedrawCursor | null truncated: boolean linesTotal: number } ): boolean { if ( partialLine !== snapshot.partialLine || pendingAnsi !== snapshot.pendingAnsi || !tailRedrawCursorsMatch(redrawCursor, snapshot.redrawCursor) || truncated !== snapshot.truncated || linesTotal !== snapshot.linesTotal || lines.length !== snapshot.lines.length ) { return false } if (lines === snapshot.lines) { return true } for (let index = 0; index < lines.length; index++) { if (lines[index] !== snapshot.lines[index]) { return false } } return true } function tailRedrawCursorsMatch( left: RetainedTailRedrawCursor | null, right: RetainedTailRedrawCursor | null ): boolean { if (left === right) { return true } if (!left || !right) { return false } return left.rowFromEnd === right.rowFromEnd && left.column === right.column } function buildTailLines(lines: string[], partialLine: string): string[] { return partialLine.length > 0 ? [...lines, partialLine] : lines } function terminalReadLimit(limit: number | undefined, defaultLimit: number): number { if (typeof limit !== 'number' || !Number.isFinite(limit) || limit <= 0) { return defaultLimit } return Math.min(Math.max(1, Math.floor(limit)), MAX_TERMINAL_READ_LIMIT) } function trimTerminalPreviewToCharacterBudget( lines: string[], characterBudget: number ): { tail: string[]; limited: boolean; omittedLineCount: number; slicedFirstLine: boolean } { let totalCharacters = lines.reduce((sum, line) => sum + line.length, 0) if (totalCharacters <= characterBudget) { return { tail: lines, limited: false, omittedLineCount: 0, slicedFirstLine: false } } let omittedLineCount = 0 while ( omittedLineCount < lines.length && totalCharacters - lines[omittedLineCount].length >= characterBudget ) { totalCharacters -= lines[omittedLineCount].length omittedLineCount += 1 } const tail = omittedLineCount > 0 ? lines.slice(omittedLineCount) : [...lines] let slicedFirstLine = false if (tail.length > 0 && totalCharacters > characterBudget) { tail[0] = tail[0].slice(totalCharacters - characterBudget) slicedFirstLine = true } return { tail, limited: true, omittedLineCount, slicedFirstLine } } function readTerminalTail(args: { handle: string status: RuntimeTerminalState completedLines: string[] partialLine: string completedLineCount: number bufferTruncated: boolean cursor?: number limit?: number }): RuntimeTerminalRead { const oldestCursor = Math.max(0, args.completedLineCount - args.completedLines.length) const latestCursor = args.completedLineCount if (typeof args.cursor === 'number' && args.cursor >= 0) { const limit = terminalReadLimit(args.limit, MAX_TERMINAL_READ_LIMIT) if (args.cursor > latestCursor) { return { handle: args.handle, status: args.status, tail: [], truncated: false, limited: false, oldestCursor: String(oldestCursor), nextCursor: String(latestCursor), latestCursor: String(latestCursor), returnedLineCount: 0 } } // Why: cursor reads are transcript/pagination reads. They return completed // lines only so a partial line is not delivered once as "hel" and again as // "hello" after the newline arrives. const startCursor = Math.max(args.cursor, oldestCursor) const startIndex = startCursor - oldestCursor const available = args.completedLines.slice(startIndex) const tail = available.slice(0, limit) const nextCursor = startCursor + tail.length return { handle: args.handle, status: args.status, tail, truncated: args.cursor < oldestCursor, limited: tail.length < available.length, oldestCursor: String(oldestCursor), nextCursor: String(nextCursor), latestCursor: String(latestCursor), returnedLineCount: tail.length } } // Why: un-cursored reads are preview reads for humans/agents. Return the // latest bounded view, while the larger retained buffer remains available // through cursor reads plus --limit. const limit = terminalReadLimit(args.limit, DEFAULT_TERMINAL_READ_LIMIT) const allLines = buildTailLines(args.completedLines, args.partialLine) const lineBoundedTail = allLines.slice(-limit) const charBoundedTail = trimTerminalPreviewToCharacterBudget( lineBoundedTail, MAX_TERMINAL_PREVIEW_CHARS ) const lineBoundedStartIndex = Math.max(0, allLines.length - lineBoundedTail.length) const charBoundedStartIndex = lineBoundedStartIndex + charBoundedTail.omittedLineCount const hasPageableOmittedCompletedLines = Math.min(args.completedLineCount, charBoundedStartIndex) > 0 || (charBoundedTail.slicedFirstLine && charBoundedStartIndex < args.completedLineCount) // Why: a long unterminated partial line can exceed the preview character // budget, but cursor reads only page completed lines, so the trimmed bytes // cannot be recovered by asking for nextCursor again. const truncatedByNonPageablePartial = charBoundedTail.limited && !hasPageableOmittedCompletedLines return { handle: args.handle, status: args.status, tail: charBoundedTail.tail, truncated: args.bufferTruncated || truncatedByNonPageablePartial, limited: lineBoundedTail.length < allLines.length || charBoundedTail.limited, oldestCursor: String(oldestCursor), nextCursor: String(latestCursor), latestCursor: String(latestCursor), returnedLineCount: charBoundedTail.tail.length } } function shouldFallbackToVisibleTerminalSnapshot( read: RuntimeTerminalRead, opts: { cursor?: number; limit?: number } ): boolean { if (typeof opts.cursor === 'number') { return false } if (read.tail.length === 0) { return false } const hasSubstantialBlankTail = read.limited === true || read.truncated || read.tail.length >= DEFAULT_TERMINAL_READ_LIMIT return hasSubstantialBlankTail && read.tail.every((line) => line.trim().length === 0) } function buildVisibleSnapshotReadFallback( read: RuntimeTerminalRead, visibleLines: string[], limit: number | undefined ): RuntimeTerminalRead { const lineLimit = terminalReadLimit(limit, DEFAULT_TERMINAL_READ_LIMIT) const lineBoundedTail = visibleLines.slice(-lineLimit) const charBoundedTail = trimTerminalPreviewToCharacterBudget( lineBoundedTail, MAX_TERMINAL_PREVIEW_CHARS ) return { ...read, tail: charBoundedTail.tail, limited: read.limited || lineBoundedTail.length < visibleLines.length || charBoundedTail.limited, returnedLineCount: charBoundedTail.tail.length } } function getTerminalState(leaf: RuntimeLeafRecord): RuntimeTerminalState { if (leaf.connected) { return 'running' } if (leaf.lastExitCode !== null) { return 'exited' } return 'unknown' } function buildSendPayload(action: { text?: string enter?: boolean interrupt?: boolean }): string | null { let payload = '' if (typeof action.text === 'string' && action.text.length > 0) { payload += action.text } if (action.enter) { payload += '\r' } if (action.interrupt) { payload += '\x03' } return payload.length > 0 ? payload : null } async function assertTerminalInputWithinLimitWithYield(text: string | undefined): Promise { if (!text) { return } if (await isTerminalInputTooLargeWithYield(text)) { throw new Error(TERMINAL_INPUT_TOO_LARGE_ERROR) } } // Why: tui-idle relies on recognized agent CLIs setting OSC titles. If the // terminal runs an unsupported CLI (or a plain shell), no title transition // will ever fire. A 5-minute ceiling prevents indefinite hangs while still // giving real agent tasks plenty of time to complete. const TUI_IDLE_DEFAULT_TIMEOUT_MS = 5 * 60 * 1000 const TUI_IDLE_POLL_INTERVAL_MS = 2000 const TUI_IDLE_QUIESCENCE_MS = 3000 const MESSAGE_WAIT_DEFAULT_TIMEOUT_MS = 2 * 60 * 1000 const EXPLICIT_IDLE_TITLE_RE = /(^|\s)(ready|idle|done)(\s|$|[.!?])/i const CLAUDE_IDLE_PREFIX = '\u2733' const GEMINI_IDLE_PREFIX = '\u25c7' const PI_IDLE_PREFIX = '\u03c0 - ' // Clamp range for the user-facing mobileAutoRestoreFitMs preference. // MIN floor: a couple of seconds is the smallest useful auto-restore // (anything tighter is the legacy 300ms debounce). // MAX ceiling: one hour — a held PTY beyond that is almost certainly // "I forgot" rather than intentional. const MOBILE_AUTO_RESTORE_FIT_MIN_MS = 5_000 const MOBILE_AUTO_RESTORE_FIT_MAX_MS = 60 * 60 * 1000 function detectExplicitIdleStatusFromTitle(title: string): AgentStatus | null { const status = detectAgentStatusFromTitle(title) if (status !== 'idle') { return null } // Why: user-supplied launch titles like "Codex YOLO" contain an agent name // but are not readiness signals. terminal.wait needs explicit idle evidence. if ( EXPLICIT_IDLE_TITLE_RE.test(title) || title.startsWith(CLAUDE_IDLE_PREFIX) || title.startsWith('* ') || title.includes(GEMINI_IDLE_PREFIX) || title.startsWith(PI_IDLE_PREFIX) ) { return 'idle' } return null } function isKnownReadyPromptPreview(preview: string): boolean { const normalized = preview.toLowerCase() const readyIndex = findKnownReadyPromptIndex(normalized) if (readyIndex === null) { return false } const blockedSignal = findTerminalWaitBlockedSignal(normalized) if (blockedSignal !== null && blockedSignal.index > readyIndex) { return false } return true } function detectTerminalWaitBlockedReason(preview: string): RuntimeTerminalWaitBlockedReason | null { const normalized = preview.toLowerCase() return findActionableTerminalWaitBlockedSignal(normalized)?.reason ?? null } function nextTailHasNewerBlockedReason( previousWaitText: string, nextWaitText: string, appendedText: string ): boolean { const nextBlockedSignal = findActionableTerminalWaitBlockedSignal(nextWaitText.toLowerCase()) if (!nextBlockedSignal) { return false } // Why: permission prompts can arrive split across PTY chunks. Stamp the // blocked signal when the accumulated tail first becomes blocked, or when // a later prompt appears after stale blocked text already in the tail. const previousBlockedSignal = findActionableTerminalWaitBlockedSignal( previousWaitText.toLowerCase() ) if (previousBlockedSignal === null) { return true } const appendCandidateSignal = findActionableTerminalWaitBlockedSignal( `${previousWaitText}${appendedText}`.toLowerCase() ) return appendCandidateSignal !== null && appendCandidateSignal.index > previousBlockedSignal.index } function findActionableTerminalWaitBlockedSignal( normalized: string ): { reason: RuntimeTerminalWaitBlockedReason; index: number } | null { const blockedSignal = findTerminalWaitBlockedSignal(normalized) if (blockedSignal === null) { return null } const readyIndex = findKnownReadyPromptIndex(normalized) // Why: retained terminal tails can include stale startup modals. If a known // ready prompt appears after that modal, the latest signal is ready. return readyIndex !== null && readyIndex > blockedSignal.index ? null : blockedSignal } function findKnownReadyPromptIndex(normalized: string): number | null { const indexes = [ findCodexReadyPromptIndex(normalized), findAntigravityReadyPromptIndex(normalized) ].filter((index): index is number => index !== null) return indexes.length > 0 ? Math.max(...indexes) : null } function findCodexReadyPromptIndex(normalized: string): number | null { const headerIndex = normalized.lastIndexOf('openai codex') if (headerIndex === -1) { return null } const readySegment = normalized.slice(headerIndex) // Why: current Codex prints permissions only in YOLO mode. The stable ready // header is OpenAI Codex + model + directory. return readySegment.includes('model:') && readySegment.includes('directory:') ? headerIndex : null } function findAntigravityReadyPromptIndex(normalized: string): number | null { const headerIndex = normalized.lastIndexOf('antigravity cli') if (headerIndex === -1) { return null } let lineStart = headerIndex let modelIndex: number | null = null let promptIndex: number | null = null // Why: ready previews can include echoed pasted output after the header; // scan line bounds directly instead of splitting the whole terminal tail. for (let cursor = headerIndex; cursor <= normalized.length; cursor += 1) { if (cursor < normalized.length && normalized.charCodeAt(cursor) !== 10) { continue } let trimmedStart = lineStart let trimmedEnd = cursor while (trimmedStart < trimmedEnd && isTerminalWaitWhitespace(normalized, trimmedStart)) { trimmedStart += 1 } while (trimmedEnd > trimmedStart && isTerminalWaitWhitespace(normalized, trimmedEnd - 1)) { trimmedEnd -= 1 } if (lineStart > headerIndex && trimmedStart < trimmedEnd) { if (modelIndex === null && normalized.startsWith('gemini', trimmedStart)) { modelIndex = trimmedStart } if ( promptIndex === null && trimmedEnd - trimmedStart === 1 && normalized.charCodeAt(trimmedStart) === 62 ) { promptIndex = trimmedStart } } lineStart = cursor + 1 } return modelIndex !== null && promptIndex !== null ? Math.max(modelIndex, promptIndex) : null } function isTerminalWaitWhitespace(value: string, index: number): boolean { const code = value.charCodeAt(index) return code === 32 || (code >= 9 && code <= 13) } function findTerminalWaitBlockedSignal( normalized: string ): { reason: RuntimeTerminalWaitBlockedReason; index: number } | null { const candidates: { reason: RuntimeTerminalWaitBlockedReason; index: number }[] = [] const updateIndex = normalized.lastIndexOf('update available') if (updateIndex !== -1 && normalized.includes('press enter to continue', updateIndex)) { candidates.push({ reason: 'codex-update-prompt', index: updateIndex }) } const cwdIndex = normalized.lastIndexOf('choose working directory to') if (cwdIndex !== -1 && normalized.includes('press enter to continue', cwdIndex)) { candidates.push({ reason: 'codex-cwd-prompt', index: cwdIndex }) } const modelMigrationIndex = normalized.lastIndexOf('codex just got an upgrade') if ( modelMigrationIndex !== -1 && normalized.includes('press enter to continue', modelMigrationIndex) ) { candidates.push({ reason: 'codex-model-migration-prompt', index: modelMigrationIndex }) } const hooksIndex = normalized.lastIndexOf('hooks need review') if (hooksIndex !== -1 && normalized.includes('press enter to confirm', hooksIndex)) { candidates.push({ reason: 'codex-hooks-review-prompt', index: hooksIndex }) } const trustIndex = Math.max( normalized.lastIndexOf('do you trust'), normalized.lastIndexOf('trust this'), normalized.lastIndexOf('trusted workspace') ) const trustSegment = trustIndex === -1 ? '' : normalized.slice(trustIndex) if ( trustIndex !== -1 && (trustSegment.includes('workspace') || trustSegment.includes('folder') || trustSegment.includes('directory') || trustSegment.includes('repo')) ) { candidates.push({ reason: 'codex-trust-workspace', index: trustIndex }) } const interactivePromptIndex = Math.max( normalized.lastIndexOf('press enter to confirm'), normalized.lastIndexOf('press enter to continue'), normalized.lastIndexOf('press enter to view'), normalized.lastIndexOf('press enter to insert'), normalized.lastIndexOf('press t to trust') ) const interactivePromptContext = interactivePromptIndex === -1 ? '' : normalized.slice(Math.max(0, interactivePromptIndex - 600), interactivePromptIndex + 200) const hasCodexInteractiveContext = interactivePromptContext.includes('codex') || interactivePromptContext.includes('permission') || interactivePromptContext.includes('sandbox') || interactivePromptContext.includes('trust') || interactivePromptContext.includes('hook') if (interactivePromptIndex !== -1 && hasCodexInteractiveContext) { const contextStart = Math.max(0, interactivePromptIndex - 600) const hasSpecificPromptInContext = candidates.some( (candidate) => candidate.index >= contextStart && candidate.index <= interactivePromptIndex ) if (!hasSpecificPromptInContext) { candidates.push({ reason: 'codex-interactive-prompt', index: interactivePromptIndex }) } } return candidates.length > 0 ? candidates.reduce((latest, candidate) => candidate.index > latest.index ? candidate : latest ) : null } function buildTerminalWaitResult( handle: string, condition: RuntimeTerminalWaitCondition, leaf: RuntimeLeafRecord ): RuntimeTerminalWait { return buildTerminalWait(handle, condition, getTerminalState(leaf), leaf.lastExitCode) } function buildTerminalWaitBlockedResult( handle: string, condition: RuntimeTerminalWaitCondition, leaf: RuntimeLeafRecord, blockedReason: RuntimeTerminalWaitBlockedReason ): RuntimeTerminalWait { return buildTerminalWait( handle, condition, getTerminalState(leaf), leaf.lastExitCode, blockedReason ) } function buildPtyTerminalWaitResult( handle: string, condition: RuntimeTerminalWaitCondition, pty: RuntimePtyWorktreeRecord ): RuntimeTerminalWait { return buildTerminalWait(handle, condition, getPtyTerminalState(pty), pty.lastExitCode) } function buildPtyTerminalWaitBlockedResult( handle: string, condition: RuntimeTerminalWaitCondition, pty: RuntimePtyWorktreeRecord, blockedReason: RuntimeTerminalWaitBlockedReason ): RuntimeTerminalWait { return buildTerminalWait( handle, condition, getPtyTerminalState(pty), pty.lastExitCode, blockedReason ) } function buildTerminalWait( handle: string, condition: RuntimeTerminalWaitCondition, status: RuntimeTerminalState, exitCode: number | null, blockedReason?: RuntimeTerminalWaitBlockedReason ): RuntimeTerminalWait { return { handle, condition, satisfied: blockedReason === undefined, status, exitCode, ...(blockedReason ? { blockedReason } : {}) } } function getPtyTerminalState(pty: RuntimePtyWorktreeRecord): RuntimeTerminalState { return pty.connected ? 'running' : pty.lastExitCode !== null ? 'exited' : 'unknown' } function branchSelectorMatches(branch: string, selector: string): boolean { // Why: Git worktree data can report local branches as either `refs/heads/foo` // or `foo` depending on which plumbing path produced the record. Orca's // branch selectors should accept either form so newly created worktrees stay // discoverable without exposing internal ref-shape differences to users. return normalizeLocalBranchName(branch) === normalizeLocalBranchName(selector) } function runtimePathsEqual(left: string, right: string): boolean { return normalizeRuntimePathForComparison(left) === normalizeRuntimePathForComparison(right) } function inferWorktreeIdFromPtyId(ptyId: string): string | null { return parsePtySessionId(ptyId).worktreeId } function setsEqual(a: ReadonlySet, b: ReadonlySet): boolean { if (a.size !== b.size) { return false } for (const value of a) { if (!b.has(value)) { return false } } return true } function parseRuntimeWorktreeId( worktreeId: string ): { repoId: string; worktreePath: string } | null { const parsed = splitWorktreeId(worktreeId) if (!parsed?.repoId) { return null } if (!parsed.worktreePath) { return null } return parsed } function includeTargetResolvedWorktree( resolvedWorktrees: ResolvedWorktree[], targetWorktree: ResolvedWorktree | null ): ResolvedWorktree[] { if (!targetWorktree || resolvedWorktrees.some((worktree) => worktree.id === targetWorktree.id)) { return resolvedWorktrees } return [...resolvedWorktrees, targetWorktree] } function findResolvedWorktreeIdForPath( resolvedWorktrees: ResolvedWorktree[], cwd: string ): string | null { if (!cwd) { return null } const matches = resolvedWorktrees .filter((worktree) => isPathInsideOrEqual(worktree.path, cwd)) .sort((left, right) => right.path.length - left.path.length) return matches[0]?.id ?? null } function getLeafWorktreeStatus( leaf: RuntimeLeafRecord, tabTitle: string | null ): RuntimeWorktreeStatus { // Why: recompute from the live title each call so worktree.ps mirrors what // the desktop sidebar's getWorktreeStatus does (no sticky state). Prefer // the freshest pane/OSC title, then tab title. Falling back to lastAgentStatus // only when no title is available preserves a sensible signal for very fresh // leaves before any title has been observed. const titleCandidates = [ { title: leaf.paneTitle, updatedAt: leaf.paneTitleUpdatedAt }, { title: leaf.lastOscTitle, updatedAt: leaf.lastOscTitleAt }, { title: tabTitle, updatedAt: 0 } ] const latestTitle = getLatestAgentCandidateTitle(...titleCandidates) const detected = latestTitle ? detectAgentStatusFromTitle(latestTitle) : leaf.lastAgentStatus return getDetectedWorktreeStatus(detected, leaf.ptyId !== null) } function classifyLatestAgentTitle( ...titles: { title: string | null | undefined; updatedAt: number | null | undefined }[] ): 'agent' | 'management' | 'neutral' { return classifyAgentTitle(getLatestAgentCandidateTitle(...titles)) } function getLatestPtyTitle(pty: RuntimePtyWorktreeRecord): string | null { return getLatestAgentCandidateTitle( { title: pty.title, updatedAt: pty.titleUpdatedAt }, { title: pty.lastOscTitle, updatedAt: pty.lastOscTitleAt } ) } function getLatestLeafTitle(leaf: RuntimeLeafRecord, tabTitle: string | null): string | null { return getLatestAgentCandidateTitle( { title: leaf.paneTitle, updatedAt: leaf.paneTitleUpdatedAt }, { title: leaf.lastOscTitle, updatedAt: leaf.lastOscTitleAt }, { title: tabTitle, updatedAt: 0 } ) } function classifyAgentTitle(title: string | null): 'agent' | 'management' | 'neutral' { if (!title) { return 'neutral' } if (isClaudeManagementTitle(title)) { return 'management' } return detectAgentStatusFromTitle(title) !== null ? 'agent' : 'neutral' } function terminalTitleBlocksExplicitAgentStatus(title: string | null): boolean { if (!title) { return false } return isClaudeManagementTitle(title) || isShellProcess(title) } function getLatestAgentCandidateTitle( ...titles: { title: string | null | undefined; updatedAt: number | null | undefined }[] ): string | null { return getLatestAgentCandidateTitleInfo(...titles)?.title ?? null } function getLatestAgentCandidateTitleInfo( ...titles: { title: string | null | undefined; updatedAt: number | null | undefined }[] ): { title: string; updatedAt: number } | null { let latest: { title: string; updatedAt: number } | null = null for (const candidate of titles) { const title = candidate.title?.trim() if (!title) { continue } const updatedAt = candidate.updatedAt ?? 0 if (!latest || updatedAt > latest.updatedAt) { latest = { title, updatedAt } } } return latest } function getSavedTabWorktreeStatus(title: string, hasPty: boolean): RuntimeWorktreeStatus { return getDetectedWorktreeStatus(detectAgentStatusFromTitle(title), hasPty) } function getDetectedWorktreeStatus( detected: AgentStatus | null, hasPty: boolean ): RuntimeWorktreeStatus { if (detected === 'permission') { return 'permission' } if (detected === 'working') { return 'working' } return hasPty ? 'active' : 'inactive' } function mapExplicitAgentStateToRuntimeTerminalStatus( state: AgentStatusEntry['state'] ): NonNullable { switch (state) { case 'blocked': case 'waiting': return 'permission' case 'working': return 'working' case 'done': return 'idle' } } function mergeWorktreeStatus( current: RuntimeWorktreeStatus, next: RuntimeWorktreeStatus ): RuntimeWorktreeStatus { return WORKTREE_STATUS_PRIORITY[next] > WORKTREE_STATUS_PRIORITY[current] ? next : current } function normalizeTerminalChunk( chunk: string, pendingAnsi: string = '' ): { text: string; pendingAnsi: string } { // Why: most high-throughput PTY chunks are plain printable text. Avoid // running every ANSI/OSC regex over megabytes that do not need normalization. if (pendingAnsi.length === 0 && !terminalChunkNeedsNormalization(chunk)) { return { text: chunk, pendingAnsi: '' } } const combined = `${pendingAnsi}${chunk}` const parts: string[] = [] let textStart = 0 for (let index = 0; index < combined.length; index += 1) { const char = combined[index] if (char === '\x1b') { appendTerminalNormalizedSpan(parts, combined, textStart, index) if (index + 1 >= combined.length) { return { text: parts.join(''), pendingAnsi: combined.slice(index) } } const parsed = parseAnsiControlSequence(combined, index) if (!parsed) { return { text: parts.join(''), pendingAnsi: trimPendingAnsiControl(combined.slice(index)) } } if (parsed.kind === 'csi' && isTerminalPreviewLineControl(parsed)) { // Why: Codex can redraw status text with ANSI controls but no CR; keep // those controls so the tail buffer overwrites the previous frame. parts.push(combined.slice(index, parsed.endIndex + 1)) } index = parsed.endIndex textStart = index + 1 continue } if (char === '\r' && combined[index + 1] === '\n') { appendTerminalNormalizedSpan(parts, combined, textStart, index) parts.push('\n') index += 1 textStart = index + 1 continue } const code = combined.charCodeAt(index) if (code === 0x08 || code === 0x09 || code === 0x0a || code === 0x0d) { appendTerminalNormalizedSpan(parts, combined, textStart, index) parts.push(char) textStart = index + 1 } else if (!isTerminalPreviewPrintableCodeUnit(code)) { appendTerminalNormalizedSpan(parts, combined, textStart, index) textStart = index + 1 } } appendTerminalNormalizedSpan(parts, combined, textStart, combined.length) return { text: parts.join(''), pendingAnsi: '' } } function appendTerminalNormalizedSpan( parts: string[], value: string, start: number, end: number ): void { if (end > start) { parts.push(value.slice(start, end)) } } function isTerminalPreviewPrintableCodeUnit(code: number): boolean { return code >= 0x20 && code !== 0x7f && (code < 0x80 || code > 0x9f) } function terminalChunkNeedsNormalization(chunk: string): boolean { for (let index = 0; index < chunk.length; index++) { const code = chunk.charCodeAt(index) if ( code === 0x1b || code === 0x7f || code === 0x0d || code < 0x09 || (code > 0x0a && code < 0x20) || (code >= 0x80 && code <= 0x9f) ) { return true } } return false } function trimPendingAnsiControl(value: string): string { if (value.length <= MAX_TAIL_PENDING_ANSI_CHARS) { return value } const introducer = value.slice(0, Math.min(2, value.length)) const suffixBudget = Math.max(0, MAX_TAIL_PENDING_ANSI_CHARS - introducer.length) return `${introducer}${value.slice(-suffixBudget)}` } function isTerminalPreviewLineControl(parsed: { final: string params: string firstParam: number | null }): boolean { if (!hasCanonicalNumericCsiParams(parsed.params)) { return false } if (parsed.final === 'K') { const mode = parsed.firstParam ?? 0 return mode === 0 || mode === 1 || mode === 2 } return ( parsed.final === 'A' || parsed.final === 'G' || parsed.final === '`' || parsed.final === 'D' || parsed.final === 'C' ) } function maxTimestamp(left: number | null, right: number | null): number | null { if (left === null) { return right } if (right === null) { return left } return Math.max(left, right) } function compareWorktreePs( left: RuntimeWorktreePsSummary, right: RuntimeWorktreePsSummary ): number { // Pinned and unread worktrees sort above others so they survive truncation. if (left.isPinned !== right.isPinned) { return left.isPinned ? -1 : 1 } if (left.unread !== right.unread) { return left.unread ? -1 : 1 } const leftLast = left.lastOutputAt ?? -1 const rightLast = right.lastOutputAt ?? -1 if (leftLast !== rightLast) { return rightLast - leftLast } if (left.liveTerminalCount !== right.liveTerminalCount) { return right.liveTerminalCount - left.liveTerminalCount } return left.path.localeCompare(right.path) }